gtkdialog.html

最新gtk中文资料集

not require extensive effort on the user's part.
</p>
<p>
GTK+ treats a dialog as a window split vertically. The top section is a
<a class="link" href="GtkVBox.html" title="GtkVBox"><span class="type">GtkVBox</span></a>, and is where widgets such as a <a class="link" href="GtkLabel.html" title="GtkLabel"><span class="type">GtkLabel</span></a> or a <a class="link" href="GtkEntry.html" title="GtkEntry"><span class="type">GtkEntry</span></a> should
be packed. The bottom area is known as the
<em class="structfield"><code>action_area</code></em>. This is generally used for
packing buttons into the dialog which may perform functions such as
cancel, ok, or apply. The two areas are separated by a <a class="link" href="GtkHSeparator.html" title="GtkHSeparator"><span class="type">GtkHSeparator</span></a>.
</p>
<p>
<a class="link" href="GtkDialog.html" title="GtkDialog"><span class="type">GtkDialog</span></a> boxes are created with a call to <a class="link" href="GtkDialog.html#gtk-dialog-new"><code class="function">gtk_dialog_new()</code></a> or
<a class="link" href="GtkDialog.html#gtk-dialog-new-with-buttons"><code class="function">gtk_dialog_new_with_buttons()</code></a>. <a class="link" href="GtkDialog.html#gtk-dialog-new-with-buttons"><code class="function">gtk_dialog_new_with_buttons()</code></a> is recommended; it
allows you to set the dialog title, some convenient flags, and add simple
buttons.
</p>
<p>
If 'dialog' is a newly created dialog, the two primary areas of the window 
can be accessed as <code class="literal">GTK_DIALOG(dialog)-&gt;vbox</code> and 
<code class="literal">GTK_DIALOG(dialog)-&gt;action_area</code>,
as can be seen from the example, below.
</p>
<p>
A 'modal' dialog (that is, one which freezes the rest of the application from
user input), can be created by calling <a class="link" href="GtkWindow.html#gtk-window-set-modal"><code class="function">gtk_window_set_modal()</code></a> on the dialog. Use
the <code class="function">GTK_WINDOW()</code> macro to cast the widget returned from <a class="link" href="GtkDialog.html#gtk-dialog-new"><code class="function">gtk_dialog_new()</code></a> into a
<a class="link" href="GtkWindow.html" title="GtkWindow"><span class="type">GtkWindow</span></a>. When using <a class="link" href="GtkDialog.html#gtk-dialog-new-with-buttons"><code class="function">gtk_dialog_new_with_buttons()</code></a> you can also pass the
<a class="link" href="GtkDialog.html#GTK-DIALOG-MODAL:CAPS"><span class="type">GTK_DIALOG_MODAL</span></a> flag to make a dialog modal.
</p>
<p>
If you add buttons to <a class="link" href="GtkDialog.html" title="GtkDialog"><span class="type">GtkDialog</span></a> using <a class="link" href="GtkDialog.html#gtk-dialog-new-with-buttons"><code class="function">gtk_dialog_new_with_buttons()</code></a>,
<a class="link" href="GtkDialog.html#gtk-dialog-add-button"><code class="function">gtk_dialog_add_button()</code></a>, <a class="link" href="GtkDialog.html#gtk-dialog-add-buttons"><code class="function">gtk_dialog_add_buttons()</code></a>, or
<a class="link" href="GtkDialog.html#gtk-dialog-add-action-widget"><code class="function">gtk_dialog_add_action_widget()</code></a>, clicking the button will emit a signal called
"response" with a response ID that you specified. GTK+ will never assign a
meaning to positive response IDs; these are entirely user-defined. But for
convenience, you can use the response IDs in the <a class="link" href="GtkDialog.html#GtkResponseType"><span class="type">GtkResponseType</span></a> 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 <a class="link" href="GtkDialog.html#GTK-RESPONSE-DELETE-EVENT:CAPS"><span class="type">GTK_RESPONSE_DELETE_EVENT</span></a>.
</p>
<p>
If you want to block waiting for a dialog to return before returning control
flow to your code, you can call <a class="link" href="GtkDialog.html#gtk-dialog-run"><code class="function">gtk_dialog_run()</code></a>. This function enters a
recursive main loop and waits for the user to respond to the dialog, returning the 
response ID corresponding to the button the user clicked.
</p>
<p>
For the simple dialog in the following example, in reality you'd probably use
<a class="link" href="GtkMessageDialog.html" title="GtkMessageDialog"><span class="type">GtkMessageDialog</span></a> to save yourself some effort.  But you'd need to create the
dialog contents manually if you had more than a simple message in the dialog.
</p>
<div class="example">
<a name="id3360061"></a><p class="title"><b>Example&#160;4.&#160;Simple <span class="structname">GtkDialog</span> usage.</b></p>
<div class="example-contents"><pre class="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)-&gt;vbox),
                      label);
   gtk_widget_show_all (dialog);
}

</pre></div>
</div>
<p><br class="example-break">
</p>
<div class="refsect2" lang="en">
<a name="GtkDialog-BUILDER-UI"></a><h3>GtkDialog as GtkBuildable</h3>
<p>
The GtkDialog implementation of the GtkBuildable interface exposes the 
<em class="parameter"><code>vbox</code></em> and <em class="parameter"><code>action_area</code></em> as internal children with the names "vbox" and 
"action_area".
</p>
<p>
GtkDialog supports a custom &lt;action-widgets&gt; element, which 
can contain multiple &lt;action-widget&gt; elements. The "response"
attribute specifies a numeric response, and the content of the element
is the id of widget (which should be a child of the dialogs <em class="parameter"><code>action_area</code></em>).
</p>
<div class="example">
<a name="id3360142"></a><p class="title"><b>Example&#160;5.&#160;A <span class="structname">GtkDialog</span> UI definition fragment.</b></p>
<div class="example-contents"><pre class="programlisting">
&lt;object class="GtkDialog" id="dialog1"&gt;
  &lt;child internal-child="vbox"&gt;"
    &lt;object class="GtkVBox"&gt;
      &lt;child internal-child="action_area"&gt;
        &lt;object class="GtkHButtonBox"&gt;
          &lt;child&gt;
            &lt;object class="GtkButton" id="button_cancel"/&gt;
          &lt;/child&gt;
          &lt;child&gt;
            &lt;object class="GtkButton" id="button_ok"/&gt;
          &lt;/child&gt;
        &lt;/object&gt;
      &lt;/child&gt;
    &lt;/object&gt;
  &lt;/child&gt;
  &lt;action-widgets&gt;
    &lt;action-widget response="3"&gt;button_ok&lt;/action-widget&gt;
    &lt;action-widget response="-5"&gt;button_cancel&lt;/action-widget&gt;
  &lt;/action-widgets&gt;
&lt;/object&gt;
</pre></div>
</div>
<br class="example-break">
</div>
</div>
<div class="refsect1" lang="en">
<a name="id3360159"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="id3360181"></a><h3>
<a name="GtkDialog-struct"></a>GtkDialog</h3>
<a class="indexterm" name="id3360194"></a><pre class="programlisting">typedef struct {
  GtkWidget *vbox;
  GtkWidget *action_area;
} GtkDialog;
</pre>
<p>
<em class="structfield"><code>vbox</code></em> is a <a class="link" href="GtkVBox.html" title="GtkVBox"><span class="type">GtkVBox</span></a> - the main part of the
dialog box.
</p>
<p>
<em class="structfield"><code>action_area</code></em> is a <a class="link" href="GtkHButtonBox.html" title="GtkHButtonBox"><span class="type">GtkHButtonBox</span></a> packed below the
dividing <a class="link" href="GtkHSeparator.html" title="GtkHSeparator"><span class="type">GtkHSeparator</span></a> in the dialog. It is treated exactly the same
as any other <a class="link" href="GtkHButtonBox.html" title="GtkHButtonBox"><span class="type">GtkHButtonBox</span></a>.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3360255"></a><h3>
<a name="GtkDialogFlags"></a>enum GtkDialogFlags</h3>
<a class="indexterm" name="id3360268"></a><pre class="programlisting">typedef enum
{
  GTK_DIALOG_MODAL               = 1 &lt;&lt; 0, /* call gtk_window_set_modal (win, TRUE) */
  GTK_DIALOG_DESTROY_WITH_PARENT = 1 &lt;&lt; 1, /* call gtk_window_set_destroy_with_parent () */
  GTK_DIALOG_NO_SEPARATOR        = 1 &lt;&lt; 2  /* no separator bar above buttons */
} GtkDialogFlags;
</pre>
<p>
Flags used to influence dialog construction.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><a name="GTK-DIALOG-MODAL:CAPS"></a><code class="literal">GTK_DIALOG_MODAL</code></span></p></td>
<td>Make the constructed dialog modal, 
  see <a class="link" href="GtkWindow.html#gtk-window-set-modal"><code class="function">gtk_window_set_modal()</code></a>.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="GTK-DIALOG-DESTROY-WITH-PARENT:CAPS"></a><code class="literal">GTK_DIALOG_DESTROY_WITH_PARENT</code></span></p></td>
<td>Destroy the dialog when its
  parent is destroyed, see <a class="link" href="GtkWindow.html#gtk-window-set-destroy-with-parent"><code class="function">gtk_window_set_destroy_with_parent()</code></a>.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="GTK-DIALOG-NO-SEPARATOR:CAPS"></a><code class="literal">GTK_DIALOG_NO_SEPARATOR</code></span></p></td>
<td>Don't put a separator between the
  action area and the dialog content.

</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3360389"></a><h3>
<a name="GtkResponseType"></a>enum GtkResponseType</h3>
<a class="indexterm" name="id3360402"></a><pre class="programlisting">typedef enum
{
  /* GTK returns this if a response widget has no response_id,
   * or if the dialog gets programmatically hidden or destroyed.
   */
  GTK_RESPONSE_NONE = -1,

  /* GTK won't return these unless you pass them in
   * as the response for an action widget. They are
   * for your convenience.
   */
  GTK_RESPONSE_REJECT = -2,
  GTK_RESPONSE_ACCEPT = -3,

  /* If the dialog is deleted. */
  GTK_RESPONSE_DELETE_EVENT = -4,

  /* These are returned from GTK dialogs, and you can also use them
   * yourself if you like.
   */
  GTK_RESPONSE_OK     = -5,
  GTK_RESPONSE_CANCEL = -6,
  GTK_RESPONSE_CLOSE  = -7,
  GTK_RESPONSE_YES    = -8,
  GTK_RESPONSE_NO     = -9,
  GTK_RESPONSE_APPLY  = -10,
  GTK_RESPONSE_HELP   = -11
} GtkResponseType;
</pre>
<p>
Predefined values for use as response ids in <a class="link" href="GtkDialog.html#gtk-dialog-add-button"><code class="function">gtk_dialog_add_button()</code></a>.
All predefined values are negative, GTK+ leaves positive values for
application-defined response ids. 
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><a name="GTK-RESPONSE-NONE:CAPS"></a><code class="literal">GTK_RESPONSE_NONE</code></span></p></td>
<td>Returned if an action widget has no response id, or if 
   the dialog gets programmatically hidden or destroyed.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="GTK-RESPONSE-REJECT:CAPS"></a><code class="literal">GTK_RESPONSE_REJECT</code></span></p></td>
<td>Generic response id, not used by GTK+ dialogs.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="GTK-RESPONSE-ACCEPT:CAPS"></a><code class="literal">GTK_RESPONSE_ACCEPT</code></span></p></td>
<td>Generic response id, not used by GTK+ dialogs.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="GTK-RESPONSE-DELETE-EVENT:CAPS"></a><code class="literal">GTK_RESPONSE_DELETE_EVENT</code></span></p></td>
<td>Returned if the dialog is deleted.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="GTK-RESPONSE-OK:CAPS"></a><code class="literal">GTK_RESPONSE_OK</code></span></p></td>
<td>Returned by OK buttons in GTK+ dialogs.
</td>
</tr>
<tr>