<p>                If the dialog is not modal, interacting with other                parts of the application              </p>            </li>          </ul>          <p>            <tt class="CLASSNAME">GnomeDialog</tt> emits two            signals in addition to those it inherits from parent            classes. If the user clicks one of the dialog's            buttons, a <span class="SYMBOL">"clicked"</span> signal            is emitted. (This is <i class="EMPHASIS">not</i> the            <span class="SYMBOL">"clicked"</span> signal from <tt            class="CLASSNAME">GtkButton</tt>; it's a different            signal, emitted by <tt class="CLASSNAME">            GnomeDialog</tt>.) A <tt class="CLASSNAME">            GnomeDialog</tt><span class="SYMBOL">"clicked"</span>            handler should have three arguments: the dialog            emitting the signal, the number of the button clicked,            and your callback data.          </p>          <p>            <tt class="CLASSNAME">GnomeDialog</tt> also has a <span            class="SYMBOL">"close"</span> signal. It is emitted            when <tt class="FUNCTION">gnome_dialog_close()</tt> is            called; all the built-in event handlers (e.g. for the            Escape shortcut) call this function to close the            dialog. <tt class="CLASSNAME">GnomeDialog</tt>'s            default handler for <span class="SYMBOL">"close"</span>            has two possible behaviors: it can call either <tt            class="FUNCTION">gtk_widget_hide()</tt> or <tt class=             "FUNCTION">gtk_widget_destroy()</tt> on the dialog. The            behavior is configurable by calling <tt class=            "FUNCTION">gnome_dialog_close_hides()</tt>, shown in <a            href="cha-dialogs.html#FL-CLOSINGDIALOG">Figure 3</a>.          </p>          <div class="FIGURE">            <a name="FL-CLOSINGDIALOG"></a>            <div class="FUNCSYNOPSIS">              <a name="FL-CLOSINGDIALOG.SYNOPSIS"></a>              <table border="0" bgcolor="#E0E0E0" width="100%">                <tr>                  <td><pre class="FUNCSYNOPSISINFO">       #include &lt;libgnomeui/gnome-dialog.h&gt;      </pre>                  </td>                </tr>              </table>              <p>                <code><code class="FUNCDEF">void <tt class=                "FUNCTION">                gnome_dialog_close_hides</tt></code>(GnomeDialog*                <tt class="PARAMETER"><i>dialog</i></tt>, gboolean                <tt class="PARAMETER"><i>setting</i></tt>);</code>              </p>              <p>                <code><code class="FUNCDEF">void <tt class=                "FUNCTION">                gnome_dialog_set_close</tt></code>(GnomeDialog* <tt                class="PARAMETER"><i>dialog</i></tt>, gboolean <tt                class="PARAMETER"><i>setting</i></tt>);</code>              </p>            </div>            <p>              <b>Figure 3. Closing <tt class="CLASSNAME">              GnomeDialog</tt></b>            </p>          </div>          <p>            By default, <span class="SYMBOL">"close"</span>            destroys the dialog. This is what you usually want;            however, if a dialog is noticeably time-consuming to            create, you might want to merely hide and re-show it            between uses, without ever destroying it. You might            also want to hide the dialog from the user, extract the            state of any widgets inside it, and then destroy it            with <tt class="FUNCTION">gtk_widget_destroy()</tt>.            The decision depends on the structure of your code.            However, in general it is simpler and less error-prone            to let the dialog be destroyed when clicked. You can            connect to the <span class="SYMBOL">"clicked"</span>            signal if you need to query the state of widgets in the            dialog.          </p>          <p>            If you connect a handler to <span class="SYMBOL">            "close"</span>, that handler should return a boolean            value. If it returns <span class="STRUCTNAME">            TRUE</span>, the hide or destroy will not take place.            You can use this to keep the user from closing the            dialog, for example if they have not filled in all the            fields of a form.          </p>          <p>            The <span class="SYMBOL">"close"</span> signal is            designed to collect several possible user actions into            a single handler: it should be emitted when the user            presses Escape or the window manager's window close            button is clicked. It's often convenient to emit close            when the dialog's buttons are clicked as well. You can            ask <tt class="CLASSNAME">GnomeDialog</tt> to emit            close whenever a button is clicked with <tt class=             "FUNCTION">gnome_dialog_set_close()</tt> (<a href=             "cha-dialogs.html#FL-CLOSINGDIALOG">Figure 3</a>); if            its <span class="STRUCTNAME">setting</span> argument is            <span class="STRUCTNAME">TRUE</span>, the dialog will            emit <span class="SYMBOL">"close"</span> in addition to            <span class="SYMBOL">"clicked"</span> if any of its            buttons are clicked. By default, this setting is <span            class="STRUCTNAME">FALSE</span> for <tt class=            "CLASSNAME">GnomeDialog</tt>, but for many of the            special dialog types the default is <span class=             "STRUCTNAME">TRUE</span> (the inconsistency is an            unfortunate misfeature).          </p>          <p>            Note that the <span class="SYMBOL">"close"</span>            signal is emitted when the dialog receives <span class=             "SYMBOL">"delete_event"</span>; this means you only            have to write one signal handler to deal with all            dialog closings. There is no need to handle <span            class="SYMBOL">"delete_event"</span> as a separate            case.          </p>        </div>        <div class="SECT2">          <h2 class="SECT2">            <a name="SEC-DIALOGS-TOUCHES">Finishing Touches</a>          </h2>          <p>            The difference between a good dialog and a great dialog            is in the details. <tt class="CLASSNAME">            GnomeDialog</tt> comes with a number of features to            make that final polish easy. <a href=             "cha-dialogs.html#FL-DIALOGPOLISH">Figure 4</a> sums            them up.          </p>          <div class="FIGURE">            <a name="FL-DIALOGPOLISH"></a>            <div class="FUNCSYNOPSIS">              <a name="FL-DIALOGPOLISH.SYNOPSIS"></a>              <table border="0" bgcolor="#E0E0E0" width="100%">                <tr>                  <td><pre class="FUNCSYNOPSISINFO">       #include &lt;libgnomeui/gnome-dialog.h&gt;      </pre>                  </td>                </tr>              </table>              <p>                <code><code class="FUNCDEF">void <tt class=                "FUNCTION">                gnome_dialog_set_parent</tt></code>(GnomeDialog*                <tt class="PARAMETER"><i>dialog</i></tt>,                GtkWindow* <tt class="PARAMETER"><i>                parent</i></tt>);</code>              </p>              <p>                <code><code class="FUNCDEF">void <tt class=                "FUNCTION">                gnome_dialog_set_default</tt></code>(GnomeDialog*                <tt class="PARAMETER"><i>dialog</i></tt>, gint <tt                class="PARAMETER"><i>button</i></tt>);</code>              </p>              <p>                <code><code class="FUNCDEF">void <tt class=                "FUNCTION">                gnome_dialog_editable_enters</tt></code>(GnomeDialog*                <tt class="PARAMETER"><i>dialog</i></tt>,                GtkEditable* <tt class="PARAMETER"><i>                editable</i></tt>);</code>              </p>              <p>                <code><code class="FUNCDEF">void <tt class=                "FUNCTION">                gnome_dialog_set_sensitive</tt></code>(GnomeDialog*                <tt class="PARAMETER"><i>dialog</i></tt>, gint <tt                class="PARAMETER"><i>button</i></tt>, gboolean <tt                class="PARAMETER"><i>setting</i></tt>);</code>              </p>            </div>            <p>              <b>Figure 4. <tt class="CLASSNAME">GnomeDialog</tt>              Polish</b>            </p>          </div>          <p>            Dialogs have a logical <i class="FIRSTTERM">parent</i>,            usually the main application window. You can tell the            library about this parent-child relationship; this lets            Gnome honor certain user preferences, and in turn            indicates the relationship to the window manager. Most            window managers will minimize child dialogs when the            parent window is minimized, and keep child dialogs on            top of their parent.          </p>          <p>            It's important to use <tt class="FUNCTION">            gnome_dialog_set_parent()</tt> with <i class=            "FIRSTTERM">transient</i> dialogs only. A transient            dialog is one that appears and is dismissed relatively            quickly. (<tt class="CLASSNAME">GnomeDialog</tt> is            really meant for transient dialogs.) Some "dialogs" are            just small windows, such as the tool palette in the            Gimp. These persistent ("floating") dialogs should be            minimizable without minimizing the parent, and they            should not be forced to stay above the parent window.          </p>          <p>            Your dialog should have a sensible <i class=            "FIRSTTERM">default button</i>---this is the button            activated when the user presses the Enter key. <tt            class="FUNCTION">gnome_dialog_set_default()</tt>            specifies the default button. It's a judgment call            which button should be the default. Often the best            choice is the least-destructive action (i.e., "Cancel"            rather than "OK"), but if neither is destructive, user            convenience might guide your decision.          </p>          <p>            Typically, operations such as deleting data or quitting            an application have "Cancel" or "No" as the default;            dialogs that ask the user to enter text or other            information typically have "OK" as the default.            Remember that many window managers will focus windows            when they pop up, so keystrokes users intend to go to            their current application might go to your dialog            instead. If your dialog has "delete all my files" as            the default button, you will get hate mail.          </p>          <p>            Editable widgets emit the <span class="SYMBOL">            "activate"</span> signal when Enter is pressed.            Typically users expect Enter to activate the default            dialog button, but if you have an editable widget such            as <tt class="CLASSNAME">GtkEntry</tt> in your dialog,            it will capture any Enter presses, and keep the            dialog's buttons from responding to them. <tt class=             "FUNCTION">gnome_dialog_editable_enters()</tt>            activates the dialog's default button when the <tt            class="CLASSNAME">GtkEditable</tt> is activated,            solving the problem.          </p>          <p>            <tt class="FUNCTION">gnome_dialog_set_sensitive()</tt>            calls <tt class="FUNCTION">            gtk_widget_set_sensitive()</tt> on <span class=             "STRUCTNAME">button</span>. If clicking a button makes            no sense at a given time it should be desensitized.          </p>          <p>            Finally, you should make sure you do not create            multiple instances of a dialog. Many applications allow            you to pop up multiple Preferences or About dialogs;            users will not trigger this bug very often, but it is a            nice touch to avoid the problem. The following code            deals with it in a simple way (note that the details of            creating and showing the dialog have been omitted).          </p>          <table border="0" bgcolor="#E0E0E0" width="100%">            <tr>              <td><pre class="PROGRAMLISTING">&#13;void do_dialog(){  static GtkWidget* dialog = NULL;  if (dialog != NULL)     {      /* This code tries to de-iconify and raise the dialog.        * It assumes the dialog is realized; if you can't        * ensure that, check that dialog-&gt;window != NULL.       */      gdk_window_show(dialog-&gt;window);      gdk_window_raise(dialog-&gt;window);    }  else    {      dialog = gnome_dialog_new();      /* Arguments elided. */      gtk_signal_connect(GTK_OBJECT(dialog),                         "destroy",                         GTK_SIGNAL_FUNC(gtk_widget_destroyed),                         &amp;dialog);      /* Show the dialog, connect callbacks, etc. here */                       }}      </pre>              </td>            </tr>          </table>          <p>            <tt class="FUNCTION">gtk_widget_destroyed()</tt> is            defined in <tt class="FILENAME">gtk/gtkwidget.h</tt>,            and simply assigns <span class="STRUCTNAME">NULL</span>            to its second argument. The code resets the <span            class="STRUCTNAME">dialog</span> variable each time the            user closes the dialog, and raises/deiconifies the            dialog if the user tries to open it while another one            is active. Note that the window manager has some say in            whether the raise/deiconify is successful, so it is not            guaranteed to happen.          </p>        </div>      </div>    </div>    <div class="NAVFOOTER">      <br>      <br>      <table width="100%" border="0" bgcolor="#ffffff" cellpadding=       "1" cellspacing="0">        <tr>          <td width="25%" bgcolor="#ffffff" align="left">            <a href="z94.html"><font color="#0000ff" size="2"><b>            &lt;&lt;&lt; Previous</b></font></a>          </td>          <td width="25%" colspan="2" bgcolor="#ffffff" align=           "center">            <font color="#0000ff" size="2"><b><a href="ggad.html">            <font color="#0000ff" size="2"><b>            Home</b></font></a></b></font>          </td>          <td width="25%" bgcolor="#ffffff" align="right">            <a href="sec-modaldialogs.html"><font color="#0000ff"            size="2"><b>Next &gt;&gt;&gt;</b></font></a>          </td>        </tr>        <tr>          <td colspan="2" align="left">            <font color="#000000" size="2"><b>Finishing            Touches</b></font>          </td>          <td colspan="2" align="right">            <font color="#000000" size="2"><b>Modal            Dialogs</b></font>          </td>        </tr>      </table>    </div>  </body></html>