mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-30 17:36:16 +01:00
dfa8c540a1
Thu Oct 23 12:38:24 2003 Owen Taylor <otaylor@redhat.com>
* === Released 2.3.0 ===
* tests/gobject/Makefile.am (dist-hook): Remove
and extra backslash.
* tests/gobject/Makefile.am (EXTRA_DIST): Add
testmarshal.list.
* glib/Makefile.am (libglib_2_0_la_SOURCES): Add
missing gunicode-private.h.
* tests/testglib.c (main): Fix a warning.
* tests/gobject/ifaceinherit.c: Remove check that
wasn't supposed to work (adding an interface already
added to the derived class to the base class),
fix a bug.
895 lines
33 KiB
Plaintext
895 lines
33 KiB
Plaintext
<!-- ##### 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>
|
|
|
|
<!-- ##### 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:
|
|
@data:
|
|
@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" appendixes 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 by third-party code generically callable object methods.
|
|
@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.
|
|
@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.
|
|
@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.
|
|
@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 object stays alive during the call to @c_handler.
|
|
</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.
|
|
</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 #GDestroyNotify 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 amount of handlers that got blocked.
|
|
|
|
|
|
<!-- ##### 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 amount of handlers that got unblocked.
|
|
|
|
|
|
<!-- ##### 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 amount of handlers that got disconnected.
|
|
|
|
|
|
<!-- ##### 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 got blocked.
|
|
|
|
|
|
<!-- ##### 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 got unblocked.
|
|
|
|
|
|
<!-- ##### 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 got disconnected.
|
|
|
|
|
|
<!-- ##### 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.
|
|
</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 invokced, 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
|
|
|
|
|