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, the
  55 "response" signal will be emitted with a response ID of #GTK_RESPONSE_NONE.
  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 (GTK_OBJECT (dialog),
  93                              "response",
  94                              G_CALLBACK (gtk_widget_destroy),
  95                              GTK_OBJECT (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>window</structfield> is a #GtkWindow, but should not be
 131 modified directly, (use the functions provided, such as
 132 gtk_window_set_title(). See the #GtkWindow section for more).
 133 </para>
 134 <para>
 135 <structfield>vbox</structfield> is a #GtkVBox - the main part of the dialog box.
 136 </para>
 137 <para>
 138 <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.
 139 </para>
 140
 141
 142 <!-- ##### ENUM GtkDialogFlags ##### -->
 143 <para>
 144
 145 </para>
 146
 147 @GTK_DIALOG_MODAL:
 148 @GTK_DIALOG_DESTROY_WITH_PARENT:
 149 @GTK_DIALOG_NO_SEPARATOR:
 150
 151 <!-- ##### ENUM GtkResponseType ##### -->
 152 <para>
 153
 154 </para>
 155
 156 @GTK_RESPONSE_NONE:
 157 @GTK_RESPONSE_REJECT:
 158 @GTK_RESPONSE_ACCEPT:
 159 @GTK_RESPONSE_DELETE_EVENT:
 160 @GTK_RESPONSE_OK:
 161 @GTK_RESPONSE_CANCEL:
 162 @GTK_RESPONSE_CLOSE:
 163 @GTK_RESPONSE_YES:
 164 @GTK_RESPONSE_NO:
 165 @GTK_RESPONSE_APPLY:
 166 @GTK_RESPONSE_HELP:
 167
 168 <!-- ##### FUNCTION gtk_dialog_new ##### -->
 169 <para>
 170 Creates a new dialog box. Widgets should not be packed into this #GtkWindow
 171 directly, but into the @vbox and @action_area, as described above.
 172 </para>
 173
 174 @Returns: a new #GtkDialog.
 175
 176
 177 <!-- ##### FUNCTION gtk_dialog_new_with_buttons ##### -->
 178 <para>
 179
 180 </para>
 181
 182 @title:
 183 @parent:
 184 @flags:
 185 @first_button_text:
 186 @Varargs:
 187 @Returns:
 188
 189
 190 <!-- ##### FUNCTION gtk_dialog_run ##### -->
 191 <para>
 192
 193 </para>
 194
 195 @dialog:
 196 @Returns:
 197
 198
 199 <!-- ##### FUNCTION gtk_dialog_response ##### -->
 200 <para>
 201
 202 </para>
 203
 204 @dialog:
 205 @response_id:
 206
 207
 208 <!-- ##### FUNCTION gtk_dialog_add_button ##### -->
 209 <para>
 210
 211 </para>
 212
 213 @dialog:
 214 @button_text:
 215 @response_id:
 216 @Returns:
 217
 218
 219 <!-- ##### FUNCTION gtk_dialog_add_buttons ##### -->
 220 <para>
 221
 222 </para>
 223
 224 @dialog:
 225 @first_button_text:
 226 @Varargs:
 227
 228
 229 <!-- ##### FUNCTION gtk_dialog_add_action_widget ##### -->
 230 <para>
 231
 232 </para>
 233
 234 @dialog:
 235 @child:
 236 @response_id:
 237 <!-- # Unused Parameters # -->
 238 @widget:
 239
 240
 241 <!-- ##### FUNCTION gtk_dialog_get_has_separator ##### -->
 242 <para>
 243
 244 </para>
 245
 246 @dialog:
 247 @Returns:
 248
 249
 250 <!-- ##### FUNCTION gtk_dialog_set_default_response ##### -->
 251 <para>
 252
 253 </para>
 254
 255 @dialog:
 256 @response_id:
 257
 258
 259 <!-- ##### FUNCTION gtk_dialog_set_has_separator ##### -->
 260 <para>
 261
 262 </para>
 263
 264 @dialog:
 265 @setting:
 266
 267
 268 <!-- ##### FUNCTION gtk_dialog_set_response_sensitive ##### -->
 269 <para>
 270
 271 </para>
 272
 273 @dialog:
 274 @response_id:
 275 @setting:
 276
 277
 278 <!-- ##### SIGNAL GtkDialog::close ##### -->
 279 <para>
 280
 281 </para>
 282
 283 @dialog: the object which received the signal.
 284
 285 <!-- ##### SIGNAL GtkDialog::response ##### -->
 286 <para>
 287 Emitted when an action widget is clicked, the dialog receives a delete event, or
 288 the application programmer calls gtk_dialog_response(). On a delete event, the
 289 response ID is #GTK_RESPONSE_NONE. Otherwise, it depends on which action widget
 290 was clicked.
 291 </para>
 292
 293 @dialog: the object which received the signal.
 294 @arg1: the response ID
 295
 296 <!-- ##### ARG GtkDialog:has-separator ##### -->
 297 <para>
 298
 299 </para>
 300
 301 <!-- ##### ARG GtkDialog:button-spacing ##### -->
 302 <para>
 303
 304 </para>
 305
 306 <!-- ##### ARG GtkDialog:content-area-border ##### -->
 307 <para>
 308
 309 </para>
 310
 311 <!-- ##### ARG GtkDialog:action-area-border ##### -->
 312 <para>
 313
 314 </para>
 315