</pre>            </td>          </tr>        </table>        <p>          Conveniently, you can use <tt class="FUNCTION">          g_free()</tt> or <tt class="FUNCTION">          gtk_object_destroy()</tt> as a <span class="STRUCTNAME">          GtkDestroyNotify</span>. Of course, if these aren't          appropriate you can write a custom function.        </p>        <p>          <tt class="FUNCTION">          gtk_signal_connect_while_alive()</tt> is a variant on <tt          class="FUNCTION">gtk_signal_connect()</tt>; its          additional argument is an object to monitor. When the          monitored object is destroyed (emits the <span class=           "SYMBOL">"destroy"</span> signal), the handler will be          disconnected. That is, handlers connected with this          function are automatically disconnected when a specified          object no longer exists.        </p>        <p>          There's rarely a need to do so, but you can look up a          signal's ID number given the signal name and the object          type that emits it. This function is <tt class=          "FUNCTION">gtk_signal_lookup()</tt>. Note that names are          not globally unique, but they are unique with respect to          a particular object type. On the other hand, signal IDs          <i class="EMPHASIS">are</i> globally unique.        </p>        <p>          During the emission of a signal (that is, during the          process of invoking its handlers), you can call <tt          class="FUNCTION">gtk_signal_emit_stop()</tt> (or its          <span class="STRUCTNAME">_by_name()</span> variant) to          halt the emission. These functions are only useful from          within signal handlers, because they must be called          during the emission process or they won't have anything          to stop. They do not take effect immediately; instead,          they set a variable that GTK+ checks at key points during          emission. <a href="z109.html#SEC-EMISSION">the section          called <i>What Happens When A Signal Is Emitted</i></a>          describes this in detail.        </p>        <p>          <i class="FIRSTTERM">Emission hooks</i> can be used to          monitor all emissions of a given signal (regardless of          the object instance doing the emitting). Emission hooks          have the following signature:        </p>        <table border="0" bgcolor="#E0E0E0" width="100%">          <tr>            <td><pre class="PROGRAMLISTING">&#13;typedef gboolean (*GtkEmissionHook) (GtkObject      *object,                                     guint           signal_id,                                     guint           n_params,                                     GtkArg         *params,                                     gpointer        data);&#13;</pre>            </td>          </tr>        </table>        <p>          They are passed the same parameters GTK+ would normally          pass to callback marshallers (see <a href=           "z109.html#SEC-ADDINGSIGNAL">the section called <i>Adding          a New Signal</i></a>). You can connect an emission hook          with a destroy notify function to be invoked on the user          data pointer when the hook is removed. When you add an          emission hook, an integer identify is returned. You can          remove emission hooks with this ID number.        </p>        <p>          Emission hooks are rarely useful, but sometimes they are          the only way to do something. For example, Gnome          optionally plays sound effects when certain signals are          emitted (such as button clicks).        </p>        <p>          Finally, you can ask everything you ever wanted to know          about a signal using <tt class="FUNCTION">          gtk_signal_query()</tt>. This function is intended for          GUI builders and language bindings to use; it is probably          not useful in application code. It returns a <span class=           "STRUCTNAME">GtkSignalQuery</span> structure filled with          information about the signal. The return value should be          freed with <tt class="FUNCTION">g_free()</tt> but not          modified in any way (it contains pointers to internal          data which isn't copied). Here is the definition of <span          class="STRUCTNAME">GtkSignalQuery</span>:        </p>        <table border="0" bgcolor="#E0E0E0" width="100%">          <tr>            <td><pre class="PROGRAMLISTING">&#13;typedef struct _GtkSignalQuery GtkSignalQuery;struct  _GtkSignalQuery{  GtkType          object_type;  guint            signal_id;  const gchar     *signal_name;  guint            is_user_signal : 1;  GtkSignalRunType signal_flags;  GtkType          return_val;  guint            nparams;  const GtkType   *params;};&#13;</pre>            </td>          </tr>        </table>        <div class="FIGURE">          <a name="FL-USINGSIGNALS"></a>          <div class="FUNCSYNOPSIS">            <a name="FL-USINGSIGNALS.SYNOPSIS"></a>            <table border="0" bgcolor="#E0E0E0" width="100%">              <tr>                <td><pre class="FUNCSYNOPSISINFO">#include &lt;gtk/gtksignal.h&gt;</pre>                </td>              </tr>            </table>            <p>              <code><code class="FUNCDEF">guint <tt class=              "FUNCTION">gtk_signal_lookup</tt></code>(const gchar*              <tt class="PARAMETER"><i>name</i></tt>, GtkType <tt              class="PARAMETER"><i>object_type</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">gchar* <tt class=              "FUNCTION">gtk_signal_name</tt></code>(guint <tt              class="PARAMETER"><i>signal_id</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_emit_stop</tt></code>(GtkObject* <tt              class="PARAMETER"><i>object</i></tt>, guint <tt              class="PARAMETER"><i>signal_id</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_emit_stop_by_name</tt></code>(GtkObject*              <tt class="PARAMETER"><i>object</i></tt>, const              gchar* <tt class="PARAMETER"><i>              name</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">guint <tt class=              "FUNCTION">gtk_signal_connect</tt></code>(GtkObject*              <tt class="PARAMETER"><i>object</i></tt>, const              gchar* <tt class="PARAMETER"><i>name</i></tt>,              GtkSignalFunc <tt class="PARAMETER"><i>func</i></tt>,              gpointer <tt class="PARAMETER"><i>              func_data</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">guint <tt class=              "FUNCTION">              gtk_signal_connect_after</tt></code>(GtkObject* <tt              class="PARAMETER"><i>object</i></tt>, const gchar*              <tt class="PARAMETER"><i>name</i></tt>, GtkSignalFunc              <tt class="PARAMETER"><i>func</i></tt>, gpointer <tt              class="PARAMETER"><i>func_data</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">guint <tt class=              "FUNCTION">              gtk_signal_connect_object</tt></code>(GtkObject* <tt              class="PARAMETER"><i>object</i></tt>, const gchar*              <tt class="PARAMETER"><i>name</i></tt>, GtkSignalFunc              <tt class="PARAMETER"><i>func</i></tt>, GtkObject*              <tt class="PARAMETER"><i>              slot_object</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">guint <tt class=              "FUNCTION">              gtk_signal_connect_object_after</tt></code>(GtkObject*              <tt class="PARAMETER"><i>object</i></tt>, const              gchar* <tt class="PARAMETER"><i>name</i></tt>,              GtkSignalFunc <tt class="PARAMETER"><i>func</i></tt>,              GtkObject* <tt class="PARAMETER"><i>              slot_object</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">guint <tt class=              "FUNCTION">              gtk_signal_connect_full</tt></code>(GtkObject* <tt              class="PARAMETER"><i>object</i></tt>, const gchar*              <tt class="PARAMETER"><i>name</i></tt>, GtkSignalFunc              <tt class="PARAMETER"><i>func</i></tt>,              GtkCallbackMarshal <tt class="PARAMETER"><i>              marshal</i></tt>, gpointer <tt class="PARAMETER"><i>              data</i></tt>, GtkDestroyNotify <tt class=              "PARAMETER"><i>destroy_func</i></tt>, gint <tt class=               "PARAMETER"><i>object_signal</i></tt>, gint <tt              class="PARAMETER"><i>after</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_connect_object_while_alive</tt></code>(GtkObject*              <tt class="PARAMETER"><i>object</i></tt>, const              gchar* <tt class="PARAMETER"><i>signal</i></tt>,              GtkSignalFunc <tt class="PARAMETER"><i>func</i></tt>,              GtkObject* <tt class="PARAMETER"><i>              alive_object</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_connect_while_alive</tt></code>(GtkObject*              <tt class="PARAMETER"><i>object</i></tt>, const              gchar* <tt class="PARAMETER"><i>signal</i></tt>,              GtkSignalFunc <tt class="PARAMETER"><i>func</i></tt>,              gpointer <tt class="PARAMETER"><i>func_data</i></tt>,              GtkObject * <tt class="PARAMETER"><i>              alive_object</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_disconnect</tt></code>(GtkObject* <tt              class="PARAMETER"><i>object</i></tt>, guint <tt              class="PARAMETER"><i>handler_id</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_disconnect_by_func</tt></code>(GtkObject*              <tt class="PARAMETER"><i>object</i></tt>,              GtkSignalFunc <tt class="PARAMETER"><i>func</i></tt>,              gpointer <tt class="PARAMETER"><i>              func_data</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_disconnect_by_data</tt></code>(GtkObject *              <tt class="PARAMETER"><i>object</i></tt>, gpointer              <tt class="PARAMETER"><i>func_data</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_handler_block</tt></code>(GtkObject* <tt              class="PARAMETER"><i>object</i></tt>, guint <tt              class="PARAMETER"><i>handler_id</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_handler_block_by_func</tt></code>(GtkObject*              <tt class="PARAMETER"><i>object</i></tt>,              GtkSignalFunc <tt class="PARAMETER"><i>func</i></tt>,              gpointer <tt class="PARAMETER"><i>              func_data</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_handler_block_by_data</tt></code>(GtkObject*              <tt class="PARAMETER"><i>object</i></tt>, gpointer              <tt class="PARAMETER"><i>func_data</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_handler_unblock</tt></code>(GtkObject* <tt              class="PARAMETER"><i>object</i></tt>, guint <tt              class="PARAMETER"><i>handler_id</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_handler_unblock_by_func</tt></code>(GtkObject*              <tt class="PARAMETER"><i>object</i></tt>,              GtkSignalFunc <tt class="PARAMETER"><i>func</i></tt>,              gpointer <tt class="PARAMETER"><i>              func_data</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_handler_unblock_by_data</tt></code>(GtkObject*              <tt class="PARAMETER"><i>object</i></tt>, gpointer              <tt class="PARAMETER"><i>func_data</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">guint <tt class=              "FUNCTION">              gtk_signal_add_emission_hook</tt></code>(guint <tt              class="PARAMETER"><i>signal_id</i></tt>,              GtkEmissionHook <tt class="PARAMETER"><i>              hook_func</i></tt>, gpointer <tt class="PARAMETER">              <i>data</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">guint <tt class=              "FUNCTION">              gtk_signal_add_emission_hook_full</tt></code>(guint              <tt class="PARAMETER"><i>signal_id</i></tt>,              GtkEmissionHook <tt class="PARAMETER"><i>              hook_func</i></tt>, gpointer <tt class="PARAMETER">              <i>data</i></tt>, GDestroyNotify <tt class=              "PARAMETER"><i>destroy</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">void <tt class=              "FUNCTION">              gtk_signal_remove_emission_hook</tt></code>(guint <tt              class="PARAMETER"><i>signal_id</i></tt>, guint <tt              class="PARAMETER"><i>hook_id</i></tt>);</code>            </p>            <p>              <code><code class="FUNCDEF">GtkSignalQuery* <tt              class="FUNCTION">gtk_signal_query</tt></code>(guint              <tt class="PARAMETER"><i>signal_id</i></tt>);</code>            </p>