GtkDialog
<!-- ##### SECTION Short_Description ##### -->
-
-create popup windows.
+Create popup windows
<!-- ##### SECTION Long_Description ##### -->
+
<para>
Dialog boxes are a convenient way to prompt the user for a small amount of
-input, eg. to display
-a message, ask a question, or anything else that does not require extensive
-effort on the user's part.
+input, e.g. to display a message, ask a question, or anything else that does
+not require extensive effort on the user's part.
</para>
+
<para>
-Gtk+ treats a dialog as a window split horizontally. The top section is a
-#GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should be
-packed. The second area is known as the <structfield>action_area</structfield>. This is generally used
-for packing buttons into the dialog which may perform functions such as cancel, ok, or apply. The two
-areas are separated by a #GtkHSeparator.
+GTK+ treats a dialog as a window split vertically. The top section is a
+#GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should
+be packed. The bottom area is known as the
+<structfield>action_area</structfield>. This is generally used for
+packing buttons into the dialog which may perform functions such as
+cancel, ok, or apply. The two areas are separated by a #GtkHSeparator.
</para>
+
<para>
-#GtkDialog boxes are created with a call to gtk_dialog_new().
+#GtkDialog boxes 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.
</para>
+
<para>
If 'dialog' is a newly created dialog, the two primary areas of the window
-can be accessed as GTK_DIALOG(dialog)->vbox and GTK_DIALOG(dialog)->action_area,
-as can be seen from the example, below.
+can be accessed through gtk_dialog_get_content_area() and
+gtk_dialog_get_action_area(), as can be seen from the example, below.
+</para>
+
+<para>
+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.
+</para>
+
+<para>
+If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(),
+gtk_dialog_add_button(), gtk_dialog_add_buttons(), or
+gtk_dialog_add_action_widget(), clicking the button will emit a signal called
+"response" 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 "response" signal will be emitted with a response ID of #GTK_RESPONSE_DELETE_EVENT.
</para>
+
+
<para>
-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.
+If you want to block waiting for a dialog to return before returning control
+flow to your code, you can call gtk_dialog_run(). This function enters a
+recursive main loop and waits for the user to respond to the dialog, returning the
+response ID corresponding to the button the user clicked.
</para>
+
<para>
+For the simple dialog in the following example, in reality you'd probably use
+#GtkMessageDialog to save yourself some effort. But you'd need to create the
+dialog contents manually if you had more than a simple message in the dialog.
<example>
-<title>Using a #GtkDialog to keep the user informed.</title>
+<title>Simple <structname>GtkDialog</structname> usage.</title>
<programlisting>
/* Function to open a dialog box displaying the message provided. */
-void quick_message(#gchar *message) {
+void quick_message (gchar *message) {
- #GtkWidget *dialog, *label, *okay_button;
+ GtkWidget *dialog, *label, *content_area;
/* Create the widgets */
- dialog = gtk_dialog_new();
+ dialog = gtk_dialog_new_with_buttons ("Message",
+ main_application_window,
+ GTK_DIALOG_DESTROY_WITH_PARENT,
+ GTK_STOCK_OK,
+ GTK_RESPONSE_NONE,
+ NULL);
+ content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
label = gtk_label_new (message);
- okay_button = gtk_button_new_with_label("Okay");
- /* Ensure that the dialog box is destroyed when the user clicks ok. */
+ /* Ensure that the dialog box is destroyed when the user responds. */
- gtk_signal_connect_object (GTK_OBJECT (okay_button), "clicked",
- GTK_SIGNAL_FUNC (gtk_widget_destroy), dialog);
- gtk_container_add (GTK_CONTAINER (GTK_DIALOG(dialog)->action_area),
- okay_button);
+ g_signal_connect_swapped (dialog,
+ "response",
+ G_CALLBACK (gtk_widget_destroy),
+ dialog);
/* Add the label, and show everything we've added to the dialog. */
- gtk_container_add (GTK_CONTAINER (GTK_DIALOG(dialog)->vbox),
- label);
+ gtk_container_add (GTK_CONTAINER (content_area), label);
gtk_widget_show_all (dialog);
}
</example>
</para>
+<refsect2 id="GtkDialog-BUILDER-UI"><title>GtkDialog as GtkBuildable</title>
+<para>
+The GtkDialog implementation of the GtkBuildable interface exposes the
+@vbox and @action_area as internal children with the names "vbox" and
+"action_area".
+</para>
+<para>
+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).
+</para>
+<example>
+<title>A <structname>GtkDialog</structname> UI definition fragment.</title>
+<programlisting><![CDATA[
+<object class="GtkDialog" id="dialog1">
+ <child internal-child="vbox">"
+ <object class="GtkVBox" id="vbox">
+ <child internal-child="action_area">
+ <object class="GtkHButtonBox" id="button_box">
+ <child>
+ <object class="GtkButton" id="button_cancel"/>
+ </child>
+ <child>
+ <object class="GtkButton" id="button_ok"/>
+ </child>
+ </object>
+ </child>
+ </object>
+ </child>
+ <action-widgets>
+ <action-widget response="3">button_ok</action-widget>
+ <action-widget response="-5">button_cancel</action-widget>
+ </action-widgets>
+</object>
+]]></programlisting>
+</example>
+</refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
</variablelist>
</para>
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
<!-- ##### STRUCT GtkDialog ##### -->
<para>
-<structfield>window</structfield> is a #GtkWindow, but should not be
-modified directly, (use the functions provided, such as
-gtk_window_set_title(). See the #GtkWindow section for more).
+<structfield>vbox</structfield> is a #GtkVBox - the main part of the
+dialog box.
+</para>
+
+<para>
+<structfield>action_area</structfield> is a #GtkHButtonBox packed below the
+dividing #GtkHSeparator in the dialog. It is treated exactly the same
+as any other #GtkHButtonBox.
+</para>
+
+
+<!-- ##### SIGNAL GtkDialog::close ##### -->
+<para>
+
+</para>
+
+@dialog: the object which received the signal.
+
+<!-- ##### SIGNAL GtkDialog::response ##### -->
+<para>
+
+</para>
+
+@dialog:
+@arg1:
+
+<!-- ##### ARG GtkDialog:has-separator ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkDialog:action-area-border ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkDialog:button-spacing ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GtkDialog:content-area-border ##### -->
+<para>
+
</para>
+
+<!-- ##### ARG GtkDialog:content-area-spacing ##### -->
<para>
-<structfield>vbox</structfield> is a #GtkVBox - the main part of the dialog box.
+
</para>
+
+<!-- ##### ENUM GtkDialogFlags ##### -->
<para>
-<structfield>action_area</structfield> is a #GtkHBox packed below the dividing #GtkHSeparator in the dialog. It is treated exactly the same as any other #GtkHBox.
+Flags used to influence dialog construction.
</para>
+@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_NO_SEPARATOR: Don't put a separator between the
+ action area and the dialog content.
-<!-- ##### STRUCT GtkDialogButton ##### -->
+<!-- ##### ENUM GtkResponseType ##### -->
<para>
-Deprecated.
+Predefined values for use as response ids in gtk_dialog_add_button().
+All predefined values are negative, GTK+ leaves positive values for
+application-defined response ids.
</para>
+@GTK_RESPONSE_NONE: Returned if an action widget has no response id, or if
+ the dialog gets programmatically hidden or destroyed.
+@GTK_RESPONSE_REJECT: Generic response id, not used by GTK+ dialogs.
+@GTK_RESPONSE_ACCEPT: Generic response id, not used by GTK+ dialogs.
+@GTK_RESPONSE_DELETE_EVENT: Returned if the dialog is deleted.
+@GTK_RESPONSE_OK: Returned by OK buttons in GTK+ dialogs.
+@GTK_RESPONSE_CANCEL: Returned by Cancel buttons in GTK+ dialogs.
+@GTK_RESPONSE_CLOSE: Returned by Close buttons in GTK+ dialogs.
+@GTK_RESPONSE_YES: Returned by Yes buttons in GTK+ dialogs.
+@GTK_RESPONSE_NO: Returned by No buttons in GTK+ dialogs.
+@GTK_RESPONSE_APPLY: Returned by Apply buttons in GTK+ dialogs.
+@GTK_RESPONSE_HELP: Returned by Help buttons in GTK+ dialogs.
<!-- ##### FUNCTION gtk_dialog_new ##### -->
<para>
Creates a new dialog box. Widgets should not be packed into this #GtkWindow
-directly, but into the vbox and action_area, as described above.
+directly, but into the @vbox and @action_area, as described above.
+</para>
+
+@void:
+@Returns: a new #GtkDialog.
+
+
+<!-- ##### FUNCTION gtk_dialog_new_with_buttons ##### -->
+<para>
+
+</para>
+
+@title:
+@parent:
+@flags:
+@first_button_text:
+@Varargs:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_dialog_run ##### -->
+<para>
+
+</para>
+
+@dialog:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_dialog_response ##### -->
+<para>
+
+</para>
+
+@dialog:
+@response_id:
+
+
+<!-- ##### FUNCTION gtk_dialog_add_button ##### -->
+<para>
+
+</para>
+
+@dialog:
+@button_text:
+@response_id:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_dialog_add_buttons ##### -->
+<para>
+
+</para>
+
+@dialog:
+@first_button_text:
+@Varargs:
+
+
+<!-- ##### FUNCTION gtk_dialog_add_action_widget ##### -->
+<para>
+
+</para>
+
+@dialog:
+@child:
+@response_id:
+
+
+<!-- ##### FUNCTION gtk_dialog_get_has_separator ##### -->
+<para>
+
+</para>
+
+@dialog:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_dialog_set_default_response ##### -->
+<para>
+
+</para>
+
+@dialog:
+@response_id:
+
+
+<!-- ##### FUNCTION gtk_dialog_set_has_separator ##### -->
+<para>
+
+</para>
+
+@dialog:
+@setting:
+
+
+<!-- ##### FUNCTION gtk_dialog_set_response_sensitive ##### -->
+<para>
+
+</para>
+
+@dialog:
+@response_id:
+@setting:
+
+
+<!-- ##### FUNCTION gtk_dialog_get_response_for_widget ##### -->
+<para>
+
+</para>
+
+@dialog:
+@widget:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_dialog_get_widget_for_response ##### -->
+<para>
+
+</para>
+
+@dialog:
+@response_id:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_dialog_get_action_area ##### -->
+<para>
+
+</para>
+
+@dialog:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_dialog_get_content_area ##### -->
+<para>
+
+</para>
+
+@dialog:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_alternative_dialog_button_order ##### -->
+<para>
+
+</para>
+
+@screen:
+@Returns:
+
+
+<!-- ##### FUNCTION gtk_dialog_set_alternative_button_order ##### -->
+<para>
+
+</para>
+
+@dialog:
+@first_response_id:
+@Varargs:
+
+
+<!-- ##### FUNCTION gtk_dialog_set_alternative_button_order_from_array ##### -->
+<para>
+
</para>
-@Returns: a #GtkWidget - the newly created dialog box.
+@dialog:
+@n_params:
+@new_order:
projects / ~andy / gtk / blobdiff