-<!-- ##### SECTION Title ##### -->
-Signals
-
-<!-- ##### SECTION Short_Description ##### -->
-A means for customization of object behaviour and a general purpose notification mechanism
-
-<!-- ##### SECTION Long_Description ##### -->
-<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 %G_SIGNAL_RUN_FIRST signals
- </para></listitem></varlistentry>
- <varlistentry><term></term><listitem><para>
- 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE)
- </para></listitem></varlistentry>
- <varlistentry><term></term><listitem><para>
- 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
- </para></listitem></varlistentry>
- <varlistentry><term></term><listitem><para>
- 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE
- </para></listitem></varlistentry>
- <varlistentry><term></term><listitem><para>
- 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP 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 %G_SIGNAL_DETAILED signal, an additional
-"detail" argument passed in to g_signal_emit() 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>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GSignalInvocationHint ##### -->
-<para>
-The #GSignalInvocationHint structure is used to pass on additional information
-to callbacks during a signal emission.
-</para>
-
-@signal_id: The signal id of the signal invoking the callback
-@detail: The detail passed on for this emission
-@run_type: The stage the signal emission is currently in, this
- field will contain one of %G_SIGNAL_RUN_FIRST,
- %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP.
-
-<!-- ##### USER_FUNCTION GSignalAccumulator ##### -->
-<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>
-
-@ihint: Signal invocation hint, see #GSignalInvocationHint.
-@return_accu: Accumulator to collect callback return values in, this
- is the return value of the current signal emission.
-@handler_return: A #GValue holding the return value of the signal handler.
-@data: Callback data that was specified when creating the signal.
-@Returns: The accumulator function returns whether the signal emission
- should be aborted. Returning %FALSE means to abort the
- current emission and %TRUE is returned for continuation.
-
-
-<!-- ##### TYPEDEF GSignalCMarshaller ##### -->
-<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 #GClosureMarshal since the #GClosure
-mechanism takes over responsibility of actual function invocation for the
-signal system.
-</para>
-
-
-<!-- ##### USER_FUNCTION GSignalEmissionHook ##### -->
-<para>
-A simple function pointer to get invoked when the signal is emitted. This
-allows you to tie a hook to the signal type, so that it will trap all
-emissions of that signal, from any object.
-</para>
-<para>
-You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
-</para>
-
-@ihint: Signal invocation hint, see #GSignalInvocationHint.
-@n_param_values: the number of parameters to the function, including
- the instance on which the signal was emitted.
-@param_values: the instance on which the signal was emitted, followed by the
- parameters of the emission.
-@data: user data associated with the hook.
-@Returns: whether it wants to stay connected. If it returns %FALSE, the signal
- hook is disconnected (and destroyed).
-
-
-<!-- ##### ENUM GSignalFlags ##### -->
-<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>
-
-@G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage.
-@G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage.
-@G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage.
-@G_SIGNAL_NO_RECURSE: 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.
-@G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name
- upon handler connections and emissions.
-@G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive
- objects from user code via g_signal_emit() 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 object methods which can be called generically by
- third-party code.
-@G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal.
-
-<!-- ##### ENUM GSignalMatchType ##### -->
-<para>
-The match types specify what g_signal_handlers_block_matched(),
-g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched()
-match signals by.
-</para>
-
-@G_SIGNAL_MATCH_ID: The signal id must be equal.
-@G_SIGNAL_MATCH_DETAIL: The signal detail be equal.
-@G_SIGNAL_MATCH_CLOSURE: The closure must be the same.
-@G_SIGNAL_MATCH_FUNC: The C closure callback must be the same.
-@G_SIGNAL_MATCH_DATA: The closure data must be the same.
-@G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched.
-
-<!-- ##### STRUCT GSignalQuery ##### -->
-<para>
-A structure holding in-depth information for a specific signal. It is
-filled in by the g_signal_query() function.
-</para>
-
-@signal_id: The signal id of the signal being queried, or 0 if the
- signal to be queried was unknown.
-@signal_name: The signal name.
-@itype: The interface/instance type that this signal can be emitted for.
-@signal_flags: The signal flags as passed in to g_signal_new().
-@return_type: The return type for user callbacks.
-@n_params: The number of parameters that user callbacks take.
-@param_types: The individual parameter types for user callbacks, note that the
- effective callback signature is:
-<programlisting>
-@return_type callback (#gpointer data1,
- [#param_types param_names,]
- #gpointer data2);
-</programlisting>
-
-<!-- ##### MACRO G_SIGNAL_TYPE_STATIC_SCOPE ##### -->
-<para>
-This macro flags signal argument types for which the signal system may
-assume that instances thereof remain persistent across all signal emissions
-they are used in. This is only useful for non ref-counted, value-copy types.
-</para>
-<para>
-To flag a signal argument in this way, add
-<literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument
-of g_signal_new().
-</para>
-<informalexample>
-<programlisting>
- g_signal_new ("size_request",
- G_TYPE_FROM_CLASS (gobject_class),
- G_SIGNAL_RUN_FIRST,
- G_STRUCT_OFFSET (GtkWidgetClass, size_request),
- NULL, NULL,
- _gtk_marshal_VOID__BOXED,
- G_TYPE_NONE, 1,
- GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
-</programlisting>
-</informalexample>
-
-
-
-<!-- ##### MACRO G_SIGNAL_MATCH_MASK ##### -->
-<para>
-A mask for all #GSignalMatchType bits.
-</para>
-
-
-
-<!-- ##### MACRO G_SIGNAL_FLAGS_MASK ##### -->
-<para>
-A mask for all #GSignalFlags bits.
-</para>
-
-
-
-<!-- ##### FUNCTION g_signal_new ##### -->
-<para>
-Creates a new signal. (This is usually done in the class initializer.)
-</para>
-<para>
-A signal name consists of segments consisting of ASCII letters and
-digits, separated by either the '-' or '_' character. The first
-character of a signal name must be a letter. Names which violate these
-rules lead to undefined behaviour of the GSignal system.
-</para>
-<para>
-When registering a signal and looking up a signal, either separator can
-be used, but they cannot be mixed.
-</para>
-
-@signal_name: the name for the signal
-@itype: the type this signal pertains to. It will also pertain to
- types which are derived from this type.
-@signal_flags: a combination of #GSignalFlags specifying detail of when
- the default handler is to be invoked. You should at least specify
- %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
-@class_offset: The offset of the function pointer in the class structure
- for this type. Used to invoke a class method generically. Pass 0 to
- not associate a class method with this signal.
-@accumulator: the accumulator for this signal; may be %NULL.
-@accu_data: user data for the @accumulator.
-@c_marshaller: the function to translate arrays of parameter values to
- signal emissions into C language callback invocations.
-@return_type: the type of return value, or #G_TYPE_NONE for a signal
- without a return value.
-@n_params: the number of parameter types to follow.
-@Varargs: a list of types, one for each parameter.
-@Returns: the signal id
-
-
-<!-- ##### FUNCTION g_signal_newv ##### -->
-<para>
-Creates a new signal. (This is usually done in the class initializer.)
-</para>
-<para>
-See g_signal_new() for details on allowed signal names.
-</para>
-
-@signal_name: the name for the signal
-@itype: the type this signal pertains to. It will also pertain to
- types which are derived from this type.
-@signal_flags: a combination of #GSignalFlags specifying detail of when
- the default handler is to be invoked. You should at least specify
- %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
-@class_closure: The closure to invoke on signal emission; may be %NULL.
-@accumulator: the accumulator for this signal; may be %NULL.
-@accu_data: user data for the @accumulator.
-@c_marshaller: the function to translate arrays of parameter values to
- signal emissions into C language callback invocations.
-@return_type: the type of return value, or #G_TYPE_NONE for a signal
- without a return value.
-@n_params: the length of @param_types.
-@param_types: an array types, one for each parameter.
-@Returns: the signal id
-
-
-<!-- ##### FUNCTION g_signal_new_valist ##### -->
-<para>
-Creates a new signal. (This is usually done in the class initializer.)
-</para>
-<para>
-See g_signal_new() for details on allowed signal names.
-</para>
-
-@signal_name: the name for the signal
-@itype: the type this signal pertains to. It will also pertain to
- types which are derived from this type.
-@signal_flags: a combination of #GSignalFlags specifying detail of when
- the default handler is to be invoked. You should at least specify
- %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
-@class_closure: The closure to invoke on signal emission; may be %NULL.
-@accumulator: the accumulator for this signal; may be %NULL.
-@accu_data: user data for the @accumulator.
-@c_marshaller: the function to translate arrays of parameter values to
- signal emissions into C language callback invocations.
-@return_type: the type of return value, or #G_TYPE_NONE for a signal
- without a return value.
-@n_params: the number of parameter types in @args.
-@args: va_list of #GType, one for each parameter.
-@Returns: the signal id
-
-
-<!-- ##### FUNCTION g_signal_query ##### -->
-<para>
-Queries the signal system for in-depth information about a
-specific signal. This function will fill in a user-provided
-structure to hold signal-specific information. If an invalid
-signal id is passed in, the @signal_id member of the #GSignalQuery
-is 0. All members filled into the #GSignalQuery structure should
-be considered constant and have to be left untouched.
-</para>
-
-@signal_id: The signal id of the signal to query information for.
-@query: A user provided structure that is filled in with constant
- values upon success.
-
-
-<!-- ##### FUNCTION g_signal_lookup ##### -->
-<para>
-Given the name of the signal and the type of object it connects to, gets
-the signal's identifying integer. Emitting the signal by number is
-somewhat faster than using the name each time.
-</para>
-<para>
-Also tries the ancestors of the given type.
-</para>
-<para>
-See g_signal_new() for details on allowed signal names.
-</para>
-
-@name: the signal's name.
-@itype: the type that the signal operates on.
-@Returns: the signal's identifying number, or 0 if no signal was found.
-
-
-<!-- ##### FUNCTION g_signal_name ##### -->
-<para>
-Given the signal's identifier, finds its name.
-</para>
-<para>
-Two different signals may have the same name, if they have differing types.
-</para>
-
-@signal_id: the signal's identifying number.
-@Returns: the signal name, or %NULL if the signal number was invalid.
-
-
-<!-- ##### FUNCTION g_signal_list_ids ##### -->
-<para>
-Lists the signals by id that a certain instance or interface type
-created. Further information about the signals can be acquired through
-g_signal_query().
-</para>
-
-@itype: Instance or interface type.
-@n_ids: Location to store the number of signal ids for @itype.
-@Returns: Newly allocated array of signal IDs.
-
-
-<!-- ##### FUNCTION g_signal_emit ##### -->
-<para>
-Emits a signal.
-</para>
-<para>
-Note that g_signal_emit() resets the return value to the default
-if no handlers are connected, in contrast to g_signal_emitv().
-</para>
-
-@instance: the instance the signal is being emitted on.
-@signal_id: the signal id
-@detail: the detail
-@Varargs: parameters to be passed to the signal, followed by a
- location for the return value. If the return type of the signal
- is #G_TYPE_NONE, the return value location can be omitted.
-
-
-<!-- ##### FUNCTION g_signal_emit_by_name ##### -->
-<para>
-Emits a signal.
-</para>
-<para>
-Note that g_signal_emit_by_name() resets the return value to the default
-if no handlers are connected, in contrast to g_signal_emitv().
-</para>
-
-@instance: the instance the signal is being emitted on.
-@detailed_signal: a string of the form "signal-name::detail".
-@Varargs: parameters to be passed to the signal, followed by a
- location for the return value. If the return type of the signal
- is #G_TYPE_NONE, the return value location can be omitted.
-
-
-<!-- ##### FUNCTION g_signal_emitv ##### -->
-<para>
-Emits a signal.
-</para>
-<para>
-Note that g_signal_emitv() doesn't change @return_value if no handlers are
-connected, in contrast to g_signal_emit() and g_signal_emit_valist().
-</para>
-
-@instance_and_params: argument list for the signal emission. The first
- element in the array is a #GValue for the instance the signal is
- being emitted on. The rest are any arguments to be passed to the
- signal.
-@signal_id: the signal id
-@detail: the detail
-@return_value: Location to store the return value of the signal emission.
-
-
-<!-- ##### FUNCTION g_signal_emit_valist ##### -->
-<para>
-Emits a signal.
-</para>
-<para>
-Note that g_signal_emit_valist() resets the return value to the default
-if no handlers are connected, in contrast to g_signal_emitv().
-</para>
-
-@instance: the instance the signal is being emitted on.
-@signal_id: the signal id
-@detail: the detail
-@var_args: a list of parameters to be passed to the signal, followed by a
- location for the return value. If the return type of the signal
- is #G_TYPE_NONE, the return value location can be omitted.
-
-
-<!-- ##### MACRO g_signal_connect ##### -->
-<para>
-Connects a #GCallback function to a signal for a particular object.
-</para>
-<para>
-The handler will be called before the default handler of the signal.
-</para>
-
-@instance: the instance to connect to.
-@detailed_signal: a string of the form "signal-name::detail".
-@c_handler: the #GCallback to connect.
-@data: data to pass to @c_handler calls.
-@Returns: the handler id
-
-
-<!-- ##### MACRO g_signal_connect_after ##### -->
-<para>
-Connects a #GCallback function to a signal for a particular object.
-</para>
-<para>
-The handler will be called after the default handler of the signal.
-</para>
-
-@instance: the instance to connect to.
-@detailed_signal: a string of the form "signal-name::detail".
-@c_handler: the #GCallback to connect.
-@data: data to pass to @c_handler calls.
-@Returns: the handler id
-
-
-<!-- ##### MACRO g_signal_connect_swapped ##### -->
-<para>
-Connects a #GCallback function to a signal for a particular object.
-</para>
-<para>
-The instance on which the signal is emitted and @data will be swapped when
-calling the handler.
-</para>
-
-@instance: the instance to connect to.
-@detailed_signal: a string of the form "signal-name::detail".
-@c_handler: the #GCallback to connect.
-@data: data to pass to @c_handler calls.
-@Returns: the handler id
-
-
-<!-- ##### FUNCTION g_signal_connect_object ##### -->
-<para>
- This is similar to g_signal_connect_data(), but uses a closure which
- ensures that the @gobject stays alive during the call to @c_handler
- by temporarily adding a reference count to @gobject.
-</para>
-<para>
- Note that there is a bug in GObject that makes this function
- much less useful than it might seem otherwise. Once @gobject is
- disposed, the callback will no longer be called, but, the signal
- handler is <emphasis>not</emphasis> currently disconnected. If the
- @instance is itself being freed at the same time than this doesn't
- matter, since the signal will automatically be removed, but
- if @instance persists, then the signal handler will leak. You
- should not remove the signal yourself because in a future versions of
- GObject, the handler <emphasis>will</emphasis> automatically
- be disconnected.
-</para>
-<para>
- It's possible to work around this problem in a way that will
- continue to work with future versions of GObject by checking
- that the signal handler is still connected before disconnected it:
-<informalexample><programlisting>
- if (g_signal_handler_is_connected (instance, id))
- g_signal_handler_disconnect (instance, id);
-</programlisting></informalexample>
-</para>
-
-@instance: the instance to connect to.
-@detailed_signal: a string of the form "signal-name::detail".
-@c_handler: the #GCallback to connect.
-@gobject: the object to pass as data to @c_handler.
-@connect_flags: a combination of #GConnnectFlags.
-@Returns: the handler id.
-
-
-<!-- ##### ENUM GConnectFlags ##### -->
-<para>
-The connection flags are used to specify the behaviour of a signal's
-connection.
-</para>
-
-@G_CONNECT_AFTER: whether the handler should be called before or after the
- default handler of the signal.
-@G_CONNECT_SWAPPED: whether the instance and data should be swapped when
- calling the handler.
-
-<!-- ##### FUNCTION g_signal_connect_data ##### -->
-<para>
-Connects a #GCallback function to a signal for a particular object. Similar
-to g_signal_connect(), but allows to provide a #GClosureNotify for the data
-which will be called when the signal handler is disconnected and no longer
-used. Specify @connect_flags if you need <literal>..._after()</literal> pr
-<literal>..._swapped()</literal> variants of this function.
-</para>
-
-@instance: the instance to connect to.
-@detailed_signal: a string of the form "signal-name::detail".
-@c_handler: the #GCallback to connect.
-@data: data to pass to @c_handler calls.
-@destroy_data: a #GClosureNotify for @data.
-@connect_flags: a combination of #GConnectFlags.
-@Returns: the handler id
-
-
-<!-- ##### FUNCTION g_signal_connect_closure ##### -->
-<para>
-Connects a closure to a signal for a particular object.
-</para>
-
-@instance: the instance to connect to.
-@detailed_signal: a string of the form "signal-name::detail".
-@closure: the closure to connect.
-@after: whether the handler should be called before or after the
- default handler of the signal.
-@Returns: the handler id
-
-
-<!-- ##### FUNCTION g_signal_connect_closure_by_id ##### -->
-<para>
-Connects a closure to a signal for a particular object.
-</para>
-
-@instance: the instance to connect to.
-@signal_id: the id of the signal.
-@detail: the detail.
-@closure: the closure to connect.
-@after: whether the handler should be called before or after the
- default handler of the signal.
-@Returns: the handler id
-
-
-<!-- ##### FUNCTION g_signal_handler_block ##### -->
-<para>
-Blocks a handler of an instance so it will not be called during
-any signal emissions unless it is unblocked again. Thus "blocking"
-a signal handler means to temporarily deactive it, a signal handler
-has to be unblocked exactly the same amount of times it has been
-blocked before to become active again.
-</para>
-<para>
-The @handler_id has to be a valid signal handler id, connected to a
-signal of @instance.
-</para>
-
-@instance: The instance to block the signal handler of.
-@handler_id: Handler id of the handler to be blocked.
-
-
-<!-- ##### FUNCTION g_signal_handler_unblock ##### -->
-<para>
-Undoes the effect of a previous g_signal_handler_block() call.
-A blocked handler is skipped during signal emissions and will not be
-invoked, unblocking it (for exactly the amount of times it has been
-blocked before) reverts its "blocked" state, so the handler will be
-recognized by the signal system and is called upon future or currently
-ongoing signal emissions (since the order in which handlers are
-called during signal emissions is deterministic, whether the
-unblocked handler in question is called as part of a currently
-ongoing emission depends on how far that emission has proceeded
-yet).
-</para>
-<para>
-The @handler_id has to be a valid id of a signal handler that is
-connected to a signal of @instance and is currently blocked.
-</para>
-
-@instance: The instance to unblock the signal handler of.
-@handler_id: Handler id of the handler to be unblocked.
-
-
-<!-- ##### FUNCTION g_signal_handler_disconnect ##### -->
-<para>
-Disconnects a handler from an instance so it will not be called during
-any future or currently ongoing emissions of the signal it has been
-connected to. The @handler_id becomes invalid and may be reused.
-</para>
-<para>
-The @handler_id has to be a valid signal handler id, connected to a
-signal of @instance.
-</para>
-
-@instance: The instance to remove the signal handler from.
-@handler_id: Handler id of the handler to be disconnected.
-
-
-<!-- ##### FUNCTION g_signal_handler_find ##### -->
-<para>
-Finds the first signal handler that matches certain selection criteria.
-The criteria mask is passed as an OR-ed combination of #GSignalMatchType
-flags, and the criteria values are passed as arguments.
-The match @mask has to be non-0 for successful matches.
-If no handler was found, 0 is returned.
-</para>
-
-@instance: The instance owning the signal handler to be found.
-@mask: Mask indicating which of @signal_id, @detail, @closure, @func
- and/or @data the handler has to match.
-@signal_id: Signal the handler has to be connected to.
-@detail: Signal detail the handler has to be connected to.
-@closure: The closure the handler will invoke.
-@func: The C closure callback of the handler (useless for non-C closures).
-@data: The closure data of the handler's closure.
-@Returns: A valid non-0 signal handler id for a successful match.
-
-
-<!-- ##### FUNCTION g_signal_handlers_block_matched ##### -->
-<para>
-Blocks all handlers on an instance that match a certain selection criteria.
-The criteria mask is passed as an OR-ed combination of #GSignalMatchType
-flags, and the criteria values are passed as arguments.
-Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
-or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
-If no handlers were found, 0 is returned, the number of blocked handlers
-otherwise.
-</para>
-
-@instance: The instance to block handlers from.
-@mask: Mask indicating which of @signal_id, @detail, @closure, @func
- and/or @data the handlers have to match.
-@signal_id: Signal the handlers have to be connected to.
-@detail: Signal detail the handlers have to be connected to.
-@closure: The closure the handlers will invoke.
-@func: The C closure callback of the handlers (useless for non-C closures).
-@data: The closure data of the handlers' closures.
-@Returns: The number of handlers that matched.
-
-
-<!-- ##### FUNCTION g_signal_handlers_unblock_matched ##### -->
-<para>
-Unblocks all handlers on an instance that match a certain selection
-criteria. The criteria mask is passed as an OR-ed combination of
-#GSignalMatchType flags, and the criteria values are passed as arguments.
-Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
-or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
-If no handlers were found, 0 is returned, the number of unblocked handlers
-otherwise. The match criteria should not apply to any handlers that are
-not currently blocked.
-</para>
-
-@instance: The instance to unblock handlers from.
-@mask: Mask indicating which of @signal_id, @detail, @closure, @func
- and/or @data the handlers have to match.
-@signal_id: Signal the handlers have to be connected to.
-@detail: Signal detail the handlers have to be connected to.
-@closure: The closure the handlers will invoke.
-@func: The C closure callback of the handlers (useless for non-C closures).
-@data: The closure data of the handlers' closures.
-@Returns: The number of handlers that matched.
-
-
-<!-- ##### FUNCTION g_signal_handlers_disconnect_matched ##### -->
-<para>
-Disconnects all handlers on an instance that match a certain selection
-criteria. The criteria mask is passed as an OR-ed combination of
-#GSignalMatchType flags, and the criteria values are passed as arguments.
-Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
-or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
-If no handlers were found, 0 is returned, the number of disconnected
-handlers otherwise.
-</para>
-
-@instance: The instance to remove handlers from.
-@mask: Mask indicating which of @signal_id, @detail, @closure, @func
- and/or @data the handlers have to match.
-@signal_id: Signal the handlers have to be connected to.
-@detail: Signal detail the handlers have to be connected to.
-@closure: The closure the handlers will invoke.
-@func: The C closure callback of the handlers (useless for non-C closures).
-@data: The closure data of the handlers' closures.
-@Returns: The number of handlers that matched.
-
-
-<!-- ##### FUNCTION g_signal_handler_is_connected ##### -->
-<para>
-Returns whether @handler_id is the id of a handler connected to @instance.
-</para>
-
-@instance: The instance where a signal handler is sought.
-@handler_id: the handler id.
-@Returns: whether @handler_id identifies a handler connected to @instance.
-
-
-<!-- ##### MACRO g_signal_handlers_block_by_func ##### -->
-<para>
-Blocks all handlers on an instance that match @func and @data.
-</para>
-
-@instance: The instance to block handlers from.
-@func: The C closure callback of the handlers (useless for non-C closures).
-@data: The closure data of the handlers' closures.
-@Returns: The number of handlers that matched.
-
-
-<!-- ##### MACRO g_signal_handlers_unblock_by_func ##### -->
-<para>
-Unblocks all handlers on an instance that match @func and @data.
-</para>
-
-@instance: The instance to unblock handlers from.
-@func: The C closure callback of the handlers (useless for non-C closures).
-@data: The closure data of the handlers' closures.
-@Returns: The number of handlers that matched.
-
-
-<!-- ##### MACRO g_signal_handlers_disconnect_by_func ##### -->
-<para>
-Disconnects all handlers on an instance that match @func and @data.
-</para>
-
-@instance: The instance to remove handlers from.
-@func: The C closure callback of the handlers (useless for non-C closures).
-@data: The closure data of the handlers' closures.
-@Returns: The number of handlers that matched.
-
-
-<!-- ##### FUNCTION g_signal_has_handler_pending ##### -->
-<para>
-Returns whether there are any handlers connected to @instance for the
-given signal id and detail.
-</para>
-<para>
-One example of when you might use this is when the arguments to the
-signal are difficult to compute. A class implementor may opt to not emit
-the signal if no one is attached anyway, thus saving the cost of building
-the arguments.
-</para>
-
-@instance: the object whose signal handlers are sought.
-@signal_id: the signal id.
-@detail: the detail.
-@may_be_blocked: whether blocked handlers should count as match.
-@Returns: %TRUE if a handler is connected to the signal,
- %FALSE otherwise.
-
-
-<!-- ##### FUNCTION g_signal_stop_emission ##### -->
-<para>
-Stops a signal's current emission.
-</para>
-<para>
-This will prevent the default method from running, if the signal was
-%G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after"
-flag).
-</para>
-<para>
-Prints a warning if used on a signal which isn't being emitted.
-</para>
-
-@instance: the object whose signal handlers you wish to stop.
-@signal_id: the signal identifier, as returned by g_signal_lookup().
-@detail: the detail which the signal was emitted with.
-
-
-<!-- ##### FUNCTION g_signal_stop_emission_by_name ##### -->
-<para>
-Stops a signal's current emission.
-</para>
-<para>
-This is just like g_signal_stop_emission() except it will look up the
-signal id for you.
-</para>
-
-@instance: the object whose signal handlers you wish to stop.
-@detailed_signal: a string of the form "signal-name::detail".
-
-
-<!-- ##### FUNCTION g_signal_override_class_closure ##### -->
-<para>
-Overrides the class closure (i.e. the default handler) for the given signal
-for emissions on instances of @instance_type. @instance_type must be derived
-from the type to which the signal belongs.
-</para>
-
-@signal_id: the signal id
-@instance_type: the instance type on which to override the class closure
- for the signal.
-@class_closure: the closure.
-
-
-<!-- ##### FUNCTION g_signal_chain_from_overridden ##### -->
-<para>
-Calls the original class closure of a signal. This function should only
-be called from an overridden class closure; see
-g_signal_override_class_closure().
-</para>
-
-@instance_and_params: the argument list of the signal emission. The first
- element in the array is a #GValue for the instance the signal is being
- emitted on. The rest are any arguments to be passed to the signal.
-@return_value: Location for the return value.
-
-
-<!-- ##### FUNCTION g_signal_add_emission_hook ##### -->
-<para>
-Adds an emission hook for a signal, which will get called for any emission
-of that signal, independent of the instance. This is possible only
-for signals which don't have #G_SIGNAL_NO_HOOKS flag set.
-</para>
-
-@signal_id: the signal identifier, as returned by g_signal_lookup().
-@detail: the detail on which to call the hook.
-@hook_func: a #GSignalEmissionHook function.
-@hook_data: user data for @hook_func.
-@data_destroy: a #GDestroyNotify for @hook_data.
-@Returns: the hook id, for later use with g_signal_remove_emission_hook().
-
-
-<!-- ##### FUNCTION g_signal_remove_emission_hook ##### -->
-<para>
-Deletes an emission hook.
-</para>
-
-@signal_id: the id of the signal
-@hook_id: the id of the emission hook, as returned by
-g_signal_add_emission_hook()
-
-
-<!-- ##### FUNCTION g_signal_parse_name ##### -->
-<para>
-Internal function to parse a signal name into its @signal_id
-and @detail quark.
-</para>
-
-@detailed_signal: a string of the form "signal-name::detail".
-@itype: The interface/instance type that introduced "signal-name".
-@signal_id_p: Location to store the signal id.
-@detail_p: Location to store the detail quark.
-@force_detail_quark: %TRUE forces creation of a #GQuark for the detail.
-@Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values.
-
-
-<!-- ##### FUNCTION g_signal_get_invocation_hint ##### -->
-<para>
-Returns the invocation hint of the innermost signal emission of instance.
-</para>
-
-@instance: the instance to query
-@Returns: the invocation hint of the innermost signal emission.
-
-
-<!-- ##### FUNCTION g_signal_type_cclosure_new ##### -->
-<para>
-Creates a new closure which invokes the function found at the offset
-@struct_offset in the class structure of the interface or classed type
-identified by @itype.
-</para>
-
-@itype: the #GType identifier of an interface or classed type
-@struct_offset: the offset of the member function of @itype's class
- structure which is to be invoked by the new closure
-@Returns: a new #GCClosure
-
-
-<!-- ##### FUNCTION g_signal_accumulator_true_handled ##### -->
-<para>
-A predefined #GSignalAccumulator for signals that return a
-boolean values. The behavior that this accumulator gives is
-that a return of %TRUE stops the signal emission: no further
-callbacks will be invoked, while a return of %FALSE allows
-the emission to coninue. The idea here is that a %TRUE return
-indicates that the callback <emphasis>handled</emphasis> the signal,
-and no further handling is needed.
-</para>
-
-@ihint: standard #GSignalAccumulator parameter
-@return_accu: standard #GSignalAccumulator parameter
-@handler_return: standard #GSignalAccumulator parameter
-@dummy: standard #GSignalAccumulator parameter
-@Returns: standard #GSignalAccumulator result
-@Since: 2.4
-
-