Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkdialog.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkDialog
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5
   6 create popup windows.
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9
  10 <para>
  11 Dialog boxes are a convenient way to prompt the user for a small amount of
  12 input, eg. to display a message, ask a question, or anything else that does not
  13 require extensive effort on the user's part.
  14 </para>
  15
  16 <para>
  17 GTK+ treats a dialog as a window split vertically. The top section is a
  18 #GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should
  19 be packed. The bottom area is known as the
  20 <structfield>action_area</structfield>. This is generally used for
  21 packing buttons into the dialog which may perform functions such as
  22 cancel, ok, or apply. The two areas are separated by a #GtkHSeparator.
  23 </para>
  24
  25 <para>
  26 #GtkDialog boxes are created with a call to gtk_dialog_new() or
  27 gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is recommended; it
  28 allows you to set the dialog title, some convenient flags, and add simple
  29 buttons.
  30 </para>
  31
  32 <para>
  33 If 'dialog' is a newly created dialog, the two primary areas of the window
  34 can be accessed as <literal>GTK_DIALOG(dialog)->vbox</literal> and
  35 <literal>GTK_DIALOG(dialog)->action_area</literal>,
  36 as can be seen from the example, below.
  37 </para>
  38
  39 <para>
  40 A 'modal' dialog (that is, one which freezes the rest of the application from
  41 user input), can be created by calling gtk_window_set_modal() on the dialog. Use
  42 the GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a
  43 #GtkWindow. When using gtk_dialog_new_with_buttons() you can also pass the
  44 #GTK_DIALOG_MODAL flag to make a dialog modal.
  45 </para>
  46
  47 <para>
  48 If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(),
  49 gtk_dialog_add_button(), gtk_dialog_add_buttons(), or
  50 gtk_dialog_add_action_widget(), clicking the button will emit a signal called
  51 "response" with a response ID that you specified. GTK+ will never assign a
  52 meaning to positive response IDs; these are entirely user-defined. But for
  53 convenience, you can use the response IDs in the #GtkResponseType enumeration
  54 (these all have values less than zero). If a dialog receives a delete event,
  55 the "response" signal will be emitted with a response ID of #GTK_RESPONSE_DELETE_EVENT.
  56 </para>
  57
  58
  59 <para>
  60 If you want to block waiting for a dialog to return before returning control
  61 flow to your code, you can call gtk_dialog_run(). This function enters a
  62 recursive main loop and waits for the user to respond to the dialog, returning the
  63 response ID corresponding to the button the user clicked.
  64 </para>
  65
  66 <para>
  67 For the simple dialog in the following example, in reality you'd probably use
  68 #GtkMessageDialog to save yourself some effort.  But you'd need to create the
  69 dialog contents manually if you had more than a simple message in the dialog.
  70 <example>
  71 <title>Simple <structname>GtkDialog</structname> usage.</title>
  72 <programlisting>
  73
  74 /* Function to open a dialog box displaying the message provided. */
  75
  76 void quick_message (gchar *message) {
  77
  78    GtkWidget *dialog, *label;
  79
  80    /* Create the widgets */
  81
  82    dialog = gtk_dialog_new_with_buttons ("Message",
  83                                          main_application_window,
  84                                          GTK_DIALOG_DESTROY_WITH_PARENT,
  85                                          GTK_STOCK_OK,
  86                                          GTK_RESPONSE_NONE,
  87                                          NULL);
  88    label = gtk_label_new (message);
  89
  90    /* Ensure that the dialog box is destroyed when the user responds. */
  91
  92    g_signal_connect_swapped (dialog,
  93                              "response",
  94                              G_CALLBACK (gtk_widget_destroy),
  95                              dialog);
  96
  97    /* Add the label, and show everything we've added to the dialog. */
  98
  99    gtk_container_add (GTK_CONTAINER (GTK_DIALOG(dialog)->vbox),
 100                       label);
 101    gtk_widget_show_all (dialog);
 102 }
 103
 104 </programlisting>
 105 </example>
 106 </para>
 107
 108 <!-- ##### SECTION See_Also ##### -->
 109
 110 <para>
 111 <variablelist>
 112 <varlistentry>
 113 <term>#GtkVBox</term>
 114 <listitem><para>Pack widgets vertically.</para></listitem>
 115 </varlistentry>
 116 <varlistentry>
 117 <term>#GtkWindow</term>
 118 <listitem><para>Alter the properties of your dialog box.</para></listitem>
 119 </varlistentry>
 120 <varlistentry>
 121 <term>#GtkButton</term>
 122 <listitem><para>Add them to the <structfield>action_area</structfield> to get a
 123 response from the user.</para></listitem>
 124 </varlistentry>
 125 </variablelist>
 126 </para>
 127
 128 <!-- ##### STRUCT GtkDialog ##### -->
 129 <para>
 130 <structfield>vbox</structfield> is a #GtkVBox - the main part of the
 131 dialog box.
 132 </para>
 133
 134 <para>
 135 <structfield>action_area</structfield> is a #GtkHButtonBox packed below the
 136 dividing #GtkHSeparator in the dialog. It is treated exactly the same
 137 as any other #GtkHButtonBox.
 138 </para>
 139
 140 @vbox:
 141 @action_area:
 142
 143 <!-- ##### SIGNAL GtkDialog::close ##### -->
 144 <para>
 145
 146 </para>
 147
 148 @dialog: the object which received the signal.
 149
 150 <!-- ##### SIGNAL GtkDialog::response ##### -->
 151 <para>
 152 Emitted when an action widget is clicked, the dialog receives a delete event, or
 153 the application programmer calls gtk_dialog_response(). On a delete event, the
 154 response ID is #GTK_RESPONSE_NONE. Otherwise, it depends on which action widget
 155 was clicked.
 156 </para>
 157
 158 @dialog: the object which received the signal.
 159 @arg1: the response ID
 160
 161 <!-- ##### ARG GtkDialog:has-separator ##### -->
 162 <para>
 163
 164 </para>
 165
 166 <!-- ##### ARG GtkDialog:action-area-border ##### -->
 167 <para>
 168
 169 </para>
 170
 171 <!-- ##### ARG GtkDialog:button-spacing ##### -->
 172 <para>
 173
 174 </para>
 175
 176 <!-- ##### ARG GtkDialog:content-area-border ##### -->
 177 <para>
 178
 179 </para>
 180
 181 <!-- ##### ENUM GtkDialogFlags ##### -->
 182 <para>
 183 Flags used to influence dialog construction.
 184 </para>
 185
 186 @GTK_DIALOG_MODAL: Make the constructed dialog modal,
 187   see gtk_widget_set_modal().
 188 @GTK_DIALOG_DESTROY_WITH_PARENT: Destroy the dialog when its
 189   parent is destroyed, see gtk_window_set_destroy_with_parent().
 190 @GTK_DIALOG_NO_SEPARATOR: Don't put a separator between the
 191   action area and the dialog content.
 192
 193 <!-- ##### ENUM GtkResponseType ##### -->
 194 <para>
 195 Predefined values for use as response ids in gtk_dialog_add_button().
 196 All predefined values are negative, GTK+ leaves positive values for
 197 application-defined response ids.
 198 </para>
 199
 200 @GTK_RESPONSE_NONE: Returned if an action widget has no response id, or if
 201    the dialog gets programmatically hidden or destroyed.
 202 @GTK_RESPONSE_REJECT: Generic response id, not used by GTK+ dialogs.
 203 @GTK_RESPONSE_ACCEPT: Generic response id, not used by GTK+ dialogs.
 204 @GTK_RESPONSE_DELETE_EVENT: Returned if the dialog is deleted.
 205 @GTK_RESPONSE_OK: Returned by OK buttons in GTK+ dialogs.
 206 @GTK_RESPONSE_CANCEL: Returned by Cancel buttons in GTK+ dialogs.
 207 @GTK_RESPONSE_CLOSE: Returned by Close buttons in GTK+ dialogs.
 208 @GTK_RESPONSE_YES: Returned by Yes buttons in GTK+ dialogs.
 209 @GTK_RESPONSE_NO: Returned by No buttons in GTK+ dialogs.
 210 @GTK_RESPONSE_APPLY: Returned by Apply buttons in GTK+ dialogs.
 211 @GTK_RESPONSE_HELP: Returned by Help buttons in GTK+ dialogs.
 212
 213 <!-- ##### FUNCTION gtk_dialog_new ##### -->
 214 <para>
 215 Creates a new dialog box. Widgets should not be packed into this #GtkWindow
 216 directly, but into the @vbox and @action_area, as described above.
 217 </para>
 218
 219 @Returns: a new #GtkDialog.
 220
 221
 222 <!-- ##### FUNCTION gtk_dialog_new_with_buttons ##### -->
 223 <para>
 224
 225 </para>
 226
 227 @title:
 228 @parent:
 229 @flags:
 230 @first_button_text:
 231 @Varargs:
 232 @Returns:
 233
 234
 235 <!-- ##### FUNCTION gtk_dialog_run ##### -->
 236 <para>
 237
 238 </para>
 239
 240 @dialog:
 241 @Returns:
 242
 243
 244 <!-- ##### FUNCTION gtk_dialog_response ##### -->
 245 <para>
 246
 247 </para>
 248
 249 @dialog:
 250 @response_id:
 251
 252
 253 <!-- ##### FUNCTION gtk_dialog_add_button ##### -->
 254 <para>
 255
 256 </para>
 257
 258 @dialog:
 259 @button_text:
 260 @response_id:
 261 @Returns:
 262
 263
 264 <!-- ##### FUNCTION gtk_dialog_add_buttons ##### -->
 265 <para>
 266
 267 </para>
 268
 269 @dialog:
 270 @first_button_text:
 271 @Varargs:
 272
 273
 274 <!-- ##### FUNCTION gtk_dialog_add_action_widget ##### -->
 275 <para>
 276
 277 </para>
 278
 279 @dialog:
 280 @child:
 281 @response_id:
 282 <!-- # Unused Parameters # -->
 283 @widget:
 284
 285
 286 <!-- ##### FUNCTION gtk_dialog_get_has_separator ##### -->
 287 <para>
 288
 289 </para>
 290
 291 @dialog:
 292 @Returns:
 293
 294
 295 <!-- ##### FUNCTION gtk_dialog_set_default_response ##### -->
 296 <para>
 297
 298 </para>
 299
 300 @dialog:
 301 @response_id:
 302
 303
 304 <!-- ##### FUNCTION gtk_dialog_set_has_separator ##### -->
 305 <para>
 306
 307 </para>
 308
 309 @dialog:
 310 @setting:
 311
 312
 313 <!-- ##### FUNCTION gtk_dialog_set_response_sensitive ##### -->
 314 <para>
 315
 316 </para>
 317
 318 @dialog:
 319 @response_id:
 320 @setting:
 321
 322