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

!An example GtkDialog

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 [gtk.dialog.Dialog] is called the "content area", and is yours to populate with widgets such a [gtk.label.Label] or [gtk.entry.Entry], 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 [gtk.dialog.Dialog] using [gtk.dialog.Dialog.newWithButtons], or use [gtk.dialog.Dialog.addButton], [gtk.dialog.Dialog.addButtons], or [gtk.dialog.Dialog.addActionWidget].

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.types.ResponseType.Close] or [gtk.types.ResponseType.Cancel], the close button is omitted.

Clicking a button that was added as an action widget will emit the [gtk.dialog.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 [gtk.types.ResponseType] enumeration (these all have values less than zero). If a dialog receives a delete event, the [gtk.dialog.Dialog.response] signal will be emitted with the [gtk.types.ResponseType.DeleteEvent] response ID.

Dialogs are created with a call to [gtk.dialog.Dialog.new_] or [gtk.dialog.Dialog.newWithButtons]. 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.Window.setModal] on the dialog. When using [gtk.dialog.Dialog.newWithButtons], you can also pass the [gtk.types.DialogFlags.Modal] flag to make a dialog modal.

For the simple dialog in the following example, a [gtk.message_dialog.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 [gtk.dialog.Dialog] usage:

// 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 [gtk.dialog.Dialog] implementation of the [gtk.buildable.Buildable] interface exposes the @content_area as an internal child with the name “content_area”.

[gtk.dialog.Dialog] 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.

[gtk.dialog.Dialog] 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 [gtk.dialog.Dialog] UI definition fragment:

<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

[gtk.dialog.Dialog] uses the [gtk.types.AccessibleRole.Dialog] role.

Fluent builder for [gtk.dialog.Dialog]