gtk-signals.html

最新gtk中文资料集

derives from <a class="link" href="GtkButton.html" title="GtkButton"><span class="type">GtkButton</span></a> that is called clicked,
but it is okay to share signals names if they are separate in
the class tree.
</p></td>
</tr>
<tr>
<td><p><span class="term">default handler</span></p></td>
<td><p>The object's internal method which is invoked
when the signal is emitted.</p></td>
</tr>
<tr>
<td><p><span class="term">user-defined handler</span></p></td>
<td>
<p>A function pointer and data connected
to a signal (for a particular object).</p>
<p>There are really two types: those which are connected
normally, and those which are connected by one 
of the connect_after functions.  The connect_after handlers
are always run after the default handler.</p>
<p>Many toolkits refer to these as <em class="wordasword">callbacks</em>.</p>
</td>
</tr>
<tr>
<td><p><span class="term">emission</span></p></td>
<td><p>the whole process of emitting a signal,
including the invocation of all
the different handler types mentioned above.</p></td>
</tr>
<tr>
<td><p><span class="term">signal id</span></p></td>
<td><p>The unique positive (nonzero) integer
used to identify a signal.  It can be used instead of 
a name to many functions for a slight performance
improvement.</p></td>
</tr>
<tr>
<td><p><span class="term">connection id</span></p></td>
<td><p>The unique positive (nonzero) integer
used to identify the connection of a user-defined handler
to a signal.  Notice that it is allowed to connect the
same function-pointer/user-data pair twice, so
there is no guarantee that a function-pointer/user-data
maps to a unique connection id.
</p></td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3331689"></a><h3>A brief note on how they work.</h3>
<p>
The functions responsible for translating an array of <span class="type">GtkArgs</span>
to your C compiler's normal semantics are called Marshallers.
They are identified by
gtk_marshal_<em class="replaceable"><code>return_value</code></em>__<em class="replaceable"><code>parameter_list</code></em>()
for example a C function returning a gboolean and taking a gint
can be invoked by using <code class="function">gtk_marshal_BOOL__INT()</code>.
Not all possibly combinations of return/params are available,
of course, so if you are writing a <a class="link" href="GtkObject.html" title="GtkObject"><span class="type">GtkObject</span></a> with parameters
you might have to write a marshaller.
</p>
</div>
</div>
<div class="refsect1" lang="en">
<a name="id3331742"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="id3331753"></a><h3>
<a name="GTK-SIGNAL-OFFSET:CAPS"></a>GTK_SIGNAL_OFFSET</h3>
<a class="indexterm" name="id3331769"></a><pre class="programlisting">#define GTK_SIGNAL_OFFSET	                      GTK_STRUCT_OFFSET
</pre>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p><code class="literal">GTK_SIGNAL_OFFSET</code> is deprecated and should not be used in newly-written code.</p>
</div>
<p>
Use in place of <code class="function"><code class="function">offsetof()</code></code>, which is used if it exists.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3331812"></a><h3>
<a name="GtkSignalRunType"></a>enum GtkSignalRunType</h3>
<a class="indexterm" name="id3331828"></a><pre class="programlisting">typedef enum			/*&lt; flags &gt;*/
{
  GTK_RUN_FIRST      = G_SIGNAL_RUN_FIRST,
  GTK_RUN_LAST       = G_SIGNAL_RUN_LAST,
  GTK_RUN_BOTH       = (GTK_RUN_FIRST | GTK_RUN_LAST),
  GTK_RUN_NO_RECURSE = G_SIGNAL_NO_RECURSE,
  GTK_RUN_ACTION     = G_SIGNAL_ACTION,
  GTK_RUN_NO_HOOKS   = G_SIGNAL_NO_HOOKS
} GtkSignalRunType;
</pre>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p><code class="literal">GtkSignalRunType</code> is deprecated and should not be used in newly-written code.</p>
</div>
<p>
These configure the signal's emission.  They control
whether the signal can be emitted recursively on an object
and
whether to run the default method before or after the user-defined handlers.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term">GTK_RUN_FIRST</span></p></td>
<td><p>Run the default handler before the connected user-defined
handlers.
</p></td>
</tr>
<tr>
<td><p><span class="term">GTK_RUN_LAST</span></p></td>
<td><p>Run the default handler after the connected
user-defined handlers.
(Handlers registered as "after" always run after the default handler though)
</p></td>
</tr>
<tr>
<td><p><span class="term">GTK_RUN_BOTH</span></p></td>
<td><p>Run the default handler twice,
once before the user-defined handlers,
and
once after.
</p></td>
</tr>
<tr>
<td><p><span class="term">GTK_RUN_NO_RECURSE</span></p></td>
<td>
<p>Whether to prevent a handler or hook
from reemitting the signal from within itself.
Attempts to
emit the signal while it is running will result in the signal
emission being restarted once it is done with the current processing.
</p>
<p>
You must be
careful to avoid having two handlers endlessly reemitting signals,
<code class="function">gtk_signal_n_emissions()</code> can be helpful.
</p>
</td>
</tr>
<tr>
<td><p><span class="term">GTK_RUN_ACTION</span></p></td>
<td><p>The signal is an action you can 
invoke without any particular setup or cleanup.
The signal is treated no differently, but some
other code can determine if the signal is appropriate to
delegate to user control.  For example, key binding sets
only allow bindings of ACTION signals to keystrokes.
</p></td>
</tr>
<tr>
<td><p><span class="term">GTK_RUN_NO_HOOKS</span></p></td>
<td><p>This prevents the connection of emission hooks
to the signal.
</p></td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3331970"></a><h3>
<a name="gtk-signal-new"></a>gtk_signal_new ()</h3>
<a class="indexterm" name="id3331986"></a><pre class="programlisting"><a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               gtk_signal_new                      (const <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gchar"
>gchar</a> *name,
                                                         <a class="link" href="gtk-Signals.html#GtkSignalRunType">GtkSignalRunType</a> signal_flags,
                                                         <a class="link" href="gtk-Types.html#GtkType">GtkType</a> object_type,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> function_offset,
                                                         <a class="link" href="gtk-Types.html#GtkSignalMarshaller">GtkSignalMarshaller</a> marshaller,
                                                         <a class="link" href="gtk-Types.html#GtkType">GtkType</a> return_val,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> n_args,
                                                         ...);</pre>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p><code class="literal">gtk_signal_new</code> is deprecated and should not be used in newly-written code. Use <a
href="/usr/share/gtk-doc/html/gobject/gobject-Signals.html#g-signal-new"
><code class="function">g_signal_new()</code></a> instead.</p>
</div>
<p>
Creates a new signal type.  (This is usually done in the
class initializer.)
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>name</code></em>&#160;:</span></p></td>
<td>the event name for the signal, e.g. "clicked".
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>signal_flags</code></em>&#160;:</span></p></td>
<td>a combination of <span class="type">GTK_RUN</span> flags
specifying detail of when the default handler is to be invoked.
You should at least specify <span class="type">GTK_RUN_FIRST</span>
or <span class="type">GTK_RUN_LAST</span>.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>object_type</code></em>&#160;:</span></p></td>
<td>the type of object this signal pertains to.
It will also pertain to derivers of this type automatically.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>function_offset</code></em>&#160;:</span></p></td>
<td>How many bytes the function pointer is in
the class structure for this type.  Used to invoke a class
method generically.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>marshaller</code></em>&#160;:</span></p></td>
<td>the function to translate between an array
of GtkArgs and the native calling convention.  Usually they
are identified just by the type of arguments they take:
for example, <code class="function">gtk_marshal_BOOL__STRING()</code> describes a marshaller
which takes a string and returns a boolean value.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>return_val</code></em>&#160;:</span></p></td>
<td>the type of return value, or <span class="type">GTK_TYPE_NONE</span> for a signal
without a return value.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>n_args</code></em>&#160;:</span></p></td>
<td>the number of parameter the handlers may take.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>...</code></em>&#160;:</span></p></td>
<td>a list of <span class="type">GTK_TYPE_</span>*, one for each parameter.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span>&#160;:</span></p></td>
<td>the signal id.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3332283"></a><h3>
<a name="gtk-signal-newv"></a>gtk_signal_newv ()</h3>
<a class="indexterm" name="id3332298"></a><pre class="programlisting"><a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a>               gtk_signal_newv                     (const <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gchar"
>gchar</a> *name,
                                                         <a class="link" href="gtk-Signals.html#GtkSignalRunType">GtkSignalRunType</a> signal_flags,
                                                         <a class="link" href="gtk-Types.html#GtkType">GtkType</a> object_type,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> function_offset,
                                                         <a class="link" href="gtk-Types.html#GtkSignalMarshaller">GtkSignalMarshaller</a> marshaller,
                                                         <a class="link" href="gtk-Types.html#GtkType">GtkType</a> return_val,
                                                         <a
href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#guint"
>guint</a> n_args,
                                                         <a class="link" href="gtk-Types.html#GtkType">GtkType</a> *args);</pre>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p><code class="literal">gtk_signal_newv</code> is deprecated and should not be used in newly-written code. Use <a
href="/usr/share/gtk-doc/html/gobject/gobject-Signals.html#g-signal-newv"
><code class="function">g_signal_newv()</code></a> instead.</p>