<!-- ##### SECTION Title ##### -->GtkDialog<!-- ##### SECTION Short_Description ##### -->Create popup windows<!-- ##### SECTION Long_Description ##### --><para>Dialog boxes are a convenient way to prompt the user for a small amount ofinput, 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 vertically. The top section is a#GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry shouldbe packed. The bottom area is known as the<structfield>action_area</structfield>. This is generally used forpacking buttons into the dialog which may perform functions such ascancel, ok, or apply. The two areas are separated by a #GtkHSeparator.</para><para>#GtkDialog boxes are created with a call to gtk_dialog_new() orgtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is recommended; itallows you to set the dialog title, some convenient flags, and add simplebuttons.</para><para>If 'dialog' is a newly created dialog, the two primary areas of the window can be accessed as <literal>GTK_DIALOG(dialog)->vbox</literal> and <literal>GTK_DIALOG(dialog)->action_area</literal>,as can be seen from the example, below.</para><para>A 'modal' dialog (that is, one which freezes the rest of the application fromuser input), can be created by calling gtk_window_set_modal() on the dialog. Usethe 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(), orgtk_dialog_add_action_widget(), clicking the button will emit a signal called"response" with a response ID that you specified. GTK+ will never assign ameaning to positive response IDs; these are entirely user-defined. But forconvenience, 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>If you want to block waiting for a dialog to return before returning controlflow to your code, you can call gtk_dialog_run(). This function enters arecursive 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 thedialog contents manually if you had more than a simple message in the dialog.<example><title>Simple <structname>GtkDialog</structname> usage.</title><programlisting>/* Function to open a dialog box displaying the message provided. */void quick_message (gchar *message) {   GtkWidget *dialog, *label;      /* Create the widgets */      dialog = gtk_dialog_new_with_buttons ("Message",                                         main_application_window,                                         GTK_DIALOG_DESTROY_WITH_PARENT,                                         GTK_STOCK_OK,                                         GTK_RESPONSE_NONE,                                         NULL);   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_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_widget_show_all (dialog);}</programlisting></example></para><!-- ##### SECTION See_Also ##### --><para><variablelist><varlistentry><term>#GtkVBox</term><listitem><para>Pack widgets vertically.</para></listitem></varlistentry><varlistentry><term>#GtkWindow</term><listitem><para>Alter the properties of your dialog box.</para></listitem></varlistentry><varlistentry><term>#GtkButton</term><listitem><para>Add them to the <structfield>action_area</structfield> to get aresponse from the user.</para></listitem></varlistentry></variablelist></para><!-- ##### SECTION Stability_Level ##### --><!-- ##### STRUCT GtkDialog ##### --><para><structfield>vbox</structfield> is a #GtkVBox - the main part of thedialog box.</para><para><structfield>action_area</structfield> is a #GtkHButtonBox packed below thedividing #GtkHSeparator in the dialog. It is treated exactly the sameas any other #GtkHButtonBox.</para>@vbox: @action_area: <!-- ##### SIGNAL GtkDialog::close ##### --><para></para>@dialog: the object which received the signal.<!-- ##### SIGNAL GtkDialog::response ##### --><para>Emitted when an action widget is clicked, the dialog receives a delete event, orthe application programmer calls gtk_dialog_response(). On a delete event, theresponse ID is #GTK_RESPONSE_NONE. Otherwise, it depends on which action widgetwas clicked.</para>@dialog: the object which received the signal.@arg1: the response ID<!-- ##### 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><!-- ##### ENUM GtkDialogFlags ##### --><para>Flags used to influence dialog construction.</para>@GTK_DIALOG_MODAL: Make the constructed dialog modal,   see gtk_widget_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 forapplication-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 #GtkWindowdirectly, but into the @vbox and @action_area, as described above. </para>@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: <!-- # Unused Parameters # -->@widget: <!-- ##### 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_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: