File: z109.html

package info (click to toggle)
ebook-dev-ggad 199908-2
links: PTS
area: main
in suites: woody
size: 2,264 kB
ctags: 1,163
sloc: sh: 44; makefile: 35
file content (1302 lines) | stat: -rw-r--r-- 54,600 bytes
parent folder | download | duplicates (2)
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
  <head>
    <title>
      Signals
    </title>
    <meta name="GENERATOR" content=
    "Modular DocBook HTML Stylesheet Version 1.45">
    <link rel="HOME" title="GTK+ / Gnome Application Development"
    href="ggad.html">
    <link rel="UP" title="The GTK+ Object and Type System" href= 
    "cha-objects.html">
    <link rel="PREVIOUS" title="Object Arguments" href= 
    "hc-objectargs.html">
    <link rel="NEXT" title="Object Finalization" href= 
    "sec-finalization.html">
  </head>
  <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink= 
  "#840084" alink="#0000FF">
    <div class="NAVHEADER">
      <table width="100%" border="0" bgcolor="#ffffff" cellpadding= 
      "1" cellspacing="0">
        <tr>
          <th colspan="4" align="center">
            <font color="#000000" size="2">GTK+ / Gnome Application
            Development</font>
          </th>
        </tr>
        <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>
      </table>
    </div>
    <div class="SECT1">
      <h1 class="SECT1">
        <a name="Z109">Signals</a>
      </h1>
      <p>
        A <span class="STRUCTNAME">GtkObject</span> can emit a <i
        class="FIRSTTERM">signal</i>. Signals are stored in a
        global table by GTK+. <i class="FIRSTTERM">Handlers</i> or
        <i class="FIRSTTERM">callbacks</i> can be <i class= 
        "FIRSTTERM">connected</i> to signals; when a signal is <i
        class="FIRSTTERM">emitted</i>, its callbacks are invoked.
        The process of invoking all handlers for a signal is called
        <i class="FIRSTTERM">emission</i>.
      </p>
      <p>
        Abstractly, a signal is a <i class="EMPHASIS">kind</i> of
        message that an object wants to broadcast; the kind of
        message is associated with certain conditions (such as the
        user selecting a list item) and with message-specific
        parameter types which are passed to connected callbacks
        (such as the index of the row the user selected). User
        callbacks are connected to a particular signal and to a
        particular object instance. That is, you do not connect
        callbacks to the <span class="SYMBOL">"clicked"</span>
        signal of all buttons; rather, you connect to the <span
        class="SYMBOL">"clicked"</span> signal of a particular one.
        (However, there is a way to monitor all emissions of a
        signal---these callbacks are called "emission hooks.")
      </p>
      <p>
        Signals are typically associated with a class function
        pointer which is invoked every time the signal is emitted;
        if non-<span class="STRUCTNAME">NULL</span>, the pointed-to
        class function serves as a default handler for the signal.
        It is up to the author of each <span class="STRUCTNAME">
        GtkObject</span> subclass whether to provide a space in the
        class struct for a default handler, and whether to
        implement the default handler in the base class.
        Conventionally, signals have the same name as the class
        function they are associated with.
      </p>
      <p>
        For example, the <span class="STRUCTNAME">
        GtkButtonClass</span> struct has a member called <span
        class="STRUCTNAME">clicked</span>; this member is
        registered as the default handler for the <span class= 
        "SYMBOL">"clicked"</span> signal. However, the <tt class= 
        "CLASSNAME">GtkButton</tt> base class does not implement a
        default handler, and leaves the <span class="STRUCTNAME">
        clicked</span> member set to <span class="STRUCTNAME">
        NULL</span>. Subclasses of <tt class="CLASSNAME">
        GtkButton</tt> could optionally fill it in with an
        appropriate function. If <tt class="CLASSNAME">
        GtkButton</tt> did implement a default <span class= 
        "STRUCTNAME">clicked</span> handler, subclasses could still
        override it with a different one.
      </p>
      <p>
        Note that GTK+ signals have nothing to do with UNIX
        signals. Sometimes new GTK+ users confuse the two.
      </p>
      <div class="SECT2">
        <h2 class="SECT2">
          <a name="SEC-ADDINGSIGNAL">Adding a New Signal</a>
        </h2>
        <p>
          Once you understand the GTK+ type system and <span class= 
          "STRUCTNAME">GtkArg</span>, signal registration is fairly
          transparent. Here is the signal registration code from
          <tt class="CLASSNAME">GtkButton</tt> again:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  button_signals[PRESSED] =
    gtk_signal_new ("pressed",
                    GTK_RUN_FIRST,
                    object_class-&gt;type,
                    GTK_SIGNAL_OFFSET (GtkButtonClass, pressed),
                    gtk_marshal_NONE__NONE,
                    GTK_TYPE_NONE, 0);
  button_signals[RELEASED] =
    gtk_signal_new ("released",
                    GTK_RUN_FIRST,
                    object_class-&gt;type,
                    GTK_SIGNAL_OFFSET (GtkButtonClass, released),
                    gtk_marshal_NONE__NONE,
                    GTK_TYPE_NONE, 0);
  button_signals[CLICKED] =
    gtk_signal_new ("clicked",
                    GTK_RUN_FIRST | GTK_RUN_ACTION,
                    object_class-&gt;type,
                    GTK_SIGNAL_OFFSET (GtkButtonClass, clicked),
                    gtk_marshal_NONE__NONE,
                    GTK_TYPE_NONE, 0);
  button_signals[ENTER] =
    gtk_signal_new ("enter",
                    GTK_RUN_FIRST,
                    object_class-&gt;type,
                    GTK_SIGNAL_OFFSET (GtkButtonClass, enter),
                    gtk_marshal_NONE__NONE,
                    GTK_TYPE_NONE, 0);
  button_signals[LEAVE] =
    gtk_signal_new ("leave",
                    GTK_RUN_FIRST,
                    object_class-&gt;type,
                    GTK_SIGNAL_OFFSET (GtkButtonClass, leave),
                    gtk_marshal_NONE__NONE,
                    GTK_TYPE_NONE, 0);

  gtk_object_class_add_signals (object_class, button_signals, LAST_SIGNAL);

&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          Earlier in <tt class="FILENAME">gtkbutton.c</tt>, an
          enumeration and an array were declared as follows:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;enum {
  PRESSED,
  RELEASED,
  CLICKED,
  ENTER,
  LEAVE,
  LAST_SIGNAL
};


static guint button_signals[LAST_SIGNAL] = { 0 };
&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          <tt class="FUNCTION">gtk_signal_new()</tt> has the
          following effects:
        </p>
        <ul>
          <li>
            <p>
              It registers the name of the signal.&#13;
            </p>
          </li>
          <li>
            <p>
              It associates the signal with a particular <span
              class="STRUCTNAME">GtkType</span>.&#13;
            </p>
          </li>
          <li>
            <p>
              It tells GTK+ where to find the default handler in
              the class struct, if any.&#13;
            </p>
          </li>
          <li>
            <p>
              It tells GTK+ what signature the signal's callbacks
              will have.&#13;
            </p>
          </li>
          <li>
            <p>
              It registers a <i class="FIRSTTERM">marshaller</i>, a
              function which invokes the signal's callbacks in an
              appropriate way.&#13;
            </p>
          </li>
          <li>
            <p>
              It generates an integer identifier which can be used
              to refer to the signal. (If you refer to the symbol
              by name, GTK+ will find the ID associated with the
              name and then use the ID.)&#13;
            </p>
          </li>
        </ul>
        <p>
          <tt class="FUNCTION">gtk_object_class_add_signals()</tt>
          attaches signal identifiers to the object's class struct,
          so the signals for a given class can be rapidly located.
          Conventionally, the argument to this function is an
          enumeration-indexed static array, as shown for <tt class= 
          "CLASSNAME">GtkButton</tt>. The static array is also
          useful when implementing the functionality of the class
          (the signal identifiers are used to emit the signals).
        </p>
        <p>
          The first argument to <tt class="FUNCTION">
          gtk_signal_new()</tt> is a name for the signal; you refer
          to the signal by name when you call <tt class="FUNCTION">
          gtk_signal_connect()</tt>, for example. The third
          argument is the <span class="STRUCTNAME">GtkType</span>
          of the object type emitting the signal, and the fourth is
          the location of the associated class function in the
          type's class struct. A macro is provided to compute the
          offset. If you specify an offset of <span class= 
          "STRUCTNAME">0</span>, no class function will be
          associated with the signal. Note that giving a zero
          offset is distinct from giving a valid offset but setting
          the function member in the struct to <span class= 
          "STRUCTNAME">NULL</span>; in the latter case, subclasses
          of the object can fill in a value for the default
          handler.
        </p>
        <p>
          The second argument is a bitfield. Here are the
          associated flags:
        </p>
        <ul>
          <li>
            <p>
              <span class="STRUCTNAME">GTK_RUN_FIRST</span> means
              that the default handler in the class struct, if any,
              will run before user-connected callbacks. If this
              flag is set, signal handlers should not return a
              value.&#13;
            </p>
          </li>
          <li>
            <p>
              <span class="STRUCTNAME">GTK_RUN_LAST</span> means
              the opposite, the default handler will run last.
              (Caveat: user callbacks connected with <tt class= 
              "FUNCTION">gtk_signal_connect_after()</tt> run after
              a <span class="STRUCTNAME">GTK_RUN_LAST</span>
              default handler. There is no way to ensure a default
              handler is <i class="EMPHASIS">always</i> run last.
              <span class="STRUCTNAME">GTK_RUN_FIRST</span>
              handlers are always first, however.) &#13;
            </p>
          </li>
          <li>
            <p>
              <span class="STRUCTNAME">GTK_RUN_BOTH</span> is an
              alias for <span class="STRUCTNAME">(GTK_RUN_FIRST |
              GTK_RUN_LAST)</span>, so the default handler will run
              twice (on either side of user-connected callbacks).
              &#13;
            </p>
          </li>
          <li>
            <p>
              <span class="STRUCTNAME">GTK_RUN_NO_RECURSE</span>
              means that the signal should not be called
              recursively. If a handler for a signal emits the same
              signal again, normally the second emission is
              performed as usual (calling all handlers), and then
              the first emission continues, invoking its remaining
              handlers. With <span class="STRUCTNAME">
              GTK_RUN_NO_RECURSE</span> in effect, a second
              emission aborts the first emission (ignoring any
              handlers that remain), and restarts the emission
              process. So only one emission is in progress at a
              time. (Right now this is used only for <span class= 
              "STRUCTNAME">GtkAdjustment</span>'s <span class= 
              "SYMBOL">"changed"</span> and <span class="SYMBOL">
              "value_changed"</span> signals. Usually you don't
              care about how many times a value changed, only
              whether it changed and its most recent value. <span
              class="STRUCTNAME">GTK_RUN_NO_RECURSE</span>
              "compresses" multiple emissions into a single
              emission.) &#13;
            </p>
          </li>
          <li>
            <p>
              <span class="STRUCTNAME">GTK_RUN_ACTION</span> means
              the signal can be "bound" and invoked by the user. In
              other words, no special setup or shutdown is required
              in order to emit it. Among other things, GTK+ will
              allow users to bind keyboard accelerators to these
              signals using statements in the <tt class="FILENAME">
              .gtkrc</tt> configuration file.&#13;
            </p>
          </li>
          <li>
            <p>
              <span class="STRUCTNAME">GTK_RUN_NO_HOOKS</span>
              means that emission hooks are not allowed (you can't
              monitor this signal for an entire object type, only
              for particular object instances). It is used for
              <span class="STRUCTNAME">GtkObject</span>'s <span
              class="SYMBOL">"destroy"</span> signal because hooks
              are not invoked on objects with the <span class= 
              "STRUCTNAME">GTK_DESTROYED</span> flag set and that
              flag is set before emitting <span class="SYMBOL">
              "destroy"</span>. It's probably not good for anything
              else. &#13;
            </p>
          </li>
        </ul>
        <p>
          The last few arguments to <tt class="FUNCTION">
          gtk_signal_new()</tt> provide a <i class="FIRSTTERM">
          marshaller</i>, and tell GTK+ the marshaller's type. A
          marshaller invokes a callback function, based on an array
          of <span class="STRUCTNAME">GtkArg</span> it receives
          from GTK+. Marshallers are needed because C function
          argument lists cannot be constructed at runtime. GTK+
          comes with a number of prewritten marshallers; here is
          the one used for all <tt class="CLASSNAME">GtkButton</tt>
          signals:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;typedef void (*GtkSignal_NONE__NONE) (GtkObject* object,
                                      gpointer user_data);
void 
gtk_marshal_NONE__NONE (GtkObject * object,
                        GtkSignalFunc func,
                        gpointer func_data,
                        GtkArg * args)
{
  GtkSignal_NONE__NONE rfunc;
  rfunc = (GtkSignal_NONE__NONE) func;
  (*rfunc) (object,
            func_data);
}&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          As you can see, the <span class="STRUCTNAME">
          NONE__NONE</span> refers to the fact that the expected
          callback type returns no value and has no "special"
          arguments. GTK+ automatically passes the object emitting
          the signal and a <span class="STRUCTNAME">
          user_data</span> field to all callbacks; special signal
          arguments are inserted in between these two. Since there
          are no signal-specific arguments in this case, the array
          of <span class="STRUCTNAME">GtkArg</span> is ignored.
        </p>
        <p>
          The naming convention for marshallers places a double
          underscore between the return value and the special
          arguments, if any. Here's a more complex example:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;typedef gint (*GtkSignal_INT__POINTER) (GtkObject * object,
                                        gpointer arg1,
                                        gpointer user_data);
void 
gtk_marshal_INT__POINTER (GtkObject * object,
                          GtkSignalFunc func,
                          gpointer func_data,
                          GtkArg * args)
{
  GtkSignal_INT__POINTER rfunc;
  gint *return_val;
  return_val = GTK_RETLOC_INT (args[1]);
  rfunc = (GtkSignal_INT__POINTER) func;
  *return_val = (*rfunc) (object,
                          GTK_VALUE_POINTER (args[0]),
                          func_data);
}&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          Notice that the last element of the array of <span class= 
          "STRUCTNAME">GtkArg</span> is a space for the return
          value; if there is no return value, this element will
          have type <span class="STRUCTNAME">GTK_TYPE_NONE</span>
          and can be ignored. GTK+ provides macros such as <tt
          class="FUNCTION">GTK_RETLOC_INT()</tt> to extract a
          "return location" from a <span class="STRUCTNAME">
          GtkArg</span>. Similar <span class="STRUCTNAME">
          GTK_RETLOC_</span> macros exist for all the fundamental
          types.
        </p>
        <p>
          The function pointer signatures in the class structure
          for an object will correspond to the type of the signal.
          This is a convenient way to find out what signature the
          callbacks connected to a signal should have, if the GTK+
          header files are readily available on your system.
        </p>
        <p>
          The last arguments to <tt class="FUNCTION">
          gtk_signal_new()</tt> give the type of the signal's
          marshaller. First a return value type is given, then the
          number of special arguments, then a variable argument
          list containing that many <span class="STRUCTNAME">
          GtkType</span> values in the appropriate order. Since <tt
          class="CLASSNAME">GtkButton</tt> has no examples of
          signals with arguments, here is one from <tt class= 
          "CLASSNAME">GtkWidget</tt>:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  widget_signals[BUTTON_PRESS_EVENT] =
    gtk_signal_new("button_press_event",
                   GTK_RUN_LAST,
                   object_class-&gt;type,
                   GTK_SIGNAL_OFFSET (GtkWidgetClass, button_press_event),
                   gtk_marshal_BOOL__POINTER,
                   GTK_TYPE_BOOL, 1,
                   GTK_TYPE_GDK_EVENT);&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          <span class="SYMBOL">"button_press_event"</span> returns
          a boolean value, and has a <span class="STRUCTNAME">
          GdkEvent*</span> argument. Notice that the marshaller
          works with any <span class="STRUCTNAME">
          GTK_TYPE_POINTER</span>, but the signal requires the
          more-specific boxed type <span class="STRUCTNAME">
          GTK_TYPE_GDK_EVENT</span>, allowing language bindings to
          query the correct <i class="EMPHASIS">kind</i> of
          pointer.
        </p>
        <p>
          Signals can have many arguments; here is one from <tt
          class="CLASSNAME">GtkCList</tt>:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  clist_signals[SELECT_ROW] =
    gtk_signal_new ("select_row",
                    GTK_RUN_FIRST,
                    object_class-&gt;type,
                    GTK_SIGNAL_OFFSET (GtkCListClass, select_row),
                    gtk_marshal_NONE__INT_INT_POINTER,
                    GTK_TYPE_NONE, 3,
                    GTK_TYPE_INT,
                    GTK_TYPE_INT,
                    GTK_TYPE_GDK_EVENT);&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          The <span class="SYMBOL">"select_row"</span> signal
          returns no value, but has three arguments (the selected
          row and column number, and the event that caused the
          selection).
        </p>
      </div>
      <div class="SECT2">
        <h2 class="SECT2">
          <a name="Z110">Using Existing Signals</a>
        </h2>
        <p>
          <a href="z109.html#FL-USINGSIGNALS">Figure 4</a> shows
          the wide array of functions available for manipulating
          signals. You should already be familiar with the most
          fundamental signal operation: connecting a signal handler
          to be invoked when the signal is emitted, like this:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  gtk_signal_connect(GTK_OBJECT(window),
                     "delete_event",
                     GTK_SIGNAL_FUNC(delete_event_cb),
                     NULL);

  gtk_signal_connect(GTK_OBJECT(button),
                     "clicked",
                     GTK_SIGNAL_FUNC(button_click_cb),
                     label);
&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          You may not be aware that <tt class="FUNCTION">
          gtk_signal_connect()</tt> returns a "handler ID" which
          can be used to refer to the connection it creates. Using
          the handler ID, you can unregister the callback with <tt
          class="FUNCTION">gtk_signal_disconnect()</tt>. You can
          also temporarily "block" the callback by calling <tt
          class="FUNCTION">gtk_signal_handler_block()</tt>. This
          increments a "block count"; the callback will not be
          invoked until the block count returns to <tt class= 
          "APPLICATION">0</tt>. <tt class="FUNCTION">
          gtk_signal_handler_unblock()</tt> decrements the block
          count. Both <tt class="FUNCTION">
          gtk_signal_disconnect()</tt> and <tt class="FUNCTION">
          gtk_signal_handler_unblock()</tt> have variants that
          search for the handler ID given a callback function or
          user data pointer; these are possibly more convenient,
          with some loss of efficiency.
        </p>
        <p>
          It can be useful to block signal handlers if you'll be
          changing some aspect of an object yourself, and thus
          don't need to run the callbacks you use to respond to
          user actions. For example, you normally change some
          boolean variable if the user clicks a toggle button, in a
          callback to the <span class="SYMBOL">"toggled"</span>
          signal. If you update the toggle button programmatically
          because the flag was changed via some mechanism other
          than the button, <span class="SYMBOL">"toggled"</span>
          will still be emitted; but you want to block your
          callback, since the flag is already correct.
        </p>
        <p>
          <tt class="FUNCTION">gtk_signal_connect()</tt> is not the
          only way to connect to a signal. You can also use <tt
          class="FUNCTION">gtk_signal_connect_object()</tt>; this
          simply swaps the signal-emitting object pointer and the
          user data pointer in the arguments passed to the
          callback. Normally, the object comes first, then any
          arguments unique to the signal, and finally the user data
          pointer; with <tt class="FUNCTION">
          gtk_signal_connect_object()</tt>, the object is last and
          user data is first. This function is useful when you want
          to use a pre-existing function as a callback without
          writing a wrapper to move its arguments. For example:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  gtk_signal_connect_object(GTK_OBJECT(button),
                            "clicked",
                            GTK_SIGNAL_FUNC(gtk_widget_destroy),
                            GTK_OBJECT(dialog));&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          Because the user data and the button are swapped, the
          first argument to <tt class="FUNCTION">
          gtk_widget_destroy()</tt> will be the dialog rather than
          the button, closing the dialog. When using <tt class= 
          "FUNCTION">gtk_signal_connect_object()</tt>, your
          callback data must be a <span class="STRUCTNAME">
          GtkObject</span> to avoid confusing marshallers that
          expect an object as their first argument.
        </p>
        <p>
          <tt class="FUNCTION">gtk_signal_connect_after()</tt> asks
          GTK+ to run the callback after the object's default
          signal handler, rather than before it. This only works
          with certain signals, those with the <span class= 
          "STRUCTNAME">GTK_RUN_LAST</span> flag set; <a href= 
          "z109.html#SEC-ADDINGSIGNAL">the section called <i>Adding
          a New Signal</i></a> explains this flag.
        </p>
        <p>
          <tt class="FUNCTION">
          gtk_signal_connect_object_after()</tt> combines the
          effects of <tt class="FUNCTION">
          gtk_signal_connect_object()</tt> and <tt class=
          "FUNCTION">gtk_signal_connect_after()</tt>.
        </p>
        <p>
          <tt class="FUNCTION">gtk_signal_connect_full()</tt> gives
          you complete control over the connection and is mostly
          useful in language bindings. The <span class=
          "STRUCTNAME">object_signal</span> and <span class= 
          "STRUCTNAME">after</span> arguments can be <span class= 
          "STRUCTNAME">TRUE</span> or <span class="STRUCTNAME">
          FALSE</span>, toggling argument order and time of
          callback invocation. The functions we just mentioned also
          let you change this, so <tt class="FUNCTION">
          gtk_signal_connect_full()</tt> adds little. Its unique
          features are the ability to specify a callback
          marshaller, and the ability to specify a <span class= 
          "STRUCTNAME">GtkDestroyNotify</span> function. Notice
          that <tt class="FUNCTION">gtk_signal_connect_full()</tt>
          does not expect the same kind of marshaller described in
          <a href="z109.html#SEC-ADDINGSIGNAL">the section called
          <i>Adding a New Signal</i></a>; it expects a more general
          marshaller appropriate for marshalling functions written
          in languages other than C. If you give a non-<span class= 
          "STRUCTNAME">NULL</span><span class=
          "STRUCTNAME">GtkDestroyNotify</span> function, it will be
          invoked on the user data pointer when this handler is
          disconnected or the <span class="STRUCTNAME">
          GtkObject</span> is destroyed. Here is the proper
          signature for the function:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  typedef void (*GtkDestroyNotify)   (gpointer   data);&#13;
</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>
          </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>