<!-- ##### USER_FUNCTION GSignalEmissionHook ##### -->
<para>
+A simple function pointer to get invoked when the signal is emitted. This
+allows you tie a hook to the signal type, so that it will trap all emissions
+of that signal, from any object.
+You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
</para>
-@ihint:
-@n_param_values:
-@param_values:
-@data:
-@Returns:
-<!-- # Unused Parameters # -->
-@signal_id:
-@n_values:
-@values:
+@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 wished to be removed. If it returns %TRUE, the signal
+ hook is disconnected (and destroyed).
<!-- ##### ENUM GSignalFlags ##### -->
<!-- ##### FUNCTION g_signal_query ##### -->
<para>
-Query 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.
+@signal_id:
+@query:
<!-- ##### FUNCTION g_signal_lookup ##### -->
<!-- ##### FUNCTION g_signal_list_ids ##### -->
<para>
-List 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.
+@itype:
+@n_ids:
+@Returns:
<!-- ##### FUNCTION g_signal_emit ##### -->
@gobject:
@connect_flags:
@Returns:
-<!-- # Unused Parameters # -->
-@swapped:
-@after:
<!-- ##### ENUM GConnectFlags ##### -->
<para>
-
+The connection flags are used to specify the behaviour of a signal's
+connection.
</para>
-@G_CONNECT_AFTER:
-@G_CONNECT_SWAPPED:
+@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>
@destroy_data:
@connect_flags:
@Returns:
-<!-- # Unused Parameters # -->
-@swapped:
-@after:
<!-- ##### FUNCTION g_signal_connect_closure ##### -->
@closure:
@after:
@Returns:
-<!-- # Unused Parameters # -->
-@signal_id:
-@detail:
<!-- ##### FUNCTION g_signal_connect_closure_by_id ##### -->
<!-- ##### FUNCTION g_signal_handler_block ##### -->
<para>
-g_signal_handler_block() 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.
-The @handler_id passed into g_signal_handler_block() 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.
+@instance:
+@handler_id:
<!-- ##### FUNCTION g_signal_handler_unblock ##### -->
<para>
-g_signal_handler_unblock() 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).
-The @handler_id passed into g_signal_handler_unblock() 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.
+@instance:
+@handler_id:
<!-- ##### FUNCTION g_signal_handler_disconnect ##### -->
<para>
-g_signal_handler_disconnect() 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.
-The @handler_id passed into g_signal_handler_disconnect() 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.
+@instance:
+@handler_id:
<!-- ##### FUNCTION g_signal_handler_find ##### -->
<para>
-Find 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.
+@instance:
+@mask:
+@signal_id:
+@detail:
+@closure:
+@func:
+@data:
+@Returns:
<!-- ##### FUNCTION g_signal_handlers_block_matched ##### -->
<para>
-This function 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.
+@instance:
+@mask:
+@signal_id:
+@detail:
+@closure:
+@func:
+@data:
+@Returns:
<!-- ##### FUNCTION g_signal_handlers_unblock_matched ##### -->
<para>
-This function 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.
+@instance:
+@mask:
+@signal_id:
+@detail:
+@closure:
+@func:
+@data:
+@Returns:
<!-- ##### FUNCTION g_signal_handlers_disconnect_matched ##### -->
<para>
-This function 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.
+@instance:
+@mask:
+@signal_id:
+@detail:
+@closure:
+@func:
+@data:
+@Returns:
<!-- ##### FUNCTION g_signal_handler_is_connected ##### -->
@instance_and_params:
@return_value:
-<!-- # Unused Parameters # -->
-@signal_id:
<!-- ##### FUNCTION g_signal_add_emission_hook ##### -->
</para>
@signal_id:
-@quark:
+@detail:
@hook_func:
@hook_data:
@data_destroy:
<!-- ##### FUNCTION g_signal_parse_name ##### -->
<para>
-Internal function to parse a signal names 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 stroe 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.
+@detailed_signal:
+@itype:
+@signal_id_p:
+@detail_p:
+@force_detail_quark:
+@Returns:
<!-- ##### FUNCTION g_signal_get_invocation_hint ##### -->
@Returns:
-<!-- ##### FUNCTION g_signal_handlers_destroy ##### -->
-<para>
-
-</para>
-
-@instance:
-
-
<!-- ##### FUNCTION g_signal_type_cclosure_new ##### -->
<para>
SIGNAL_UNLOCK ();
}
+/**
+ * g_signal_stop_emission:
+ * @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.
+ *
+ * Stops a signal's current emission.
+ *
+ * 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).
+ *
+ * Prints a warning if used on a signal which isn't being emitted.
+ **/
void
g_signal_stop_emission (gpointer instance,
guint signal_id,
}
}
+/**
+ * g_signal_add_emission_hook:
+ * @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.
+ *
+ * Adds an emission hook for a signal, which will get called for any emission
+ * of that signal, independent of the instance.
+ *
+ * Return value: the hook id, for later use with
+ * g_signal_remove_emission_hook().
+ **/
gulong
g_signal_add_emission_hook (guint signal_id,
GQuark detail,
return hook->hook_id;
}
+/**
+ * g_signal_remove_emission_hook:
+ * @signal_id: the id of the signal
+ * @hook_id: the id of the emission hook, as returned by
+ * g_signal_add_emission_hook()
+ *
+ * Deletes an emission hook.
+ **/
void
g_signal_remove_emission_hook (guint signal_id,
gulong hook_id)
return signal_id;
}
+/**
+ * g_signal_parse_name:
+ * @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.
+ *
+ * Internal function to parse a signal name into its @signal_id
+ * and @detail quark.
+ *
+ * Return value: Whether the signal name could successfully be parsed and
+ * @signal_id_p and @detail_p contain valid return values.
+ **/
gboolean
g_signal_parse_name (const gchar *detailed_signal,
GType itype,
return TRUE;
}
+/**
+ * g_signal_stop_emission_by_name:
+ * @instance: the object whose signal handlers you wish to stop.
+ * @detailed_signal: a string of the form "signal-name::detail".
+ *
+ * Stops a signal's current emission.
+ *
+ * This is just like g_signal_stop_emission() except it will look up the
+ * signal id for you.
+ **/
void
g_signal_stop_emission_by_name (gpointer instance,
const gchar *detailed_signal)
SIGNAL_UNLOCK ();
}
+/**
+ * g_signal_lookup:
+ * @name: the signal's name.
+ * @itype: the type that the signal operates on.
+ *
+ * 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.
+ *
+ * Also tries the ancestors of the given type.
+ *
+ * Return value: the signal's identifying number, or 0 if no signal was found.
+ **/
guint
g_signal_lookup (const gchar *name,
GType itype)
{
guint signal_id;
-
g_return_val_if_fail (name != NULL, 0);
g_return_val_if_fail (G_TYPE_IS_INSTANTIATABLE (itype) || G_TYPE_IS_INTERFACE (itype), 0);
return signal_id;
}
+/**
+ * g_signal_list_ids:
+ * @itype: Instance or interface type.
+ * @n_ids: Location to store the number of signal ids for @itype.
+ *
+ * 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().
+ *
+ * Return value: Newly allocated array of signal IDs.
+ **/
guint*
g_signal_list_ids (GType itype,
guint *n_ids)
return (guint*) g_array_free (result, FALSE);
}
+/**
+ * g_signal_name:
+ * @signal_id: the signal's identifying number.
+ *
+ * Given the signal's identifier, finds its name.
+ *
+ * Two different signals may have the same name, if they have differing types.
+ *
+ * Return value: the signal name, or %NULL if the signal number was invalid.
+ **/
G_CONST_RETURN gchar*
g_signal_name (guint signal_id)
{
return name;
}
+/**
+ * g_signal_query:
+ * @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.
+ *
+ * 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.
+ **/
void
g_signal_query (guint signal_id,
GSignalQuery *query)
SIGNAL_UNLOCK ();
}
+/**
+ * g_signal_new:
+ * @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.
+ *
+ * Creates a new signal. (This is usually done in the class initializer.)
+ *
+ * Note that you can use '-' and '_' interchangeably in signal names.
+ *
+ * Return value: the signal id
+ **/
guint
g_signal_new (const gchar *signal_name,
GType itype,
g_closure_set_marshal (closure, node->c_marshaller);
}
+/**
+ * g_signal_newv:
+ * @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.
+ *
+ * Creates a new signal. (This is usually done in the class initializer.)
+ *
+ * Note that you can use '-' and '_' interchangeably in signal names.
+ *
+ * Return value: the signal id
+ **/
guint
g_signal_newv (const gchar *signal_name,
GType itype,
return signal_id;
}
+/**
+ * g_signal_new_valist:
+ * @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.
+ *
+ * Creates a new signal. (This is usually done in the class initializer.)
+ *
+ * Note that you can use '-' and '_' interchangeably in signal names.
+ *
+ * Return value: the signal id
+ **/
guint
g_signal_new_valist (const gchar *signal_name,
GType itype,
SIGNAL_LOCK ();
}
+/**
+ * g_signal_override_class_closure:
+ * @signal_id: the signal id
+ * @instance_type: the instance type on which to override the class closure
+ * for the signal.
+ * @class_closure: the closure.
+ *
+ * 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.
+ **/
void
g_signal_override_class_closure (guint signal_id,
GType instance_type,
SIGNAL_UNLOCK ();
}
+/**
+ * g_signal_chain_from_overridden:
+ * @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.
+ *
+ * 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().
+ **/
void
g_signal_chain_from_overridden (const GValue *instance_and_params,
GValue *return_value)
SIGNAL_UNLOCK ();
}
+/**
+ * g_signal_get_invocation_hint:
+ * @instance: the instance to query
+ *
+ * Returns the invocation hint of the innermost signal emission of instance.
+ *
+ * Return value: the invocation hint of the innermost signal emission.
+ **/
GSignalInvocationHint*
g_signal_get_invocation_hint (gpointer instance)
{
return emission ? &emission->ihint : NULL;
}
+/**
+ * g_signal_connect_closure_by_id:
+ * @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.
+ *
+ * Connects a closure to a signal for a particular object.
+ *
+ * Return value: the handler id
+ **/
gulong
g_signal_connect_closure_by_id (gpointer instance,
guint signal_id,
return handler_seq_no;
}
+/**
+ * g_signal_connect_closure:
+ * @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.
+ *
+ * Connects a closure to a signal for a particular object.
+ *
+ * Return value: the handler id
+ **/
gulong
g_signal_connect_closure (gpointer instance,
const gchar *detailed_signal,
return handler_seq_no;
}
+/**
+ * g_signal_connect_data:
+ * @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.
+ *
+ * Connects a #GCallback function to a signal for a particular object.
+ *
+ * Return value: the handler id
+ **/
gulong
g_signal_connect_data (gpointer instance,
const gchar *detailed_signal,
return handler_seq_no;
}
+/**
+ * g_signal_handler_block:
+ * @instance: The instance to block the signal handler of.
+ * @handler_id: Handler id of the handler to be blocked.
+ *
+ * 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.
+ *
+ * The @handler_id has to be a valid signal handler id, connected to a
+ * signal of @instance.
+ **/
void
g_signal_handler_block (gpointer instance,
gulong handler_id)
SIGNAL_UNLOCK ();
}
+/**
+ * g_signal_handler_unblock:
+ * @instance: The instance to unblock the signal handler of.
+ * @handler_id: Handler id of the handler to be unblocked.
+ *
+ * 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).
+ *
+ * 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.
+ **/
void
g_signal_handler_unblock (gpointer instance,
gulong handler_id)
SIGNAL_UNLOCK ();
}
+/**
+ * g_signal_handler_disconnect:
+ * @instance: The instance to remove the signal handler from.
+ * @handler_id: Handler id of the handler to be disconnected.
+ *
+ * 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.
+ *
+ * The @handler_id has to be a valid signal handler id, connected to a
+ * signal of @instance.
+ **/
void
g_signal_handler_disconnect (gpointer instance,
gulong handler_id)
SIGNAL_UNLOCK ();
}
+/**
+ * g_signal_handler_is_connected:
+ * @instance: The instance where a signal handler is sought.
+ * @handler_id: the handler id.
+ *
+ * Returns whether @handler_id is the id of a handler connected to @instance.
+ *
+ * Return value: whether @handler_id identifies a handler connected to
+ * @instance.
+ **/
gboolean
g_signal_handler_is_connected (gpointer instance,
gulong handler_id)
return connected;
}
+/**
+ * g_signal_handlers_destroy:
+ * @instance: The instance whose signal handlers are to be destroyed
+ *
+ * Destroys all the signal handlers connected to an object. This is done
+ * automatically when the object is destroyed.
+ *
+ * This function is labeled private.
+ **/
void
g_signal_handlers_destroy (gpointer instance)
{
SIGNAL_UNLOCK ();
}
+/**
+ * g_signal_handler_find:
+ * @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.
+ *
+ * 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.
+ *
+ * Return value: A valid non-0 signal handler id for a successful match.
+ **/
gulong
g_signal_handler_find (gpointer instance,
GSignalMatchType mask,
return n_handlers;
}
+/**
+ * g_signal_handlers_block_matched:
+ * @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.
+ *
+ * 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.
+ *
+ * Return value: The amount of handlers that got blocked.
+ **/
guint
g_signal_handlers_block_matched (gpointer instance,
GSignalMatchType mask,
return n_handlers;
}
+/**
+ * g_signal_handlers_unblock_matched:
+ * @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.
+ *
+ * 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.
+ *
+ * Return value: The amount of handlers that got unblocked.
+ **/
guint
g_signal_handlers_unblock_matched (gpointer instance,
GSignalMatchType mask,
return n_handlers;
}
+/**
+ * g_signal_handlers_disconnect_matched:
+ * @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.
+ *
+ * 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.
+ *
+ * Return value: The amount of handlers that got disconnected.
+ **/
guint
g_signal_handlers_disconnect_matched (gpointer instance,
GSignalMatchType mask,
return n_handlers;
}
+/**
+ * g_signal_has_handler_pending:
+ * @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 whether there are any handlers connected to @instance for the
+ * given signal id and detail.
+ *
+ * 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.
+ *
+ * Return value: %TRUE if a handler is connected to the signal,
+ * %FALSE otherwise.
+ **/
gboolean
g_signal_has_handler_pending (gpointer instance,
guint signal_id,
return has_pending;
}
+/**
+ * g_signal_emitv:
+ * @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.
+ *
+ * Emits a signal.
+ *
+ * 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().
+ **/
void
g_signal_emitv (const GValue *instance_and_params,
guint signal_id,
signal_emit_unlocked_R (node, detail, instance, return_value, instance_and_params);
}
+/**
+ * g_signal_emit_valist:
+ * @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.
+ *
+ * Emits a signal.
+ *
+ * Note that g_signal_emit_valist() resets the return value to the default
+ * if no handlers are connected, in contrast to g_signal_emitv().
+ **/
void
g_signal_emit_valist (gpointer instance,
guint signal_id,
g_free (free_me);
}
+/**
+ * g_signal_emit:
+ * @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.
+ *
+ * Emits a signal.
+ *
+ * Note that g_signal_emit() resets the return value to the default
+ * if no handlers are connected, in contrast to g_signal_emitv().
+ **/
void
g_signal_emit (gpointer instance,
guint signal_id,
va_end (var_args);
}
+/**
+ * g_signal_emit_by_name:
+ * @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.
+ *
+ * Emits a signal.
+ *
+ * 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().
+ **/
void
g_signal_emit_by_name (gpointer instance,
const gchar *detailed_signal,
projects / dana / cg-glib.git / commitdiff