| <!-- ##### 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: |
| @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" 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. |
| @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 @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 #GDestroyNotify 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 #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. 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 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 |
| |
| |