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>
<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>
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.
+#GTK_DIALOG_MODAL flag to make a dialog modal.
</para>
<para>
"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_NONE.
+(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>
#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>Simple #GtkDialog usage.</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;
+ GtkWidget *dialog, *label, *content_area;
/* Create the widgets */
dialog = gtk_dialog_new_with_buttons ("Message",
main_application_window,
GTK_DIALOG_DESTROY_WITH_PARENT,
- GTK_STOCK_BUTTON_OK,
+ GTK_STOCK_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. */
- gtk_signal_connect_object (GTK_OBJECT (dialog), "response",
- GTK_SIGNAL_FUNC (gtk_widget_destroy),
- GTK_OBJECT (dialog));
+ 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>vbox</structfield> is a #GtkVBox - the main part of the dialog box.
+<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>
-<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.
+
</para>
+@dialog: the object which received the signal.
-<!-- ##### ENUM GtkDialogFlags ##### -->
+<!-- ##### SIGNAL GtkDialog::response ##### -->
<para>
</para>
-@GTK_DIALOG_MODAL:
-@GTK_DIALOG_DESTROY_WITH_PARENT:
-@GTK_DIALOG_NO_SEPARATOR:
+@dialog:
+@arg1:
-<!-- ##### ENUM GtkResponseType ##### -->
+<!-- ##### ARG GtkDialog:has-separator ##### -->
<para>
</para>
-@GTK_RESPONSE_NONE:
-@GTK_RESPONSE_REJECT:
-@GTK_RESPONSE_ACCEPT:
-@GTK_RESPONSE_DELETE_EVENT:
-@GTK_RESPONSE_OK:
-@GTK_RESPONSE_CANCEL:
-@GTK_RESPONSE_CLOSE:
-@GTK_RESPONSE_YES:
-@GTK_RESPONSE_NO:
-@GTK_RESPONSE_APPLY:
-@GTK_RESPONSE_HELP:
+<!-- ##### 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>
+
+</para>
+
+<!-- ##### ENUM GtkDialogFlags ##### -->
+<para>
+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.
+
+<!-- ##### ENUM GtkResponseType ##### -->
+<para>
+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>
-@Returns: a #GtkWidget - the newly created dialog box.
+@void:
+@Returns: a new #GtkDialog.
<!-- ##### FUNCTION gtk_dialog_new_with_buttons ##### -->
@dialog:
@child:
@response_id:
-<!-- # Unused Parameters # -->
-@widget:
<!-- ##### FUNCTION gtk_dialog_get_has_separator ##### -->
@setting:
-<!-- ##### SIGNAL GtkDialog::close ##### -->
+<!-- ##### FUNCTION gtk_dialog_get_response_for_widget ##### -->
<para>
</para>
-@dialog: the object which received the signal.
+@dialog:
+@widget:
+@Returns:
-<!-- ##### SIGNAL GtkDialog::response ##### -->
+
+<!-- ##### FUNCTION gtk_dialog_get_widget_for_response ##### -->
<para>
-Emitted when an action widget is clicked, the dialog receives a delete event, or
-the application programmer calls gtk_dialog_response(). On a delete event, the
-response ID is GTK_RESPONSE_NONE. Otherwise, it depends on which action widget
-was clicked.
+
</para>
-@dialog: the object which received the signal.
-@arg1: the response ID
+@dialog:
+@response_id:
+@Returns:
-<!-- ##### ARG GtkDialog:has-separator ##### -->
+
+<!-- ##### 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>
+@dialog:
+@n_params:
+@new_order:
+
+
projects / ~andy / gtk / blobdiff