signals.sgml

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

<refentry id="gobject-Signals">
<refmeta>
<refentrytitle>Signals</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GOBJECT Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Signals</refname><refpurpose>Signals provide a means for customization of object behaviour and are used
as general purpose notification mechanism.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gobject.h&gt;


struct      <link linkend="GSignalInvocationHint">GSignalInvocationHint</link>;
<link linkend="gboolean">gboolean</link>    (<link linkend="GSignalAccumulator">*GSignalAccumulator</link>)           (<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);
typedef     <link linkend="GSignalCMarshaller">GSignalCMarshaller</link>;
<link linkend="gboolean">gboolean</link>    (<link linkend="GSignalEmissionHook">*GSignalEmissionHook</link>)          (<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);
enum        <link linkend="GSignalFlags">GSignalFlags</link>;
enum        <link linkend="GSignalMatchType">GSignalMatchType</link>;
struct      <link linkend="GSignalQuery">GSignalQuery</link>;
#define     <link linkend="G-SIGNAL-TYPE-STATIC-SCOPE-CAPS">G_SIGNAL_TYPE_STATIC_SCOPE</link>
#define     <link linkend="G-SIGNAL-MATCH-MASK-CAPS">G_SIGNAL_MATCH_MASK</link>
#define     <link linkend="G-SIGNAL-FLAGS-MASK-CAPS">G_SIGNAL_FLAGS_MASK</link>
<link linkend="guint">guint</link>       <link linkend="g-signal-new">g_signal_new</link>                    (const <link linkend="gchar">gchar</link> *signal_name,
                                             <link linkend="GType">GType</link> itype,
                                             <link linkend="GSignalFlags">GSignalFlags</link> signal_flags,
                                             <link linkend="guint">guint</link> class_offset,
                                             <link linkend="GSignalAccumulator">GSignalAccumulator</link> accumulator,
                                             <link linkend="gpointer">gpointer</link> accu_data,
                                             <link linkend="GSignalCMarshaller">GSignalCMarshaller</link> c_marshaller,
                                             <link linkend="GType">GType</link> return_type,
                                             <link linkend="guint">guint</link> n_params,
                                             ...);
<link linkend="guint">guint</link>       <link linkend="g-signal-newv">g_signal_newv</link>                   (const <link linkend="gchar">gchar</link> *signal_name,
                                             <link linkend="GType">GType</link> itype,
                                             <link linkend="GSignalFlags">GSignalFlags</link> signal_flags,
                                             <link linkend="GClosure">GClosure</link> *class_closure,
                                             <link linkend="GSignalAccumulator">GSignalAccumulator</link> accumulator,
                                             <link linkend="gpointer">gpointer</link> accu_data,
                                             <link linkend="GSignalCMarshaller">GSignalCMarshaller</link> c_marshaller,
                                             <link linkend="GType">GType</link> return_type,
                                             <link linkend="guint">guint</link> n_params,
                                             <link linkend="GType">GType</link> *param_types);
<link linkend="guint">guint</link>       <link linkend="g-signal-new-valist">g_signal_new_valist</link>             (const <link linkend="gchar">gchar</link> *signal_name,
                                             <link linkend="GType">GType</link> itype,
                                             <link linkend="GSignalFlags">GSignalFlags</link> signal_flags,
                                             <link linkend="GClosure">GClosure</link> *class_closure,
                                             <link linkend="GSignalAccumulator">GSignalAccumulator</link> accumulator,
                                             <link linkend="gpointer">gpointer</link> accu_data,
                                             <link linkend="GSignalCMarshaller">GSignalCMarshaller</link> c_marshaller,
                                             <link linkend="GType">GType</link> return_type,
                                             <link linkend="guint">guint</link> n_params,
                                             va_list args);
void        <link linkend="g-signal-query">g_signal_query</link>                  (<link linkend="guint">guint</link> signal_id,
                                             <link linkend="GSignalQuery">GSignalQuery</link> *query);
<link linkend="guint">guint</link>       <link linkend="g-signal-lookup">g_signal_lookup</link>                 (const <link linkend="gchar">gchar</link> *name,
                                             <link linkend="GType">GType</link> itype);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-signal-name">g_signal_name</link>         (<link linkend="guint">guint</link> signal_id);
<link linkend="guint">guint</link>*      <link linkend="g-signal-list-ids">g_signal_list_ids</link>               (<link linkend="GType">GType</link> itype,
                                             <link linkend="guint">guint</link> *n_ids);
void        <link linkend="g-signal-emit">g_signal_emit</link>                   (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             ...);
void        <link linkend="g-signal-emit-by-name">g_signal_emit_by_name</link>           (<link linkend="gpointer">gpointer</link> instance,
                                             const <link linkend="gchar">gchar</link> *detailed_signal,
                                             ...);
void        <link linkend="g-signal-emitv">g_signal_emitv</link>                  (const <link linkend="GValue">GValue</link> *instance_and_params,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             <link linkend="GValue">GValue</link> *return_value);
void        <link linkend="g-signal-emit-valist">g_signal_emit_valist</link>            (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             va_list var_args);
#define     <link linkend="g-signal-connect">g_signal_connect</link>                (instance, detailed_signal, c_handler, data)
#define     <link linkend="g-signal-connect-after">g_signal_connect_after</link>          (instance, detailed_signal, c_handler, data)
#define     <link linkend="g-signal-connect-swapped">g_signal_connect_swapped</link>        (instance, detailed_signal, c_handler, data)
<link linkend="gulong">gulong</link>      <link linkend="g-signal-connect-object">g_signal_connect_object</link>         (<link linkend="gpointer">gpointer</link> instance,
                                             const <link linkend="gchar">gchar</link> *detailed_signal,
                                             <link linkend="GCallback">GCallback</link> c_handler,
                                             <link linkend="gpointer">gpointer</link> gobject,
                                             <link linkend="GConnectFlags">GConnectFlags</link> connect_flags);
enum        <link linkend="GConnectFlags">GConnectFlags</link>;
<link linkend="gulong">gulong</link>      <link linkend="g-signal-connect-data">g_signal_connect_data</link>           (<link linkend="gpointer">gpointer</link> instance,
                                             const <link linkend="gchar">gchar</link> *detailed_signal,
                                             <link linkend="GCallback">GCallback</link> c_handler,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GClosureNotify">GClosureNotify</link> destroy_data,
                                             <link linkend="GConnectFlags">GConnectFlags</link> connect_flags);
<link linkend="gulong">gulong</link>      <link linkend="g-signal-connect-closure">g_signal_connect_closure</link>        (<link linkend="gpointer">gpointer</link> instance,
                                             const <link linkend="gchar">gchar</link> *detailed_signal,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gboolean">gboolean</link> after);
<link linkend="gulong">gulong</link>      <link linkend="g-signal-connect-closure-by-id">g_signal_connect_closure_by_id</link>  (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gboolean">gboolean</link> after);
void        <link linkend="g-signal-handler-block">g_signal_handler_block</link>          (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="gulong">gulong</link> handler_id);
void        <link linkend="g-signal-handler-unblock">g_signal_handler_unblock</link>        (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="gulong">gulong</link> handler_id);
void        <link linkend="g-signal-handler-disconnect">g_signal_handler_disconnect</link>     (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="gulong">gulong</link> handler_id);
<link linkend="gulong">gulong</link>      <link linkend="g-signal-handler-find">g_signal_handler_find</link>           (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="GSignalMatchType">GSignalMatchType</link> mask,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> func,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="guint">guint</link>       <link linkend="g-signal-handlers-block-matched">g_signal_handlers_block_matched</link> (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="GSignalMatchType">GSignalMatchType</link> mask,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> func,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="guint">guint</link>       <link linkend="g-signal-handlers-unblock-matched">g_signal_handlers_unblock_matched</link>
                                            (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="GSignalMatchType">GSignalMatchType</link> mask,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> func,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="guint">guint</link>       <link linkend="g-signal-handlers-disconnect-matched">g_signal_handlers_disconnect_matched</link>
                                            (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="GSignalMatchType">GSignalMatchType</link> mask,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             <link linkend="GClosure">GClosure</link> *closure,
                                             <link linkend="gpointer">gpointer</link> func,
                                             <link linkend="gpointer">gpointer</link> data);
<link linkend="gboolean">gboolean</link>    <link linkend="g-signal-handler-is-connected">g_signal_handler_is_connected</link>   (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="gulong">gulong</link> handler_id);
#define     <link linkend="g-signal-handlers-block-by-func">g_signal_handlers_block_by_func</link> (instance, func, data)
#define     <link linkend="g-signal-handlers-unblock-by-func">g_signal_handlers_unblock_by_func</link>(instance, func, data)
#define     <link linkend="g-signal-handlers-disconnect-by-func">g_signal_handlers_disconnect_by_func</link>(instance, func, data)
<link linkend="gboolean">gboolean</link>    <link linkend="g-signal-has-handler-pending">g_signal_has_handler_pending</link>    (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail,
                                             <link linkend="gboolean">gboolean</link> may_be_blocked);
void        <link linkend="g-signal-stop-emission">g_signal_stop_emission</link>          (<link linkend="gpointer">gpointer</link> instance,
                                             <link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> detail);
void        <link linkend="g-signal-stop-emission-by-name">g_signal_stop_emission_by_name</link>  (<link linkend="gpointer">gpointer</link> instance,
                                             const <link linkend="gchar">gchar</link> *detailed_signal);
void        <link linkend="g-signal-override-class-closure">g_signal_override_class_closure</link> (<link linkend="guint">guint</link> signal_id,
                                             <link linkend="GType">GType</link> instance_type,
                                             <link linkend="GClosure">GClosure</link> *class_closure);
void        <link linkend="g-signal-chain-from-overridden">g_signal_chain_from_overridden</link>  (const <link linkend="GValue">GValue</link> *instance_and_params,
                                             <link linkend="GValue">GValue</link> *return_value);
<link linkend="gulong">gulong</link>      <link linkend="g-signal-add-emission-hook">g_signal_add_emission_hook</link>      (<link linkend="guint">guint</link> signal_id,
                                             <link linkend="GQuark">GQuark</link> quark,
                                             <link linkend="GSignalEmissionHook">GSignalEmissionHook</link> hook_func,
                                             <link linkend="gpointer">gpointer</link> hook_data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> data_destroy);
void        <link linkend="g-signal-remove-emission-hook">g_signal_remove_emission_hook</link>   (<link linkend="guint">guint</link> signal_id,
                                             <link linkend="gulong">gulong</link> hook_id);
<link linkend="gboolean">gboolean</link>    <link linkend="g-signal-parse-name">g_signal_parse_name</link>             (const <link linkend="gchar">gchar</link> *detailed_signal,
                                             <link linkend="GType">GType</link> itype,
                                             <link linkend="guint">guint</link> *signal_id_p,
                                             <link linkend="GQuark">GQuark</link> *detail_p,
                                             <link linkend="gboolean">gboolean</link> force_detail_quark);
<link linkend="GSignalInvocationHint">GSignalInvocationHint</link>* <link linkend="g-signal-get-invocation-hint">g_signal_get_invocation_hint</link>
                                            (<link linkend="gpointer">gpointer</link> instance);
void        <link linkend="g-signal-handlers-destroy">g_signal_handlers_destroy</link>       (<link linkend="gpointer">gpointer</link> instance);
<link linkend="GClosure">GClosure</link>*   <link linkend="g-signal-type-cclosure-new">g_signal_type_cclosure_new</link>      (<link linkend="GType">GType</link> itype,
                                             <link linkend="guint">guint</link> struct_offset);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
The basic concept of the signal system is that of the <emphasis>emission</emphasis>
of a signal.
Signals are introduced per-type and are identified through strings.
Signals introduced for a parent type are available in derived types as well,
so basically they are a per-type facility that is inherited.
A signal emission mainly involves invocation of a certain set of callbacks in
precisely defined manner. There are two main categories of such callbacks,
per-object
	<footnote><para>Although signals can deal with any kind of instantiatable type,
	i'm referring to those types as "object types" in the following, simply
	because that is the context most users will encounter signals in.
	</para></footnote>
ones and user provided ones.
The per-object callbacks are most often referred to as "object method
handler" or "default (signal) handler", while user provided callbacks are
usually just called "signal handler".
The object method handler is provided at signal creation time (this most
frequently happens at the end of an object class' creation), while user
provided handlers are frequently connected and disconnected to/from a certain
signal on certain object instances.
</para>
<para>
A signal emission consists of five stages, unless prematurely stopped:
<variablelist>
  <varlistentry><term></term><listitem><para>
	1 - Invocation of the object method handler for <literal>G_SIGNAL_RUN_FIRST</literal> signals
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
	2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag <literal>FALSE</literal>)
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
	3 - Invocation of the object method handler for <literal>G_SIGNAL_RUN_LAST</literal> signals
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
	4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of <literal>TRUE</literal>
  </para></listitem></varlistentry>
  <varlistentry><term></term><listitem><para>
	5 - Invocation of the object method handler for <literal>G_SIGNAL_RUN_CLEANUP</literal> signals
  </para></listitem></varlistentry>
</variablelist>
The user provided signal handlers are called in the order they were
connected in.
All handlers may prematurely stop a signal emission, and any number of
handlers may be connected, disconnected, blocked or unblocked during
a signal emission.
There are certain criteria for skipping user handlers in stages 2 and 4
of a signal emission.
First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted
during callback invocation, to return from the "blocked" state, a
handler has to get unblocked exactly the same amount of times
it has been blocked before.
Second, upon emission of a <literal>G_SIGNAL_DETAILED</literal> signal, an additional
"detail" argument passed in to <link linkend="g-signal-emit">g_signal_emit</link>() has to match the detail
argument of the signal handler currently subject to invocation.
Specification of no detail argument for signal handlers (omission of the
detail part of the signal specification upon connection) serves as a
wildcard and matches any detail argument passed in to emission.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GSignalInvocationHint">struct GSignalInvocationHint</title>
<programlisting>struct GSignalInvocationHint
{