dialog: Convert docs

Convert links, add an example image, generally clean up docs.
This commit is contained in:
Matthias Clasen
2021-02-26 09:31:38 -05:00
committed by Emmanuele Bassi
parent a61c677a0d
commit b460ffd120
2 changed files with 153 additions and 130 deletions

View File

@@ -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 users 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 youd 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 youd need to create the dialog contents manually
* if you had more than a simple message in the dialog.
*
* An example for simple GtkDialog usage:
* |[<!-- language="C" -->
* 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 <action-widgets> element, which can contain
* `GtkDialog` supports a custom <action-widgets> element, which can contain
* multiple <action-widget> 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 <action-widget> 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 <child> 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 <action-widgets> element.
*
* An example of a #GtkDialog UI definition fragment:
* |[
* ```xml
* <object class="GtkDialog" id="dialog1">
* <child type="action">
* <object class="GtkButton" id="button_cancel"/>
@@ -155,11 +161,11 @@
* <action-widget response="ok" default="true">button_ok</action-widget>
* </action-widgets>
* </object>
* ]|
* ```
*
* # 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.
*
* Heres a simple example:
* |[<!-- language="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);
* ]|
* ```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 dialogs 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 dialogs 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
* dialogs action area. The button widget is returned, but usually
* you dont 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 dialogs action area.
* The button widget is returned, but usually you dont 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 dialogs 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 dialogs 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)
{

View File

@@ -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;