[gtk/ebassi/run-dialog-run: 5/7] docs: Remove use of gtk_dialog_run()

[Emmanuele Bassi <ebassi src gnome org>]

commit 19f5cad112d20bbf6c6cf442bb07eab136316cbc
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Apr 30 14:05:23 2020 +0100

    docs: Remove use of gtk_dialog_run()

 gtk/gtkaboutdialog.c       |   5 +-
 gtk/gtkfilechooserdialog.c | 123 +++++++++++++++++++++++++++------------------
 gtk/gtkmessagedialog.c     |  30 ++++++-----
 3 files changed, 94 insertions(+), 64 deletions(-)
---
diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index 1c336316969..f1533066448 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -104,8 +104,9 @@
  * ]|
  *
  * It is also possible to show a #GtkAboutDialog like any other #GtkDialog,
- * e.g. using gtk_dialog_run(). In this case, you might need to know that
- * the “Close” button returns the #GTK_RESPONSE_CANCEL response id.
+ * and use the #GtkDialog::response signal to catch user responses. In this
+ * case, you might need to know that the “Close” button returns the
+ * %GTK_RESPONSE_CANCEL response id.
  */
 
 typedef struct
diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c
index 6ef46da6994..9dcc8b18bd2 100644
--- a/gtk/gtkfilechooserdialog.c
+++ b/gtk/gtkfilechooserdialog.c
@@ -69,61 +69,84 @@
  * #GtkFileChooserDialog to select a file for opening:
  *
  * |[
- * GtkWidget *dialog;
- * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
- * gint res;
- *
- * dialog = gtk_file_chooser_dialog_new ("Open File",
- *                                       parent_window,
- *                                       action,
- *                                       _("_Cancel"),
- *                                       GTK_RESPONSE_CANCEL,
- *                                       _("_Open"),
- *                                       GTK_RESPONSE_ACCEPT,
- *                                       NULL);
- *
- * res = gtk_dialog_run (GTK_DIALOG (dialog));
- * if (res == GTK_RESPONSE_ACCEPT)
- *   {
- *     GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);
- *     g_autoptr(GFile) filen = gtk_file_chooser_get_file (chooser);
- *     open_file (file);
- *   }
- *
- * gtk_widget_destroy (dialog);
+ * static void
+ * on_open_response (GtkDialog *dialog,
+ *                   int        response)
+ * {
+ *   if (response == GTK_RESPONSE_ACCEPT)
+ *     {
+ *       GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);
+ *
+ *       g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser);
+ *
+ *       open_file (file);
+ *     }
+ *
+ *   gtk_widget_destroy (GTK_WIDGET (dialog));
+ * }
+ *
+ *   // ...
+ *   GtkWidget *dialog;
+ *   GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
+ *
+ *   dialog = gtk_file_chooser_dialog_new ("Open File",
+ *                                         parent_window,
+ *                                         action,
+ *                                         _("_Cancel"),
+ *                                         GTK_RESPONSE_CANCEL,
+ *                                         _("_Open"),
+ *                                         GTK_RESPONSE_ACCEPT,
+ *                                         NULL);
+ *
+ *   gtk_widget_show (dialog);
+ *
+ *   g_signal_connect (dialog, "response",
+ *                     G_CALLBACK (on_open_response),
+ *                     NULL);
  * ]|
  *
  * To use a dialog for saving, you can use this:
  *
  * |[
- * GtkWidget *dialog;
- * GtkFileChooser *chooser;
- * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
- * gint res;
- *
- * dialog = gtk_file_chooser_dialog_new ("Save File",
- *                                       parent_window,
- *                                       action,
- *                                       _("_Cancel"),
- *                                       GTK_RESPONSE_CANCEL,
- *                                       _("_Save"),
- *                                       GTK_RESPONSE_ACCEPT,
- *                                       NULL);
- * chooser = GTK_FILE_CHOOSER (dialog);
- *
- * if (user_edited_a_new_document)
- *   gtk_file_chooser_set_current_name (chooser, _("Untitled document"));
- * else
- *   gtk_file_chooser_set_file (chooser, existing_filename);
- *
- * res = gtk_dialog_run (GTK_DIALOG (dialog));
- * if (res == GTK_RESPONSE_ACCEPT)
- *   {
- *     g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser);
- *     save_to_file (file);
- *   }
- *
- * gtk_widget_destroy (dialog);
+ * static void
+ * on_save_response (GtkDialog *dialog,
+ *                   int        response)
+ * {
+ *   if (response == GTK_RESPONSE_ACCEPT)
+ *     {
+ *       g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser);
+ *
+ *       save_to_file (file);
+ *     }
+ *
+ *   gtk_widget_destroy (GTK_WIDGET (dialog));
+ * }
+ *
+ *   // ...
+ *   GtkWidget *dialog;
+ *   GtkFileChooser *chooser;
+ *   GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
+ *
+ *   dialog = gtk_file_chooser_dialog_new ("Save File",
+ *                                         parent_window,
+ *                                         action,
+ *                                         _("_Cancel"),
+ *                                         GTK_RESPONSE_CANCEL,
+ *                                         _("_Save"),
+ *                                         GTK_RESPONSE_ACCEPT,
+ *                                         NULL);
+ *   chooser = GTK_FILE_CHOOSER (dialog);
+ *
+ *   if (user_edited_a_new_document)
+ *     gtk_file_chooser_set_current_name (chooser, _("Untitled document"));
+ *   else
+ *     gtk_file_chooser_set_file (chooser, existing_filename);
+ *
+ *   gtk_widget_show (dialog);
+ *
+ *   g_signal_connect (dialog, "response",
+ *                     G_CALLBACK (on_save_response),
+ *                     NULL);
  * ]|
  *
  * ## Setting up a file chooser dialog ## {#gtkfilechooserdialog-setting-up}
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index 5b434049b36..12c2493640b 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -49,14 +49,15 @@
  * convenience widget; you could construct the equivalent of #GtkMessageDialog
  * from #GtkDialog without too much effort, but #GtkMessageDialog saves typing.
  *
- * The easiest way to do a modal message dialog is to use gtk_dialog_run(), though
- * you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically
- * makes the dialog modal and waits for the user to respond to it. gtk_dialog_run()
- * returns when any dialog button is clicked.
+ * The easiest way to do a modal message dialog is to use the %GTK_DIALOG_MODAL
+ * flag, which will call gtk_window_set_modal() internally. The dialog will
+ * prevent interaction with the parent window until it's hidden or destroyed.
+ * You can use the #GtkDialog::response signal to know when the user dismissed
+ * the dialog.
  *
  * An example for using a modal dialog:
  * |[<!-- language="C" -->
- *  GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
+ *  GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT | GTK_DIALOG_MODAL;
  *  dialog = gtk_message_dialog_new (parent_window,
  *                                   flags,
  *                                   GTK_MESSAGE_ERROR,
@@ -64,13 +65,18 @@
  *                                   "Error reading “%s”: %s",
  *                                   filename,
  *                                   g_strerror (errno));
- *  gtk_dialog_run (GTK_DIALOG (dialog));
- *  gtk_widget_destroy (dialog);
+ *
+ *  // Destroy the dialog when the user responds to it
+ *  // (e.g. clicks a button)
+ *
+ *  g_signal_connect (dialog, "response",
+ *                    G_CALLBACK (gtk_widget_destroy),
+ *                    NULL);
  * ]|
  *
- * You might do a non-modal #GtkMessageDialog as follows:
+ * You might do a non-modal #GtkMessageDialog simply by omitting the
+ * %GTK_DIALOG_MODAL flag:
  *
- * An example for a non-modal dialog:
  * |[<!-- language="C" -->
  *  GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT;
  *  dialog = gtk_message_dialog_new (parent_window,
@@ -84,9 +90,9 @@
  *  // Destroy the dialog when the user responds to it
  *  // (e.g. clicks a button)
  *
- *  g_signal_connect_swapped (dialog, "response",
- *                            G_CALLBACK (gtk_widget_destroy),
- *                            dialog);
+ *  g_signal_connect (dialog, "response",
+ *                    G_CALLBACK (gtk_widget_destroy),
+ *                    NULL);
  * ]|
  *
  * # GtkMessageDialog as GtkBuildable