Class
GtkDialog
deprecated: 4.10
Description [src]
class Gtk.Dialog : Gtk.Window
implements Gtk.Accessible, Gtk.Buildable, Gtk.ConstraintTarget, Gtk.Native, Gtk.Root, Gtk.ShortcutManager {
/* No available fields */
}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
gtk_dialog_new_with_buttons(), or use
gtk_dialog_add_button(), gtk_dialog_add_buttons(),
or 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.
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.
Dialogs are created with a call to gtk_dialog_new() or
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. When using 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.
An example for simple GtkDialog 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 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:
<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.
Deprecated since: 4.10
Use GtkWindow instead.
Descendants
Constructors
gtk_dialog_new_with_buttons
Creates a new GtkDialog with the given title and transient parent.
deprecated: 4.10
Instance methods
gtk_dialog_add_action_widget
Adds an activatable widget to the action area of a GtkDialog.
deprecated: 4.10
gtk_dialog_get_response_for_widget
Gets the response id of a widget in the action area of a dialog.
deprecated: 4.10
gtk_dialog_get_widget_for_response
Gets the widget button that uses the given response ID in the action area of a dialog.
deprecated: 4.10
gtk_dialog_set_default_response
Sets the default widget for the dialog based on the response ID.
deprecated: 4.10
gtk_dialog_set_response_sensitive
A convenient way to sensitize/desensitize dialog buttons.
deprecated: 4.10
Methods inherited from GtkAccessible (20)
Methods inherited from GtkBuildable (1)
Properties
Gtk.Dialog:use-header-bar
TRUE if the dialog uses a headerbar for action buttons
instead of the action-area.
deprecated: 4.10