signals.sgml

This GLib version 2.16.1. GLib is the low-level core library that forms the basis for projects such

</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 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