z109.html

gtk 开发手册和参考文档。 包括gtk glib gdk等

</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>