signals.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

  guint		signal_id;
  GQuark	detail;
  GSignalFlags	run_type;
};
</programlisting>
<para>
The <link linkend="GSignalInvocationHint">GSignalInvocationHint</link> structure is used to pass on additional information
to callbacks during a signal emission.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="guint">guint</link> <structfield>signal_id</structfield></entry>
<entry>	The signal id of the signal invoking the callback
</entry>
</row>
<row>
<entry><link linkend="GQuark">GQuark</link> <structfield>detail</structfield></entry>
<entry>	The detail passed on for this emission
</entry>
</row>
<row>
<entry><link linkend="GSignalFlags">GSignalFlags</link> <structfield>run_type</structfield></entry>
<entry>	The stage the signal emission is currently in, this
		field will contain one of <literal>G_SIGNAL_RUN_FIRST</literal>,
		<literal>G_SIGNAL_RUN_LAST</literal> or <literal>G_SIGNAL_RUN_CLEANUP</literal>.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GSignalAccumulator">GSignalAccumulator ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    (*GSignalAccumulator)           (<link linkend="GSignalInvocationHint">GSignalInvocationHint</link> *ihint,
                                             <link linkend="GValue">GValue</link> *return_accu,
                                             const <link linkend="GValue">GValue</link> *handler_return,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
The signal accumulator is a special callback function that can be used
to collect return values of the various callbacks that are called
during a signal emission. The signal accumulator is specified at signal
creation time, if it is left NULL, no accumulation of callback return
values is performed. The return value of signal emissions is then the
value returned by the last callback.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>ihint</parameter>&nbsp;:</entry>
<entry>	Signal invocation hint, see <link linkend="GSignalInvocationHint">GSignalInvocationHint</link>.
</entry></row>
<row><entry align="right"><parameter>return_accu</parameter>&nbsp;:</entry>
<entry>	Accumulator to collect callback return values in, this
		is the return value of the current signal emission.
</entry></row>
<row><entry align="right"><parameter>handler_return</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>	The accumulator function returns whether the signal emission
		should be aborted. Returning <literal>FALSE</literal> means to abort the
		current emission and <literal>TRUE</literal> is returned for continuation.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GSignalCMarshaller">GSignalCMarshaller</title>
<programlisting>typedef GClosureMarshal			 GSignalCMarshaller;
</programlisting>
<para>
This is the signature of marshaller functions, required to marshall
arrays of parameter values to signal emissions into C language callback
invocations. It is merely an alias to <link linkend="GClosureMarshal">GClosureMarshal</link> since the <link linkend="GClosure">GClosure</link>
mechanism takes over responsibility of actual function invocation for the
signal system.
</para></refsect2>
<refsect2>
<title><anchor id="GSignalEmissionHook">GSignalEmissionHook ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    (*GSignalEmissionHook)          (<link linkend="GSignalInvocationHint">GSignalInvocationHint</link> *ihint,
                                             <link linkend="guint">guint</link> n_param_values,
                                             const <link linkend="GValue">GValue</link> *param_values,
                                             <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>ihint</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>n_param_values</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>param_values</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GSignalFlags">enum GSignalFlags</title>
<programlisting>typedef enum
{
  G_SIGNAL_RUN_FIRST	= 1 &lt;&lt; 0,
  G_SIGNAL_RUN_LAST	= 1 &lt;&lt; 1,
  G_SIGNAL_RUN_CLEANUP	= 1 &lt;&lt; 2,
  G_SIGNAL_NO_RECURSE	= 1 &lt;&lt; 3,
  G_SIGNAL_DETAILED	= 1 &lt;&lt; 4,
  G_SIGNAL_ACTION	= 1 &lt;&lt; 5,
  G_SIGNAL_NO_HOOKS	= 1 &lt;&lt; 6
} GSignalFlags;
</programlisting>
<para>
The signal flags are used to specify a signal's behaviour, the overall
signal description outlines how especially the RUN flags control the
stages of a signal emission.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_SIGNAL_RUN_FIRST</literal></entry>
<entry>  Invoke the object method handler in the first emission stage.
</entry>
</row>
<row>
<entry><literal>G_SIGNAL_RUN_LAST</literal></entry>
<entry>   Invoke the object method handler in the third emission stage.
</entry>
</row>
<row>
<entry><literal>G_SIGNAL_RUN_CLEANUP</literal></entry>
<entry>Invoke the object method handler in the last emission stage.
</entry>
</row>
<row>
<entry><literal>G_SIGNAL_NO_RECURSE</literal></entry>
<entry> Signals being emitted for an object while currently being in
                       emission for this very object will not be emitted recursively,
                       but instead cause the first emission to be restarted.
</entry>
</row>
<row>
<entry><literal>G_SIGNAL_DETAILED</literal></entry>
<entry>   This signal supports "::detail" appendixes to the signal name
                       upon handler connections and emissions.
</entry>
</row>
<row>
<entry><literal>G_SIGNAL_ACTION</literal></entry>
<entry>     Action signals are signals that may freely be emitted on alive
                       objects from user code via <link linkend="g-signal-emit">g_signal_emit</link>() and friends, without
                       the need of being embedded into extra code that performs pre or
                       post emission adjustments on the object. They can also be thought
                       of as by third-party code generically callable object methods.
</entry>
</row>
<row>
<entry><literal>G_SIGNAL_NO_HOOKS</literal></entry>
<entry>   No emissions hooks are supported for this signal.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GSignalMatchType">enum GSignalMatchType</title>
<programlisting>typedef enum
{
  G_SIGNAL_MATCH_ID	   = 1 &lt;&lt; 0,
  G_SIGNAL_MATCH_DETAIL	   = 1 &lt;&lt; 1,
  G_SIGNAL_MATCH_CLOSURE   = 1 &lt;&lt; 2,
  G_SIGNAL_MATCH_FUNC	   = 1 &lt;&lt; 3,
  G_SIGNAL_MATCH_DATA	   = 1 &lt;&lt; 4,
  G_SIGNAL_MATCH_UNBLOCKED = 1 &lt;&lt; 5
} GSignalMatchType;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="GSignalQuery">struct GSignalQuery</title>
<programlisting>struct GSignalQuery
{
  guint		signal_id;
  const gchar  *signal_name;
  GType		itype;
  GSignalFlags	signal_flags;
  GType		return_type; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */
  guint		n_params;
  const GType  *param_types; /* mangled with G_SIGNAL_TYPE_STATIC_SCOPE flag */
};
</programlisting>
<para>
A structure holding in-depth information for a specific signal. It is
filled in by the <link linkend="g-signal-query">g_signal_query</link>() function.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="guint">guint</link> <structfield>signal_id</structfield></entry>
<entry>	The signal id of the signal being queried, or 0 if the
		signal to be queried was unknown.
</entry>
</row>
<row>
<entry>const <link linkend="gchar">gchar</link> *<structfield>signal_name</structfield></entry>
<entry>	The signal name.
</entry>
</row>
<row>
<entry><link linkend="GType">GType</link> <structfield>itype</structfield></entry>
<entry>	The interface/instance type that this signal can be emitted for.
</entry>
</row>
<row>
<entry><link linkend="GSignalFlags">GSignalFlags</link> <structfield>signal_flags</structfield></entry>
<entry>	The signal flags as passed in to <link linkend="g-signal-new">g_signal_new</link>().
</entry>
</row>
<row>
<entry><link linkend="GType">GType</link> <structfield>return_type</structfield></entry>
<entry>	The return type for user callbacks.
</entry>
</row>
<row>
<entry><link linkend="guint">guint</link> <structfield>n_params</structfield></entry>
<entry>	The number of parameters that user callbacks take.
</entry>
</row>
<row>
<entry>const <link linkend="GType">GType</link> *<structfield>param_types</structfield></entry>
<entry>	The individual parameter types for user callbacks, note that the
		effective callback signature is:
<msgtext><programlisting>
<parameter>return_type</parameter> callback (<link linkend="gpointer">gpointer</link>     data1,
                      [<link linkend="param-types">param_types</link> param_names,]
                       <link linkend="gpointer">gpointer</link>     data2);
</programlisting></msgtext>

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-SIGNAL-TYPE-STATIC-SCOPE-CAPS">G_SIGNAL_TYPE_STATIC_SCOPE</title>
<programlisting>#define	G_SIGNAL_TYPE_STATIC_SCOPE (G_TYPE_FLAG_RESERVED_ID_BIT)
</programlisting>
<para>