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 <para>
  10 Dialog boxes are a convenient way to prompt the user for a small amount of
  11 input, eg. to display
  12 a message, ask a question, or anything else that does not require extensive
  13 effort on the user's part.
  14 </para>
  15 <para>
  16 Gtk+ treats a dialog as a window split horizontally. The top section is a
  17 #GtkVBox, and is where widgets such as a #GtkLabel or a #GtkEntry should be
  18 packed. The second area is known as the <structfield>action_area</structfield>. This is generally used
  19 for packing buttons into the dialog which may perform functions such as cancel, ok, or apply. The two
  20 areas are separated by a #GtkHSeparator.
  21 </para>
  22 <para>
  23 #GtkDialog boxes are created with a call to gtk_dialog_new().
  24 </para>
  25 <para>
  26 If 'dialog' is a newly created dialog, the two primary areas of the window
  27 can be accessed as GTK_DIALOG(dialog)->vbox and GTK_DIALOG(dialog)->action_area,
  28 as can be seen from the example, below.
  29 </para>
  30 <para>
  31 A 'modal' dialog (that is, one which freezes the rest of the application
  32 from user input), can be created by calling gtk_window_set_modal() on the dialog. Use the
  33 GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a
  34 #GtkWindow.
  35 </para>
  36 <para>
  37 <example>
  38 <title>Using a #GtkDialog to keep the user informed.</title>
  39 <programlisting>
  40
  41 /* Function to open a dialog box displaying the message provided. */
  42
  43 void quick_message(#gchar *message) {
  44
  45    #GtkWidget *dialog, *label, *okay_button;
  46
  47    /* Create the widgets */
  48
  49    dialog = gtk_dialog_new();
  50    label = gtk_label_new (message);
  51    okay_button = gtk_button_new_with_label("Okay");
  52
  53    /* Ensure that the dialog box is destroyed when the user clicks ok. */
  54
  55    gtk_signal_connect_object (GTK_OBJECT (okay_button), "clicked",
  56                               GTK_SIGNAL_FUNC (gtk_widget_destroy), dialog);
  57    gtk_container_add (GTK_CONTAINER (GTK_DIALOG(dialog)->action_area),
  58                       okay_button);
  59
  60    /* Add the label, and show everything we've added to the dialog. */
  61
  62    gtk_container_add (GTK_CONTAINER (GTK_DIALOG(dialog)->vbox),
  63                       label);
  64    gtk_widget_show_all (dialog);
  65 }
  66
  67 </programlisting>
  68 </example>
  69 </para>
  70
  71 <!-- ##### SECTION See_Also ##### -->
  72
  73 <para>
  74 <variablelist>
  75 <varlistentry>
  76 <term>#GtkVBox</term>
  77 <listitem><para>Pack widgets vertically.</para></listitem>
  78 </varlistentry>
  79 <varlistentry>
  80 <term>#GtkWindow</term>
  81 <listitem><para>Alter the properties of your dialog box.</para></listitem>
  82 </varlistentry>
  83 <varlistentry>
  84 <term>#GtkButton</term>
  85 <listitem><para>Add them to the <structfield>action_area</structfield> to get a
  86 response from the user.</para></listitem>
  87 </varlistentry>
  88 </variablelist>
  89 </para>
  90
  91 <!-- ##### STRUCT GtkDialog ##### -->
  92 <para>
  93 <structfield>window</structfield> is a #GtkWindow, but should not be
  94 modified directly, (use the functions provided, such as
  95 gtk_window_set_title(). See the #GtkWindow section for more).
  96 </para>
  97 <para>
  98 <structfield>vbox</structfield> is a #GtkVBox - the main part of the dialog box.
  99 </para>
 100 <para>
 101 <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.
 102 </para>
 103
 104
 105 <!-- ##### STRUCT GtkDialogButton ##### -->
 106 <para>
 107 Deprecated.
 108 </para>
 109
 110
 111 <!-- ##### FUNCTION gtk_dialog_new ##### -->
 112 <para>
 113 Creates a new dialog box. Widgets should not be packed into this #GtkWindow
 114 directly, but into the vbox and action_area, as described above.
 115 </para>
 116
 117 @Returns: a #GtkWidget - the newly created dialog box.
 118
 119