Dialogs are a convenient way to prompt the user for a small amount of input.


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, create your `GtkDialog` using [[email protected]_with_buttons], or use [[email protected]_button], [[email protected]_buttons], or [ [email protected]_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 [[email protected]:GtkDialog: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 [[email protected]] enumeration (these all have values less than zero). If a dialog receives a delete event, the [[email protected]:GtkDialog:response] signal will be emitted with the gtk_response_delete_event response ID.

Dialogs are created with a call to [[email protected]] or [[email protected]_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 [ [email protected]_modal] on the dialog. When using [[email protected]_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 [[email protected]] 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:

```c // Function to open a dialog box with a message void quick_message (GtkWindow *parent, char *message) { GtkWidget *dialog, *label, *content_area; GtkDialogFlags flags;

// Create the widgets flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_dialog_new_with_buttons ("Message", parent, flags, _( "_OK"), GTK_RESPONSE_NONE, NULL); content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog)); label = gtk_label_new (message);

// Ensure that the dialog box is destroyed when the user responds

g_signal_connect_swapped (dialog, "response", G_CALLBACK (gtk_window_destroy), dialog);

// Add the label, and show everything we’ve added

gtk_box_append (GTK_BOX (content_area), label); gtk_widget_show (dialog); } ```

GtkDialog as GtkBuildable

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 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 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"/> </child> <child type="action"> <object class="GtkButton" id="button_ok"> </object> </child> < action-widgets> <action-widget response="cancel">button_cancel</action-widget> <action-widget response="ok" default="true">button_ok</action-widget> </action-widgets> </object> ```

Accessibility

`GtkDialog` uses the gtk_accessible_role_dialog role.