z109.html

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

          </div>
          <p>
            <b>Figure 4. Using Signals</b>
          </p>
        </div>
      </div>
      <div class="SECT2">
        <h2 class="SECT2">
          <a name="SEC-EMITTING">Emitting A Signal</a>
        </h2>
        <p>
          It's your object's responsibility to emit its signals at
          appropriate times. This is very simple; if you've saved
          the return value from <tt class="FUNCTION">
          gtk_signal_new()</tt>, that identifier can be used to
          emit the signal. Otherwise, you can emit the signal by
          name (with some cost in execution speed, since GTK+ will
          have to look up the identifier in a hash table).
        </p>
        <p>
          Here is code from <tt class="FILENAME">
          gtk/gtkbutton.c</tt> which is used to emit the <span
          class="SYMBOL">"button_pressed"</span> signal:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;void
gtk_button_pressed (GtkButton *button)
{
  g_return_if_fail (button != NULL);
  g_return_if_fail (GTK_IS_BUTTON (button));

  gtk_signal_emit (GTK_OBJECT (button), button_signals[PRESSED]);
}
&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          If a signal has arguments (other than the standard two),
          you must specify those as a variable argument list:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  gtk_signal_emit (GTK_OBJECT (widget), widget_signals[SIZE_REQUEST],
                   &amp;widget-&gt;requisition);&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          If a signal returns a value, you must pass a location for
          the returned value as the final argument:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  gint return_val;

  return_val = FALSE;

  gtk_signal_emit (GTK_OBJECT (widget), widget_signals[EVENT], event,
                   &amp;return_val);&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          Notice that <span class="STRUCTNAME">return_val</span> is
          initialized to something sane; if there are no signal
          handlers, none of them will assign a value to <span
          class="STRUCTNAME">return_val</span>. So you must
          initialize the variable. Each signal handler's return
          value will be assigned to the same location, so the final
          value of <span class="STRUCTNAME">return_val</span> is
          determined by the last signal handler to run. Note that
          certain return values (such as strings) must be freed by
          the signal emitter.
        </p>
        <p>
          <tt class="FUNCTION">gtk_signal_emit_by_name()</tt> is
          the same as <tt class="FUNCTION">gtk_signal_emit()</tt>,
          except that the second argument is a signal name rather
          than a signal ID number. There are also variants of both
          emission functions that take a vector of <span class= 
          "STRUCTNAME">GtkArg</span> instead of a variable argument
          list. These variants expect arrays of <i class=
          "EMPHASIS">n+1</i><span class="STRUCTNAME">GtkArg</span>
          structs, where <i class="EMPHASIS">n</i> is the number of
          signal arguments and there is an additional <span class= 
          "STRUCTNAME">GtkArg</span> for the return value. The
          <span class="STRUCTNAME">GtkArg</span> structs should be
          initialized with sane values. If the function returns no
          value, the return value <span class="STRUCTNAME">
          GtkArg</span> will have <span class="STRUCTNAME">
          GTK_TYPE_NONE</span>.
        </p>
        <p>
          All four signal emission functions are summarized in <a
          href="z109.html#FL-SIGNALEMISSION">Figure 5</a>.
        </p>
        <div class="FIGURE">
          <a name="FL-SIGNALEMISSION"></a>
          <div class="FUNCSYNOPSIS">
            <a name="FL-SIGNALEMISSION.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">void <tt class=
              "FUNCTION">gtk_signal_emit</tt></code>(GtkObject* <tt
              class="PARAMETER"><i>object</i></tt>, guint <tt
              class="PARAMETER"><i>signal_id</i></tt>, <tt class= 
              "PARAMETER"><i>...</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">
              gtk_signal_emit_by_name</tt></code>(GtkObject* <tt
              class="PARAMETER"><i>object</i></tt>, const gchar*
              <tt class="PARAMETER"><i>name</i></tt>, <tt class= 
              "PARAMETER"><i>...</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">gtk_signal_emitv</tt></code>(GtkObject*
              <tt class="PARAMETER"><i>object</i></tt>, guint <tt
              class="PARAMETER"><i>signal_id</i></tt>, GtkArg* <tt
              class="PARAMETER"><i>params</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">
              gtk_signal_emitv_by_name</tt></code>(GtkObject* <tt
              class="PARAMETER"><i>object</i></tt>, const gchar*
              <tt class="PARAMETER"><i>name</i></tt>, GtkArg* <tt
              class="PARAMETER"><i>params</i></tt>);</code>
            </p>
          </div>
          <p>
            <b>Figure 5. Signal Emission</b>
          </p>
        </div>
        <p>
          Keep in mind that it is usually inappropriate to simply
          emit a signal outside of an object's implementation. Only
          <span class="STRUCTNAME">GTK_RUN_ACTION</span> signals
          are guaranteed to work properly without special setup or
          shutdown. Objects often export functions you can use to
          emit signals properly; for example, to emit the <span
          class="SYMBOL">"size_request"</span> signal, <tt class= 
          "CLASSNAME">GtkWidget</tt> provides this function:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;void
gtk_widget_size_request (GtkWidget      *widget,
                         GtkRequisition *requisition)
{
  g_return_if_fail (widget != NULL);
  g_return_if_fail (GTK_IS_WIDGET (widget));

  gtk_widget_ref (widget);
  gtk_widget_ensure_style (widget);
  gtk_signal_emit (GTK_OBJECT (widget), widget_signals[SIZE_REQUEST],
                   &amp;widget-&gt;requisition);

  if (requisition)
    gtk_widget_get_child_requisition (widget, requisition);

  gtk_widget_unref (widget);
}&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          As you can see, particular actions are required before
          and after emitting the signal; thus it should only be
          emitted via the <tt class="FUNCTION">
          gtk_widget_size_request()</tt> function.
        </p>
      </div>
      <div class="SECT2">
        <h2 class="SECT2">
          <a name="SEC-EMISSION">What Happens When A Signal Is
          Emitted</a>
        </h2>
        <p>
          Given the many different options when creating signals
          and connecting callbacks, you may be thoroughly confused
          about what happens when a signal is emitted. Here's a
          summary of the sequence of events:
        </p>
        <ol type="1">
          <li>
            <p>
              If you are emitting the signal by name, the signal ID
              is looked up. &#13;
            </p>
          </li>
          <li>
            <p>
              If another emission of the same signal is in
              progress, and the signal has the <span class= 
              "STRUCTNAME">GTK_RUN_NO_RECURSE</span> flag set, GTK+
              signals the previous emission to restart and this
              emission ends. &#13;
            </p>
          </li>
          <li>
            <p>
              If the signal is <span class="STRUCTNAME">
              GTK_RUN_FIRST</span>, the default signal handler is
              called using the signal's marshaller. If the emission
              is stopped from within the handler, (using <tt class= 
              "FUNCTION">gtk_emit_stop_by_name()</tt> or one of its
              cousins), this emission ends. If the signal is
              re-emitted from within the handler and is <span
              class="STRUCTNAME">GTK_RUN_NO_RECURSE</span>, this
              emission restarts. &#13;
            </p>
          </li>
          <li>
            <p>
              If there are any emission hooks installed for this
              signal, they are invoked. GTK+ does <i class=
              "EMPHASIS">not</i> check whether the emission has
              been stopped or re-emitted at this point; it will not
              check until the next step. Emission hooks should not
              re-emit the signal they are watching, or try to stop
              the emission. &#13;
            </p>
          </li>
          <li>
            <p>
              Any normally-connected callbacks are invoked using
              the signal's marshaller. Callbacks connected with <tt
              class="FUNCTION">gtk_signal_connect_after()</tt> are
              not invoked at this point. After invoking each
              callback, GTK+ checks whether it stopped the signal
              and the emission ends if so. GTK+ also checks whether
              the signal was re-emitted, and if so restarts the
              emission process for <span class="STRUCTNAME">
              GTK_RUN_NO_RECURSE</span> signals. &#13;
            </p>
          </li>
          <li>
            <p>
              If the signal is <span class="STRUCTNAME">
              GTK_RUN_LAST</span>, the default handler is invoked.
              Afterward GTK+ again checks whether the emission has
              been stopped or should be restarted. &#13;
            </p>
          </li>
          <li>
            <p>
              Any callbacks connected with <tt class="FUNCTION">
              gtk_signal_connect_after()</tt> are invoked. After
              invoking each one, GTK+ checks whether the emission
              should be stopped or restarted. &#13;
            </p>
          </li>
        </ol>
        <p>
          Within each step the handlers are invoked in the order
          they were connected. The order of the steps is fixed:
          <span class="STRUCTNAME">GTK_RUN_FIRST</span> default
          handler, emission hooks, normal connections, <span class= 
          "STRUCTNAME">GTK_RUN_LAST</span> default handler, "after"
          connections.
        </p>
      </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="hc-objectargs.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-finalization.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>Object
            Arguments</b></font>
          </td>
          <td colspan="2" align="right">
            <font color="#000000" size="2"><b>Object
            Finalization</b></font>
          </td>
        </tr>
      </table>
    </div>
  </body>
</html>