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 horizontally. The top section is a
  18 #GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should be
  19 packed. The second area is known as the
  20 <structfield>action_area</structfield>. This is generally used for packing
  21 buttons into the dialog which may perform functions such as cancel, ok, or
  22 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 GTK_DIALOG(dialog)->vbox and GTK_DIALOG(dialog)->action_area,
  35 as can be seen from the example, below.
  36 </para>
  37
  38 <para>
  39 A 'modal' dialog (that is, one which freezes the rest of the application from
  40 user input), can be created by calling gtk_window_set_modal() on the dialog. Use
  41 the GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a
  42 #GtkWindow. When using gtk_dialog_new_with_buttons() you can also pass the
  43 GTK_DIALOG_MODAL flag to make a dialog modal.
  44 </para>
  45
  46 <para>
  47 If you add buttons to #GtkDialog using gtk_dialog_new_with_buttons(),
  48 gtk_dialog_add_button(), gtk_dialog_add_buttons(), or
  49 gtk_dialog_add_action_widget(), clicking the button will emit a signal called
  50 "response" with a response ID that you specified. GTK+ will never assign a
  51 meaning to positive response IDs; these are entirely user-defined. But for
  52 convenience, you can use the response IDs in the #GtkResponseType enumeration
  53 (these all have values less than zero). If a dialog receives a delete event, the
  54 "response" signal will be emitted with a response ID of GTK_RESPONSE_NONE.
  55 </para>
  56
  57
  58 <para>
  59 If you want to block waiting for a dialog to return before returning control
  60 flow to your code, you can call gtk_dialog_run(). This function enters a
  61 recursive main loop and waits for the user to respond to the dialog, returning the
  62 response ID corresponding to the button the user clicked.
  63 </para>
  64
  65 <para>
  66 For the simple dialog in the following example, in reality you'd probably use
  67 #GtkMessageDialog to save yourself some effort.  But you'd need to create the
  68 dialog contents manually if you had more than a simple message in the dialog.
  69 <example>
  70 <title>Simple #GtkDialog usage.</title>
  71 <programlisting>
  72
  73 /* Function to open a dialog box displaying the message provided. */
  74
  75 void quick_message(#gchar *message) {
  76
  77    #GtkWidget *dialog, *label;
  78
  79    /* Create the widgets */
  80
  81    dialog = gtk_dialog_new_with_buttons ("Message",
  82                                          main_application_window,
  83                                          GTK_DIALOG_DESTROY_WITH_PARENT,
  84                                          GTK_STOCK_BUTTON_OK,
  85                                          GTK_RESPONSE_NONE,
  86                                          NULL);
  87    label = gtk_label_new (message);
  88
  89    /* Ensure that the dialog box is destroyed when the user responds. */
  90
  91    gtk_signal_connect_object (GTK_OBJECT (dialog), "response",
  92                               GTK_SIGNAL_FUNC (gtk_widget_destroy),
  93                               GTK_OBJECT (dialog));
  94
  95    /* Add the label, and show everything we've added to the dialog. */
  96
  97    gtk_container_add (GTK_CONTAINER (GTK_DIALOG(dialog)->vbox),
  98                       label);
  99    gtk_widget_show_all (dialog);
 100 }
 101
 102 </programlisting>
 103 </example>
 104 </para>
 105
 106 <!-- ##### SECTION See_Also ##### -->
 107
 108 <para>
 109 <variablelist>
 110 <varlistentry>
 111 <term>#GtkVBox</term>
 112 <listitem><para>Pack widgets vertically.</para></listitem>
 113 </varlistentry>
 114 <varlistentry>
 115 <term>#GtkWindow</term>
 116 <listitem><para>Alter the properties of your dialog box.</para></listitem>
 117 </varlistentry>
 118 <varlistentry>
 119 <term>#GtkButton</term>
 120 <listitem><para>Add them to the <structfield>action_area</structfield> to get a
 121 response from the user.</para></listitem>
 122 </varlistentry>
 123 </variablelist>
 124 </para>
 125
 126 <!-- ##### STRUCT GtkDialog ##### -->
 127 <para>
 128 <structfield>window</structfield> is a #GtkWindow, but should not be
 129 modified directly, (use the functions provided, such as
 130 gtk_window_set_title(). See the #GtkWindow section for more).
 131 </para>
 132 <para>
 133 <structfield>vbox</structfield> is a #GtkVBox - the main part of the dialog box.
 134 </para>
 135 <para>
 136 <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.
 137 </para>
 138
 139
 140 <!-- ##### ENUM GtkDialogFlags ##### -->
 141 <para>
 142
 143 </para>
 144
 145 @GTK_DIALOG_MODAL:
 146 @GTK_DIALOG_DESTROY_WITH_PARENT:
 147 @GTK_DIALOG_NO_SEPARATOR:
 148
 149 <!-- ##### ENUM GtkResponseType ##### -->
 150 <para>
 151
 152 </para>
 153
 154 @GTK_RESPONSE_NONE:
 155 @GTK_RESPONSE_REJECT:
 156 @GTK_RESPONSE_ACCEPT:
 157 @GTK_RESPONSE_DELETE_EVENT:
 158 @GTK_RESPONSE_OK:
 159 @GTK_RESPONSE_CANCEL:
 160 @GTK_RESPONSE_CLOSE:
 161 @GTK_RESPONSE_YES:
 162 @GTK_RESPONSE_NO:
 163 @GTK_RESPONSE_APPLY:
 164 @GTK_RESPONSE_HELP:
 165
 166 <!-- ##### FUNCTION gtk_dialog_new ##### -->
 167 <para>
 168 Creates a new dialog box. Widgets should not be packed into this #GtkWindow
 169 directly, but into the vbox and action_area, as described above.
 170 </para>
 171
 172 @Returns: a #GtkWidget - the newly created dialog box.
 173
 174
 175 <!-- ##### FUNCTION gtk_dialog_new_with_buttons ##### -->
 176 <para>
 177
 178 </para>
 179
 180 @title:
 181 @parent:
 182 @flags:
 183 @first_button_text:
 184 @Varargs:
 185 @Returns:
 186
 187
 188 <!-- ##### FUNCTION gtk_dialog_run ##### -->
 189 <para>
 190
 191 </para>
 192
 193 @dialog:
 194 @Returns:
 195
 196
 197 <!-- ##### FUNCTION gtk_dialog_response ##### -->
 198 <para>
 199
 200 </para>
 201
 202 @dialog:
 203 @response_id:
 204
 205
 206 <!-- ##### FUNCTION gtk_dialog_add_button ##### -->
 207 <para>
 208
 209 </para>
 210
 211 @dialog:
 212 @button_text:
 213 @response_id:
 214 @Returns:
 215
 216
 217 <!-- ##### FUNCTION gtk_dialog_add_buttons ##### -->
 218 <para>
 219
 220 </para>
 221
 222 @dialog:
 223 @first_button_text:
 224 @Varargs:
 225
 226
 227 <!-- ##### FUNCTION gtk_dialog_add_action_widget ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @dialog:
 233 @child:
 234 @response_id:
 235 <!-- # Unused Parameters # -->
 236 @widget:
 237
 238
 239 <!-- ##### FUNCTION gtk_dialog_get_has_separator ##### -->
 240 <para>
 241
 242 </para>
 243
 244 @dialog:
 245 @Returns:
 246
 247
 248 <!-- ##### FUNCTION gtk_dialog_set_default_response ##### -->
 249 <para>
 250
 251 </para>
 252
 253 @dialog:
 254 @response_id:
 255
 256
 257 <!-- ##### FUNCTION gtk_dialog_set_has_separator ##### -->
 258 <para>
 259
 260 </para>
 261
 262 @dialog:
 263 @setting:
 264
 265
 266 <!-- ##### FUNCTION gtk_dialog_set_response_sensitive ##### -->
 267 <para>
 268
 269 </para>
 270
 271 @dialog:
 272 @response_id:
 273 @setting:
 274
 275
 276 <!-- ##### SIGNAL GtkDialog::close ##### -->
 277 <para>
 278
 279 </para>
 280
 281 @dialog: the object which received the signal.
 282
 283 <!-- ##### SIGNAL GtkDialog::response ##### -->
 284 <para>
 285 Emitted when an action widget is clicked, the dialog receives a delete event, or
 286 the application programmer calls gtk_dialog_response(). On a delete event, the
 287 response ID is GTK_RESPONSE_NONE. Otherwise, it depends on which action widget
 288 was clicked.
 289 </para>
 290
 291 @dialog: the object which received the signal.
 292 @arg1: the response ID
 293
 294 <!-- ##### ARG GtkDialog:has-separator ##### -->
 295 <para>
 296
 297 </para>
 298