diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c index ad8a1e3116..934bd681f8 100644 --- a/gtk/gtkdialog.c +++ b/gtk/gtkdialog.c @@ -45,51 +45,57 @@ #include "gtksizegroup.h" /** - * SECTION:gtkdialog - * @Short_description: Create popup windows - * @Title: GtkDialog - * @See_also: #GtkWindow, #GtkMessageDialog + * GtkDialog: * * Dialogs are a convenient way to prompt the user for a small amount - * of input, e.g. to display a message, ask a question, or anything else + * of input. + * + * ![An example GtkDialog](dialog.png) + * + * Typical uses are to display a message, ask a question, or anything else * that does not require extensive effort on the user’s part. * - * The main area of a GtkDialog is called the "content area", and is yours - * to populate with widgets such a #GtkLabel or #GtkEntry, to present - * your information, questions, or tasks to the user. In addition, dialogs - * allow you to add "action widgets". Most commonly, action widgets are - * buttons. Depending on the platform, action widgets may be presented - * in the header bar at the top of the window, or at the bottom of the window. - * To add action widgets, use GtkDialog using gtk_dialog_new_with_buttons(), - * gtk_dialog_add_button(), gtk_dialog_add_buttons(), or - * gtk_dialog_add_action_widget(). + * The main area of a `GtkDialog` is called the "content area", and is yours + * to populate with widgets such a `GtkLabel` or `GtkEntry`, to present + * your information, questions, or tasks to the user. + * + * In addition, dialogs allow you to add "action widgets". Most commonly, + * action widgets are buttons. Depending on the platform, action widgets may + * be presented in the header bar at the top of the window, or at the bottom + * of the window. To add action widgets, create your `GtkDialog` using + * [ctor@Gtk.Dialog.new_with_buttons], or use + * [method@Gtk.Dialog.add_button], [method@Gtk.Dialog.add_buttons], + * or [method@Gtk.Dialog.add_action_widget]. + * + * `GtkDialogs` uses some heuristics to decide whether to add a close + * button to the window decorations. If any of the action buttons use + * the response ID %GTK_RESPONSE_CLOSE or %GTK_RESPONSE_CANCEL, the + * close button is omitted. * * Clicking a button that was added as an action widget will emit the - * #GtkDialog::response signal with a response ID that you specified. + * [signal@Gtk.Dialog::response] signal with a response ID that you specified. * GTK will never assign a meaning to positive response IDs; these are * entirely user-defined. But for convenience, you can use the response - * IDs in the #GtkResponseType enumeration (these all have values less - * than zero). If a dialog receives a delete event, the - * #GtkDialog::response signal will be emitted with the - * #GTK_RESPONSE_DELETE_EVENT response ID. + * IDs in the [enum@Gtk.ResponseType] enumeration (these all have values + * less than zero). If a dialog receives a delete event, the + * [signal@Gtk.Dialog::response] signal will be emitted with the + * %GTK_RESPONSE_DELETE_EVENT response ID. * - * Dialogs are created with a call to gtk_dialog_new() or - * gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is - * recommended; it allows you to set the dialog title, some convenient - * flags, and add simple buttons. + * Dialogs are created with a call to [ctor@Gtk.Dialog.new] or + * [ctor@Gtk.Dialog.new_with_buttons]. The latter is recommended; it allows + * you to set the dialog title, some convenient flags, and add buttons. * * A “modal” dialog (that is, one which freezes the rest of the application - * from user input), can be created by calling gtk_window_set_modal() on the - * dialog. Use the GTK_WINDOW() macro to cast the widget returned from - * gtk_dialog_new() into a #GtkWindow. When using gtk_dialog_new_with_buttons() - * you can also pass the #GTK_DIALOG_MODAL flag to make a dialog modal. + * from user input), can be created by calling [method@Gtk.Window.set_modal] + * on the dialog. When using [ctor@Gtk.Dialog.new_with_buttons], you can also + * pass the %GTK_DIALOG_MODAL flag to make a dialog modal. * - * For the simple dialog in the following example, a #GtkMessageDialog would - * save some effort. But you’d need to create the dialog contents manually if - * you had more than a simple message in the dialog. + * For the simple dialog in the following example, a [class@Gtk.MessageDialog] + * would save some effort. But you’d need to create the dialog contents manually + * if you had more than a simple message in the dialog. * - * An example for simple GtkDialog usage: - * |[ + * An example for simple `GtkDialog` usage: + * ```c * // Function to open a dialog box with a message * void * quick_message (GtkWindow *parent, char *message) @@ -120,28 +126,28 @@ * gtk_box_append (GTK_BOX (content_area), label); * gtk_widget_show (dialog); * } - * ]| + * ``` * * # GtkDialog as GtkBuildable * - * The GtkDialog implementation of the #GtkBuildable interface exposes the + * The `GtkDialog` implementation of the `GtkBuildable` interface exposes the * @content_area as an internal child with the name “content_area”. * - * GtkDialog supports a custom element, which can contain + * `GtkDialog` supports a custom element, which can contain * multiple elements. The “response” attribute specifies a * numeric response, and the content of the element is the id of widget * (which should be a child of the dialogs @action_area). To mark a response * as default, set the “default“ attribute of the element * to true. * - * GtkDialog supports adding action widgets by specifying “action“ as + * `GtkDialog` supports adding action widgets by specifying “action“ as * the “type“ attribute of a element. The widget will be added * either to the action area or the headerbar of the dialog, depending * on the “use-header-bar“ property. The response id has to be associated * with the action widget using the element. * * An example of a #GtkDialog UI definition fragment: - * |[ + * ```xml * * * @@ -155,11 +161,11 @@ * button_ok * * - * ]| + * ``` * * # Accessibility * - * GtkDialog uses the #GTK_ACCESSIBLE_ROLE_DIALOG role. + * `GtkDialog` uses the %GTK_ACCESSIBLE_ROLE_DIALOG role. */ typedef struct _ResponseData ResponseData; @@ -496,9 +502,11 @@ gtk_dialog_class_init (GtkDialogClass *class) * @dialog: the object on which the signal is emitted * @response_id: the response ID * - * Emitted when an action widget is clicked, the dialog receives a - * delete event, or the application programmer calls gtk_dialog_response(). - * On a delete event, the response ID is #GTK_RESPONSE_DELETE_EVENT. + * Emitted when an action widget is clicked. + * + * The signal is also emitted when the dialog receives a + * delete event, and when [method@Gtk.Dialog.response] is called. + * On a delete event, the response ID is %GTK_RESPONSE_DELETE_EVENT. * Otherwise, it depends on which action widget was clicked. */ dialog_signals[RESPONSE] = @@ -514,10 +522,9 @@ gtk_dialog_class_init (GtkDialogClass *class) /** * GtkDialog::close: * - * The ::close signal is a - * [keybinding signal][GtkSignalAction] - * which gets emitted when the user uses a keybinding to close - * the dialog. + * Emitted when the user uses a keybinding to close the dialog. + * + * This is a [keybinding signal](class.SignalAction.html). * * The default binding for this signal is the Escape key. */ @@ -533,11 +540,24 @@ gtk_dialog_class_init (GtkDialogClass *class) /** * GtkDialog:use-header-bar: * - * %TRUE if the dialog uses a #GtkHeaderBar for action buttons + * %TRUE if the dialog uses a headerbar for action buttons * instead of the action-area. * * For technical reasons, this property is declared as an integer * property, but you should only set it to %TRUE or %FALSE. + * + * ## Creating a dialog with headerbar + * + * Builtin `GtkDialog` subclasses such as [class@Gtk.ColorChooserDialog] + * set this property according to platform conventions (using the + * [property@Gtk.Settings:gtk-dialogs-use-header] setting). + * + * Here is how you can achieve the same: + * + * ```c + * g_object_get (settings, "gtk-dialogs-use-header", &header, NULL); + * dialog = g_object_new (GTK_TYPE_DIALOG, header, TRUE, NULL); + * ``` */ g_object_class_install_property (gobject_class, PROP_USE_HEADER_BAR, @@ -664,10 +684,11 @@ gtk_dialog_close (GtkDialog *dialog) * * Creates a new dialog box. * - * Widgets should not be packed into this #GtkWindow - * directly, but into the @content_area and @action_area, as described above. + * Widgets should not be packed into the `GtkWindow` + * directly, but into the @content_area and @action_area, + * as described above. * - * Returns: the new dialog as a #GtkWidget + * Returns: the new dialog as a `GtkWidget` */ GtkWidget* gtk_dialog_new (void) @@ -705,44 +726,45 @@ gtk_dialog_new_empty (const char *title, * gtk_dialog_new_with_buttons: * @title: (allow-none): Title of the dialog, or %NULL * @parent: (allow-none): Transient parent of the dialog, or %NULL - * @flags: from #GtkDialogFlags + * @flags: from `GtkDialogFlags` * @first_button_text: (allow-none): text to go in first button, or %NULL * @...: response ID for first button, then additional buttons, ending with %NULL * - * Creates a new #GtkDialog with title @title (or %NULL for the default - * title; see gtk_window_set_title()) and transient parent @parent (or - * %NULL for none; see gtk_window_set_transient_for()). The @flags - * argument can be used to make the dialog modal (#GTK_DIALOG_MODAL) - * and/or to have it destroyed along with its transient parent - * (#GTK_DIALOG_DESTROY_WITH_PARENT). After @flags, button - * text/response ID pairs should be listed, with a %NULL pointer ending - * the list. Button text can be arbitrary text. A response ID can be - * any positive number, or one of the values in the #GtkResponseType - * enumeration. If the user clicks one of these dialog buttons, - * #GtkDialog will emit the #GtkDialog::response signal with the corresponding - * response ID. If a #GtkDialog receives a delete event, - * it will emit ::response with a response ID of #GTK_RESPONSE_DELETE_EVENT. + * Creates a new `GtkDialog` with the given title and transient parent. + * + * The @flags argument can be used to make the dialog modal, have it + * destroyed along with its transient parent, or make it use a headerbar. + * + * Button text/response ID pairs should be listed in pairs, with a %NULL + * pointer ending the list. Button text can be arbitrary text. A response + * ID can be any positive number, or one of the values in the + * [enum@Gtk.ResponseType] enumeration. If the user clicks one of these + * buttons, `GtkDialog` will emit the [signal@Gtk.Dialog::response] signal + * with the corresponding response ID. + * + * If a `GtkDialog` receives a delete event, it will emit ::response with a + * response ID of %GTK_RESPONSE_DELETE_EVENT. + * * However, destroying a dialog does not emit the ::response signal; * so be careful relying on ::response when using the - * #GTK_DIALOG_DESTROY_WITH_PARENT flag. Buttons are from left to right, - * so the first button in the list will be the leftmost button in the dialog. + * %GTK_DIALOG_DESTROY_WITH_PARENT flag. * * Here’s a simple example: - * |[ - * GtkWindow *main_app_window; // Window the dialog should show up on - * GtkWidget *dialog; - * GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT; - * dialog = gtk_dialog_new_with_buttons ("My dialog", - * main_app_window, - * flags, - * _("_OK"), - * GTK_RESPONSE_ACCEPT, - * _("_Cancel"), - * GTK_RESPONSE_REJECT, - * NULL); - * ]| + * ```c + * GtkWindow *main_app_window; // Window the dialog should show up on + * GtkWidget *dialog; + * GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT; + * dialog = gtk_dialog_new_with_buttons ("My dialog", + * main_app_window, + * flags, + * _("_OK"), + * GTK_RESPONSE_ACCEPT, + * _("_Cancel"), + * GTK_RESPONSE_REJECT, + * NULL); + * ``` * - * Returns: a new #GtkDialog + * Returns: a new `GtkDialog` */ GtkWidget* gtk_dialog_new_with_buttons (const char *title, @@ -821,17 +843,20 @@ get_response_data (GtkDialog *dialog, /** * gtk_dialog_add_action_widget: - * @dialog: a #GtkDialog + * @dialog: a `GtkDialog` * @child: an activatable widget * @response_id: response ID for @child * - * Adds an activatable widget to the action area of a #GtkDialog, - * connecting a signal handler that will emit the #GtkDialog::response - * signal on the dialog when the widget is activated. The widget is - * appended to the end of the dialog’s action area. If you want to add a - * non-activatable widget, simply pack it into the @action_area field - * of the #GtkDialog struct. - **/ + * Adds an activatable widget to the action area of a `GtkDialog`. + * + * GTK connects a signal handler that will emit the + * [signal@Gtk.Dialog::response] signal on the dialog when the widget + * is activated. The widget is appended to the end of the dialog’s action + * area. + * + * If you want to add a non-activatable widget, simply pack it into + * the @action_area field of the `GtkDialog` struct. + */ void gtk_dialog_add_action_widget (GtkDialog *dialog, GtkWidget *child, @@ -860,18 +885,19 @@ gtk_dialog_add_action_widget (GtkDialog *dialog, /** * gtk_dialog_add_button: - * @dialog: a #GtkDialog + * @dialog: a `GtkDialog` * @button_text: text of button * @response_id: response ID for the button * - * Adds a button with the given text and sets things up so that - * clicking the button will emit the #GtkDialog::response signal with - * the given @response_id. The button is appended to the end of the - * dialog’s action area. The button widget is returned, but usually - * you don’t need it. + * Adds a button with the given text. * - * Returns: (transfer none): the #GtkButton widget that was added - **/ + * GTK arranges things so that clicking the button will emit the + * [signal@Gtk.Dialog::response] signal with the given @response_id. + * The button is appended to the end of the dialog’s action area. + * The button widget is returned, but usually you don’t need it. + * + * Returns: (transfer none): the `GtkButton` widget that was added + */ GtkWidget* gtk_dialog_add_button (GtkDialog *dialog, const char *button_text, @@ -919,13 +945,15 @@ gtk_dialog_add_buttons_valist (GtkDialog *dialog, /** * gtk_dialog_add_buttons: - * @dialog: a #GtkDialog + * @dialog: a `GtkDialog` * @first_button_text: button text * @...: response ID for first button, then more text-response_id pairs * - * Adds more buttons, same as calling gtk_dialog_add_button() - * repeatedly. The variable argument list should be %NULL-terminated - * as with gtk_dialog_new_with_buttons(). Each button must have both + * Adds multiple buttons. + * + * This is the same as calling [method@Gtk.Dialog.add_button] + * repeatedly. The variable argument list should be %NULL-terminated + * as with [new@Gtk.Dialog.new_with_buttons]. Each button must have both * text and response ID. */ void @@ -946,14 +974,15 @@ gtk_dialog_add_buttons (GtkDialog *dialog, /** * gtk_dialog_set_response_sensitive: - * @dialog: a #GtkDialog + * @dialog: a `GtkDialog` * @response_id: a response ID * @setting: %TRUE for sensitive * + * A convenient way to sensitize/desensitize dialog buttons. + * * Calls `gtk_widget_set_sensitive (widget, @setting)` * for each widget in the dialog’s action area with the given @response_id. - * A convenient way to sensitize/desensitize dialog buttons. - **/ + */ void gtk_dialog_set_response_sensitive (GtkDialog *dialog, int response_id, @@ -973,13 +1002,13 @@ gtk_dialog_set_response_sensitive (GtkDialog *dialog, /** * gtk_dialog_set_default_response: - * @dialog: a #GtkDialog + * @dialog: a `GtkDialog` * @response_id: a response ID * - * Sets the last widget in the dialog’s action area with the given @response_id - * as the default widget for the dialog. Pressing “Enter” normally activates - * the default widget. - **/ + * Sets the default widget for the dialog based on the response ID. + * + * Pressing “Enter” normally activates the default widget. + */ void gtk_dialog_set_default_response (GtkDialog *dialog, int response_id) @@ -1000,14 +1029,14 @@ gtk_dialog_set_default_response (GtkDialog *dialog, } /** - * gtk_dialog_response: - * @dialog: a #GtkDialog + * gtk_dialog_response: (attributes org.gtk.Method.signal=response) + * @dialog: a `GtkDialog` * @response_id: response ID * - * Emits the #GtkDialog::response signal with the given response ID. + * Emits the ::response signal with the given response ID. * * Used to indicate that the user has responded to the dialog in some way. - **/ + */ void gtk_dialog_response (GtkDialog *dialog, int response_id) @@ -1022,7 +1051,7 @@ gtk_dialog_response (GtkDialog *dialog, /** * gtk_dialog_get_widget_for_response: - * @dialog: a #GtkDialog + * @dialog: a `GtkDialog` * @response_id: the response ID used by the @dialog widget * * Gets the widget button that uses the given response ID in the action area @@ -1051,7 +1080,7 @@ gtk_dialog_get_widget_for_response (GtkDialog *dialog, /** * gtk_dialog_get_response_for_widget: - * @dialog: a #GtkDialog + * @dialog: a `GtkDialog` * @widget: a widget in the action area of @dialog * * Gets the response id of a widget in the action area @@ -1360,11 +1389,12 @@ gtk_dialog_get_action_area (GtkDialog *dialog) /** * gtk_dialog_get_header_bar: - * @dialog: a #GtkDialog + * @dialog: a `GtkDialog` * - * Returns the header bar of @dialog. Note that the - * headerbar is only used by the dialog if the - * #GtkDialog:use-header-bar property is %TRUE. + * Returns the header bar of @dialog. + * + * Note that the headerbar is only used by the dialog if the + * [property@Gtk.Dialog:use-header-bar] property is %TRUE. * * Returns: (type Gtk.HeaderBar) (transfer none): the header bar */ @@ -1380,12 +1410,12 @@ gtk_dialog_get_header_bar (GtkDialog *dialog) /** * gtk_dialog_get_content_area: - * @dialog: a #GtkDialog + * @dialog: a `GtkDialog` * * Returns the content area of @dialog. * * Returns: (type Gtk.Box) (transfer none): the content area #GtkBox. - **/ + */ GtkWidget * gtk_dialog_get_content_area (GtkDialog *dialog) { diff --git a/gtk/gtkdialog.h b/gtk/gtkdialog.h index 3656d26157..b23c42ba13 100644 --- a/gtk/gtkdialog.h +++ b/gtk/gtkdialog.h @@ -35,10 +35,8 @@ G_BEGIN_DECLS /** * GtkDialogFlags: - * @GTK_DIALOG_MODAL: Make the constructed dialog modal, - * see gtk_window_set_modal() - * @GTK_DIALOG_DESTROY_WITH_PARENT: Destroy the dialog when its - * parent is destroyed, see gtk_window_set_destroy_with_parent() + * @GTK_DIALOG_MODAL: Make the constructed dialog modal + * @GTK_DIALOG_DESTROY_WITH_PARENT: Destroy the dialog when its parent is destroyed * @GTK_DIALOG_USE_HEADER_BAR: Create dialog with actions in header * bar instead of action area * @@ -67,6 +65,7 @@ typedef enum * @GTK_RESPONSE_HELP: Returned by Help buttons in GTK dialogs * * Predefined values for use as response ids in gtk_dialog_add_button(). + * * All predefined values are negative; GTK leaves values of 0 or greater for * application-defined response ids. */ @@ -97,12 +96,6 @@ typedef enum typedef struct _GtkDialog GtkDialog; typedef struct _GtkDialogClass GtkDialogClass; -/** - * GtkDialog: - * - * The #GtkDialog-struct contains only private fields - * and should not be directly accessed. - */ struct _GtkDialog { GtkWindow parent_instance;