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 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.