diff options
| -rw-r--r-- | ChangeLog | 9 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/signals.sgml | 926 | ||||
| -rw-r--r-- | gobject/gclosure.c | 12 | ||||
| -rw-r--r-- | gobject/gobject.c | 33 | ||||
| -rw-r--r-- | gobject/gsignal.c | 551 | ||||
| -rw-r--r-- | gobject/gsignal.h | 223 |
6 files changed, 827 insertions, 927 deletions
@@ -1,5 +1,14 @@ 2008-06-22 Stefan Kost <ensonic@users.sf.net> + * docs/reference/gobject/tmpl/signals.sgml: + * gobject/gclosure.c: + * gobject/gobject.c: + * gobject/gsignal.c: + * gobject/gsignal.h: + Migrating docs. + +2008-06-22 Stefan Kost <ensonic@users.sf.net> + * docs/reference/gobject/Makefile.am: Help poor little gtkdoc a bit and tell that it can ignore G_GNUC_INTERNAL. Also disable including the unit-test header as this diff --git a/docs/reference/gobject/tmpl/signals.sgml b/docs/reference/gobject/tmpl/signals.sgml deleted file mode 100644 index bea34f42e..000000000 --- a/docs/reference/gobject/tmpl/signals.sgml +++ /dev/null @@ -1,926 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Signals - -<!-- ##### SECTION Short_Description ##### --> -A means for customization of object behaviour and a general purpose notification mechanism - -<!-- ##### SECTION Long_Description ##### --> -<para> -The basic concept of the signal system is that of the <emphasis>emission</emphasis> -of a signal. -Signals are introduced per-type and are identified through strings. -Signals introduced for a parent type are available in derived types as well, -so basically they are a per-type facility that is inherited. -A signal emission mainly involves invocation of a certain set of callbacks in -precisely defined manner. There are two main categories of such callbacks, -per-object - <footnote><para>Although signals can deal with any kind of instantiatable type, - i'm referring to those types as "object types" in the following, simply - because that is the context most users will encounter signals in. - </para></footnote> -ones and user provided ones. -The per-object callbacks are most often referred to as "object method -handler" or "default (signal) handler", while user provided callbacks are -usually just called "signal handler". -The object method handler is provided at signal creation time (this most -frequently happens at the end of an object class' creation), while user -provided handlers are frequently connected and disconnected to/from a certain -signal on certain object instances. -</para> -<para> -A signal emission consists of five stages, unless prematurely stopped: -<variablelist> - <varlistentry><term></term><listitem><para> - 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - </para></listitem></varlistentry> - <varlistentry><term></term><listitem><para> - 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE) - </para></listitem></varlistentry> - <varlistentry><term></term><listitem><para> - 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - </para></listitem></varlistentry> - <varlistentry><term></term><listitem><para> - 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE - </para></listitem></varlistentry> - <varlistentry><term></term><listitem><para> - 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - </para></listitem></varlistentry> -</variablelist> -The user-provided signal handlers are called in the order they were -connected in. -All handlers may prematurely stop a signal emission, and any number of -handlers may be connected, disconnected, blocked or unblocked during -a signal emission. -There are certain criteria for skipping user handlers in stages 2 and 4 -of a signal emission. -First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted -during callback invocation, to return from the "blocked" state, a -handler has to get unblocked exactly the same amount of times -it has been blocked before. -Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional -"detail" argument passed in to g_signal_emit() has to match the detail -argument of the signal handler currently subject to invocation. -Specification of no detail argument for signal handlers (omission of the -detail part of the signal specification upon connection) serves as a -wildcard and matches any detail argument passed in to emission. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### STRUCT GSignalInvocationHint ##### --> -<para> -The #GSignalInvocationHint structure is used to pass on additional information -to callbacks during a signal emission. -</para> - -@signal_id: The signal id of the signal invoking the callback -@detail: The detail passed on for this emission -@run_type: The stage the signal emission is currently in, this - field will contain one of %G_SIGNAL_RUN_FIRST, - %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. - -<!-- ##### USER_FUNCTION GSignalAccumulator ##### --> -<para> -The signal accumulator is a special callback function that can be used -to collect return values of the various callbacks that are called -during a signal emission. The signal accumulator is specified at signal -creation time, if it is left %NULL, no accumulation of callback return -values is performed. The return value of signal emissions is then the -value returned by the last callback. -</para> - -@ihint: Signal invocation hint, see #GSignalInvocationHint. -@return_accu: Accumulator to collect callback return values in, this - is the return value of the current signal emission. -@handler_return: A #GValue holding the return value of the signal handler. -@data: Callback data that was specified when creating the signal. -@Returns: The accumulator function returns whether the signal emission - should be aborted. Returning %FALSE means to abort the - current emission and %TRUE is returned for continuation. - - -<!-- ##### TYPEDEF GSignalCMarshaller ##### --> -<para> -This is the signature of marshaller functions, required to marshall -arrays of parameter values to signal emissions into C language callback -invocations. It is merely an alias to #GClosureMarshal since the #GClosure -mechanism takes over responsibility of actual function invocation for the -signal system. -</para> - - -<!-- ##### USER_FUNCTION GSignalEmissionHook ##### --> -<para> -A simple function pointer to get invoked when the signal is emitted. This -allows you to tie a hook to the signal type, so that it will trap all -emissions of that signal, from any object. -</para> -<para> -You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. -</para> - -@ihint: Signal invocation hint, see #GSignalInvocationHint. -@n_param_values: the number of parameters to the function, including - the instance on which the signal was emitted. -@param_values: the instance on which the signal was emitted, followed by the - parameters of the emission. -@data: user data associated with the hook. -@Returns: whether it wants to stay connected. If it returns %FALSE, the signal - hook is disconnected (and destroyed). - - -<!-- ##### ENUM GSignalFlags ##### --> -<para> -The signal flags are used to specify a signal's behaviour, the overall -signal description outlines how especially the RUN flags control the -stages of a signal emission. -</para> - -@G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage. -@G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage. -@G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage. -@G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in - emission for this very object will not be emitted recursively, - but instead cause the first emission to be restarted. -@G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name - upon handler connections and emissions. -@G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive - objects from user code via g_signal_emit() and friends, without - the need of being embedded into extra code that performs pre or - post emission adjustments on the object. They can also be thought - of as object methods which can be called generically by - third-party code. -@G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal. - -<!-- ##### ENUM GSignalMatchType ##### --> -<para> -The match types specify what g_signal_handlers_block_matched(), -g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() -match signals by. -</para> - -@G_SIGNAL_MATCH_ID: The signal id must be equal. -@G_SIGNAL_MATCH_DETAIL: The signal detail be equal. -@G_SIGNAL_MATCH_CLOSURE: The closure must be the same. -@G_SIGNAL_MATCH_FUNC: The C closure callback must be the same. -@G_SIGNAL_MATCH_DATA: The closure data must be the same. -@G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched. - -<!-- ##### STRUCT GSignalQuery ##### --> -<para> -A structure holding in-depth information for a specific signal. It is -filled in by the g_signal_query() function. -</para> - -@signal_id: The signal id of the signal being queried, or 0 if the - signal to be queried was unknown. -@signal_name: The signal name. -@itype: The interface/instance type that this signal can be emitted for. -@signal_flags: The signal flags as passed in to g_signal_new(). -@return_type: The return type for user callbacks. -@n_params: The number of parameters that user callbacks take. -@param_types: The individual parameter types for user callbacks, note that the - effective callback signature is: -<programlisting> -@return_type callback (#gpointer data1, - [#param_types param_names,] - #gpointer data2); -</programlisting> - -<!-- ##### MACRO G_SIGNAL_TYPE_STATIC_SCOPE ##### --> -<para> -This macro flags signal argument types for which the signal system may -assume that instances thereof remain persistent across all signal emissions -they are used in. This is only useful for non ref-counted, value-copy types. -</para> -<para> -To flag a signal argument in this way, add -<literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument -of g_signal_new(). -</para> -<informalexample> -<programlisting> - g_signal_new ("size_request", - G_TYPE_FROM_CLASS (gobject_class), - G_SIGNAL_RUN_FIRST, - G_STRUCT_OFFSET (GtkWidgetClass, size_request), - NULL, NULL, - _gtk_marshal_VOID__BOXED, - G_TYPE_NONE, 1, - GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE); -</programlisting> -</informalexample> - - - -<!-- ##### MACRO G_SIGNAL_MATCH_MASK ##### --> -<para> -A mask for all #GSignalMatchType bits. -</para> - - - -<!-- ##### MACRO G_SIGNAL_FLAGS_MASK ##### --> -<para> -A mask for all #GSignalFlags bits. -</para> - - - -<!-- ##### FUNCTION g_signal_new ##### --> -<para> -Creates a new signal. (This is usually done in the class initializer.) -</para> -<para> -A signal name consists of segments consisting of ASCII letters and -digits, separated by either the '-' or '_' character. The first -character of a signal name must be a letter. Names which violate these -rules lead to undefined behaviour of the GSignal system. -</para> -<para> -When registering a signal and looking up a signal, either separator can -be used, but they cannot be mixed. -</para> - -@signal_name: the name for the signal -@itype: the type this signal pertains to. It will also pertain to - types which are derived from this type. -@signal_flags: a combination of #GSignalFlags specifying detail of when - the default handler is to be invoked. You should at least specify - %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. -@class_offset: The offset of the function pointer in the class structure - for this type. Used to invoke a class method generically. Pass 0 to - not associate a class method with this signal. -@accumulator: the accumulator for this signal; may be %NULL. -@accu_data: user data for the @accumulator. -@c_marshaller: the function to translate arrays of parameter values to - signal emissions into C language callback invocations. -@return_type: the type of return value, or #G_TYPE_NONE for a signal - without a return value. -@n_params: the number of parameter types to follow. -@Varargs: a list of types, one for each parameter. -@Returns: the signal id - - -<!-- ##### FUNCTION g_signal_newv ##### --> -<para> -Creates a new signal. (This is usually done in the class initializer.) -</para> -<para> -See g_signal_new() for details on allowed signal names. -</para> - -@signal_name: the name for the signal -@itype: the type this signal pertains to. It will also pertain to - types which are derived from this type. -@signal_flags: a combination of #GSignalFlags specifying detail of when - the default handler is to be invoked. You should at least specify - %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. -@class_closure: The closure to invoke on signal emission; may be %NULL. -@accumulator: the accumulator for this signal; may be %NULL. -@accu_data: user data for the @accumulator. -@c_marshaller: the function to translate arrays of parameter values to - signal emissions into C language callback invocations. -@return_type: the type of return value, or #G_TYPE_NONE for a signal - without a return value. -@n_params: the length of @param_types. -@param_types: an array types, one for each parameter. -@Returns: the signal id - - -<!-- ##### FUNCTION g_signal_new_valist ##### --> -<para> -Creates a new signal. (This is usually done in the class initializer.) -</para> -<para> -See g_signal_new() for details on allowed signal names. -</para> - -@signal_name: the name for the signal -@itype: the type this signal pertains to. It will also pertain to - types which are derived from this type. -@signal_flags: a combination of #GSignalFlags specifying detail of when - the default handler is to be invoked. You should at least specify - %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. -@class_closure: The closure to invoke on signal emission; may be %NULL. -@accumulator: the accumulator for this signal; may be %NULL. -@accu_data: user data for the @accumulator. -@c_marshaller: the function to translate arrays of parameter values to - signal emissions into C language callback invocations. -@return_type: the type of return value, or #G_TYPE_NONE for a signal - without a return value. -@n_params: the number of parameter types in @args. -@args: va_list of #GType, one for each parameter. -@Returns: the signal id - - -<!-- ##### FUNCTION g_signal_query ##### --> -<para> -Queries the signal system for in-depth information about a -specific signal. This function will fill in a user-provided -structure to hold signal-specific information. If an invalid -signal id is passed in, the @signal_id member of the #GSignalQuery -is 0. All members filled into the #GSignalQuery structure should -be considered constant and have to be left untouched. -</para> - -@signal_id: The signal id of the signal to query information for. -@query: A user provided structure that is filled in with constant - values upon success. - - -<!-- ##### FUNCTION g_signal_lookup ##### --> -<para> -Given the name of the signal and the type of object it connects to, gets -the signal's identifying integer. Emitting the signal by number is -somewhat faster than using the name each time. -</para> -<para> -Also tries the ancestors of the given type. -</para> -<para> -See g_signal_new() for details on allowed signal names. -</para> - -@name: the signal's name. -@itype: the type that the signal operates on. -@Returns: the signal's identifying number, or 0 if no signal was found. - - -<!-- ##### FUNCTION g_signal_name ##### --> -<para> -Given the signal's identifier, finds its name. -</para> -<para> -Two different signals may have the same name, if they have differing types. -</para> - -@signal_id: the signal's identifying number. -@Returns: the signal name, or %NULL if the signal number was invalid. - - -<!-- ##### FUNCTION g_signal_list_ids ##### --> -<para> -Lists the signals by id that a certain instance or interface type -created. Further information about the signals can be acquired through -g_signal_query(). -</para> - -@itype: Instance or interface type. -@n_ids: Location to store the number of signal ids for @itype. -@Returns: Newly allocated array of signal IDs. - - -<!-- ##### FUNCTION g_signal_emit ##### --> -<para> -Emits a signal. -</para> -<para> -Note that g_signal_emit() resets the return value to the default -if no handlers are connected, in contrast to g_signal_emitv(). -</para> - -@instance: the instance the signal is being emitted on. -@signal_id: the signal id -@detail: the detail -@Varargs: parameters to be passed to the signal, followed by a - location for the return value. If the return type of the signal - is #G_TYPE_NONE, the return value location can be omitted. - - -<!-- ##### FUNCTION g_signal_emit_by_name ##### --> -<para> -Emits a signal. -</para> -<para> -Note that g_signal_emit_by_name() resets the return value to the default -if no handlers are connected, in contrast to g_signal_emitv(). -</para> - -@instance: the instance the signal is being emitted on. -@detailed_signal: a string of the form "signal-name::detail". -@Varargs: parameters to be passed to the signal, followed by a - location for the return value. If the return type of the signal - is #G_TYPE_NONE, the return value location can be omitted. - - -<!-- ##### FUNCTION g_signal_emitv ##### --> -<para> -Emits a signal. -</para> -<para> -Note that g_signal_emitv() doesn't change @return_value if no handlers are -connected, in contrast to g_signal_emit() and g_signal_emit_valist(). -</para> - -@instance_and_params: argument list for the signal emission. The first - element in the array is a #GValue for the instance the signal is - being emitted on. The rest are any arguments to be passed to the - signal. -@signal_id: the signal id -@detail: the detail -@return_value: Location to store the return value of the signal emission. - - -<!-- ##### FUNCTION g_signal_emit_valist ##### --> -<para> -Emits a signal. -</para> -<para> -Note that g_signal_emit_valist() resets the return value to the default -if no handlers are connected, in contrast to g_signal_emitv(). -</para> - -@instance: the instance the signal is being emitted on. -@signal_id: the signal id -@detail: the detail -@var_args: a list of parameters to be passed to the signal, followed by a - location for the return value. If the return type of the signal - is #G_TYPE_NONE, the return value location can be omitted. - - -<!-- ##### MACRO g_signal_connect ##### --> -<para> -Connects a #GCallback function to a signal for a particular object. -</para> -<para> -The handler will be called before the default handler of the signal. -</para> - -@instance: the instance to connect to. -@detailed_signal: a string of the form "signal-name::detail". -@c_handler: the #GCallback to connect. -@data: data to pass to @c_handler calls. -@Returns: the handler id - - -<!-- ##### MACRO g_signal_connect_after ##### --> -<para> -Connects a #GCallback function to a signal for a particular object. -</para> -<para> -The handler will be called after the default handler of the signal. -</para> - -@instance: the instance to connect to. -@detailed_signal: a string of the form "signal-name::detail". -@c_handler: the #GCallback to connect. -@data: data to pass to @c_handler calls. -@Returns: the handler id - - -<!-- ##### MACRO g_signal_connect_swapped ##### --> -<para> -Connects a #GCallback function to a signal for a particular object. -</para> -<para> -The instance on which the signal is emitted and @data will be swapped when -calling the handler. -</para> - -@instance: the instance to connect to. -@detailed_signal: a string of the form "signal-name::detail". -@c_handler: the #GCallback to connect. -@data: data to pass to @c_handler calls. -@Returns: the handler id - - -<!-- ##### FUNCTION g_signal_connect_object ##### --> -<para> - This is similar to g_signal_connect_data(), but uses a closure which - ensures that the @gobject stays alive during the call to @c_handler - by temporarily adding a reference count to @gobject. -</para> -<para> - Note that there is a bug in GObject that makes this function - much less useful than it might seem otherwise. Once @gobject is - disposed, the callback will no longer be called, but, the signal - handler is <emphasis>not</emphasis> currently disconnected. If the - @instance is itself being freed at the same time than this doesn't - matter, since the signal will automatically be removed, but - if @instance persists, then the signal handler will leak. You - should not remove the signal yourself because in a future versions of - GObject, the handler <emphasis>will</emphasis> automatically - be disconnected. -</para> -<para> - It's possible to work around this problem in a way that will - continue to work with future versions of GObject by checking - that the signal handler is still connected before disconnected it: -<informalexample><programlisting> - if (g_signal_handler_is_connected (instance, id)) - g_signal_handler_disconnect (instance, id); -</programlisting></informalexample> -</para> - -@instance: the instance to connect to. -@detailed_signal: a string of the form "signal-name::detail". -@c_handler: the #GCallback to connect. -@gobject: the object to pass as data to @c_handler. -@connect_flags: a combination of #GConnnectFlags. -@Returns: the handler id. - - -<!-- ##### ENUM GConnectFlags ##### --> -<para> -The connection flags are used to specify the behaviour of a signal's -connection. -</para> - -@G_CONNECT_AFTER: whether the handler should be called before or after the - default handler of the signal. -@G_CONNECT_SWAPPED: whether the instance and data should be swapped when - calling the handler. - -<!-- ##### FUNCTION g_signal_connect_data ##### --> -<para> -Connects a #GCallback function to a signal for a particular object. Similar -to g_signal_connect(), but allows to provide a #GClosureNotify for the data -which will be called when the signal handler is disconnected and no longer -used. Specify @connect_flags if you need <literal>..._after()</literal> pr -<literal>..._swapped()</literal> variants of this function. -</para> - -@instance: the instance to connect to. -@detailed_signal: a string of the form "signal-name::detail". -@c_handler: the #GCallback to connect. -@data: data to pass to @c_handler calls. -@destroy_data: a #GClosureNotify for @data. -@connect_flags: a combination of #GConnectFlags. -@Returns: the handler id - - -<!-- ##### FUNCTION g_signal_connect_closure ##### --> -<para> -Connects a closure to a signal for a particular object. -</para> - -@instance: the instance to connect to. -@detailed_signal: a string of the form "signal-name::detail". -@closure: the closure to connect. -@after: whether the handler should be called before or after the - default handler of the signal. -@Returns: the handler id - - -<!-- ##### FUNCTION g_signal_connect_closure_by_id ##### --> -<para> -Connects a closure to a signal for a particular object. -</para> - -@instance: the instance to connect to. -@signal_id: the id of the signal. -@detail: the detail. -@closure: the closure to connect. -@after: whether the handler should be called before or after the - default handler of the signal. -@Returns: the handler id - - -<!-- ##### FUNCTION g_signal_handler_block ##### --> -<para> -Blocks a handler of an instance so it will not be called during -any signal emissions unless it is unblocked again. Thus "blocking" -a signal handler means to temporarily deactive it, a signal handler -has to be unblocked exactly the same amount of times it has been -blocked before to become active again. -</para> -<para> -The @handler_id has to be a valid signal handler id, connected to a -signal of @instance. -</para> - -@instance: The instance to block the signal handler of. -@handler_id: Handler id of the handler to be blocked. - - -<!-- ##### FUNCTION g_signal_handler_unblock ##### --> -<para> -Undoes the effect of a previous g_signal_handler_block() call. -A blocked handler is skipped during signal emissions and will not be -invoked, unblocking it (for exactly the amount of times it has been -blocked before) reverts its "blocked" state, so the handler will be -recognized by the signal system and is called upon future or currently -ongoing signal emissions (since the order in which handlers are -called during signal emissions is deterministic, whether the -unblocked handler in question is called as part of a currently -ongoing emission depends on how far that emission has proceeded -yet). -</para> -<para> -The @handler_id has to be a valid id of a signal handler that is -connected to a signal of @instance and is currently blocked. -</para> - -@instance: The instance to unblock the signal handler of. -@handler_id: Handler id of the handler to be unblocked. - - -<!-- ##### FUNCTION g_signal_handler_disconnect ##### --> -<para> -Disconnects a handler from an instance so it will not be called during -any future or currently ongoing emissions of the signal it has been -connected to. The @handler_id becomes invalid and may be reused. -</para> -<para> -The @handler_id has to be a valid signal handler id, connected to a -signal of @instance. -</para> - -@instance: The instance to remove the signal handler from. -@handler_id: Handler id of the handler to be disconnected. - - -<!-- ##### FUNCTION g_signal_handler_find ##### --> -<para> -Finds the first signal handler that matches certain selection criteria. -The criteria mask is passed as an OR-ed combination of #GSignalMatchType -flags, and the criteria values are passed as arguments. -The match @mask has to be non-0 for successful matches. -If no handler was found, 0 is returned. -</para> - -@instance: The instance owning the signal handler to be found. -@mask: Mask indicating which of @signal_id, @detail, @closure, @func - and/or @data the handler has to match. -@signal_id: Signal the handler has to be connected to. -@detail: Signal detail the handler has to be connected to. -@closure: The closure the handler will invoke. -@func: The C closure callback of the handler (useless for non-C closures). -@data: The closure data of the handler's closure. -@Returns: A valid non-0 signal handler id for a successful match. - - -<!-- ##### FUNCTION g_signal_handlers_block_matched ##### --> -<para> -Blocks all handlers on an instance that match a certain selection criteria. -The criteria mask is passed as an OR-ed combination of #GSignalMatchType -flags, and the criteria values are passed as arguments. -Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC -or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. -If no handlers were found, 0 is returned, the number of blocked handlers -otherwise. -</para> - -@instance: The instance to block handlers from. -@mask: Mask indicating which of @signal_id, @detail, @closure, @func - and/or @data the handlers have to match. -@signal_id: Signal the handlers have to be connected to. -@detail: Signal detail the handlers have to be connected to. -@closure: The closure the handlers will invoke. -@func: The C closure callback of the handlers (useless for non-C closures). -@data: The closure data of the handlers' closures. -@Returns: The number of handlers that matched. - - -<!-- ##### FUNCTION g_signal_handlers_unblock_matched ##### --> -<para> -Unblocks all handlers on an instance that match a certain selection -criteria. The criteria mask is passed as an OR-ed combination of -#GSignalMatchType flags, and the criteria values are passed as arguments. -Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC -or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. -If no handlers were found, 0 is returned, the number of unblocked handlers -otherwise. The match criteria should not apply to any handlers that are -not currently blocked. -</para> - -@instance: The instance to unblock handlers from. -@mask: Mask indicating which of @signal_id, @detail, @closure, @func - and/or @data the handlers have to match. -@signal_id: Signal the handlers have to be connected to. -@detail: Signal detail the handlers have to be connected to. -@closure: The closure the handlers will invoke. -@func: The C closure callback of the handlers (useless for non-C closures). -@data: The closure data of the handlers' closures. -@Returns: The number of handlers that matched. - - -<!-- ##### FUNCTION g_signal_handlers_disconnect_matched ##### --> -<para> -Disconnects all handlers on an instance that match a certain selection -criteria. The criteria mask is passed as an OR-ed combination of -#GSignalMatchType flags, and the criteria values are passed as arguments. -Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC -or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. -If no handlers were found, 0 is returned, the number of disconnected -handlers otherwise. -</para> - -@instance: The instance to remove handlers from. -@mask: Mask indicating which of @signal_id, @detail, @closure, @func - and/or @data the handlers have to match. -@signal_id: Signal the handlers have to be connected to. -@detail: Signal detail the handlers have to be connected to. -@closure: The closure the handlers will invoke. -@func: The C closure callback of the handlers (useless for non-C closures). -@data: The closure data of the handlers' closures. -@Returns: The number of handlers that matched. - - -<!-- ##### FUNCTION g_signal_handler_is_connected ##### --> -<para> -Returns whether @handler_id is the id of a handler connected to @instance. -</para> - -@instance: The instance where a signal handler is sought. -@handler_id: the handler id. -@Returns: whether @handler_id identifies a handler connected to @instance. - - -<!-- ##### MACRO g_signal_handlers_block_by_func ##### --> -<para> -Blocks all handlers on an instance that match @func and @data. -</para> - -@instance: The instance to block handlers from. -@func: The C closure callback of the handlers (useless for non-C closures). -@data: The closure data of the handlers' closures. -@Returns: The number of handlers that matched. - - -<!-- ##### MACRO g_signal_handlers_unblock_by_func ##### --> -<para> -Unblocks all handlers on an instance that match @func and @data. -</para> - -@instance: The instance to unblock handlers from. -@func: The C closure callback of the handlers (useless for non-C closures). -@data: The closure data of the handlers' closures. -@Returns: The number of handlers that matched. - - -<!-- ##### MACRO g_signal_handlers_disconnect_by_func ##### --> -<para> -Disconnects all handlers on an instance that match @func and @data. -</para> - -@instance: The instance to remove handlers from. -@func: The C closure callback of the handlers (useless for non-C closures). -@data: The closure data of the handlers' closures. -@Returns: The number of handlers that matched. - - -<!-- ##### FUNCTION g_signal_has_handler_pending ##### --> -<para> -Returns whether there are any handlers connected to @instance for the -given signal id and detail. -</para> -<para> -One example of when you might use this is when the arguments to the -signal are difficult to compute. A class implementor may opt to not emit -the signal if no one is attached anyway, thus saving the cost of building -the arguments. -</para> - -@instance: the object whose signal handlers are sought. -@signal_id: the signal id. -@detail: the detail. -@may_be_blocked: whether blocked handlers should count as match. -@Returns: %TRUE if a handler is connected to the signal, - %FALSE otherwise. - - -<!-- ##### FUNCTION g_signal_stop_emission ##### --> -<para> -Stops a signal's current emission. -</para> -<para> -This will prevent the default method from running, if the signal was -%G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" -flag). -</para> -<para> -Prints a warning if used on a signal which isn't being emitted. -</para> - -@instance: the object whose signal handlers you wish to stop. -@signal_id: the signal identifier, as returned by g_signal_lookup(). -@detail: the detail which the signal was emitted with. - - -<!-- ##### FUNCTION g_signal_stop_emission_by_name ##### --> -<para> -Stops a signal's current emission. -</para> -<para> -This is just like g_signal_stop_emission() except it will look up the -signal id for you. -</para> - -@instance: the object whose signal handlers you wish to stop. -@detailed_signal: a string of the form "signal-name::detail". - - -<!-- ##### FUNCTION g_signal_override_class_closure ##### --> -<para> -Overrides the class closure (i.e. the default handler) for the given signal -for emissions on instances of @instance_type. @instance_type must be derived -from the type to which the signal belongs. -</para> - -@signal_id: the signal id -@instance_type: the instance type on which to override the class closure - for the signal. -@class_closure: the closure. - - -<!-- ##### FUNCTION g_signal_chain_from_overridden ##### --> -<para> -Calls the original class closure of a signal. This function should only -be called from an overridden class closure; see -g_signal_override_class_closure(). -</para> - -@instance_and_params: the argument list of the signal emission. The first - element in the array is a #GValue for the instance the signal is being - emitted on. The rest are any arguments to be passed to the signal. -@return_value: Location for the return value. - - -<!-- ##### FUNCTION g_signal_add_emission_hook ##### --> -<para> -Adds an emission hook for a signal, which will get called for any emission -of that signal, independent of the instance. This is possible only -for signals which don't have #G_SIGNAL_NO_HOOKS flag set. -</para> - -@signal_id: the signal identifier, as returned by g_signal_lookup(). -@detail: the detail on which to call the hook. -@hook_func: a #GSignalEmissionHook function. -@hook_data: user data for @hook_func. -@data_destroy: a #GDestroyNotify for @hook_data. -@Returns: the hook id, for later use with g_signal_remove_emission_hook(). - - -<!-- ##### FUNCTION g_signal_remove_emission_hook ##### --> -<para> -Deletes an emission hook. -</para> - -@signal_id: the id of the signal -@hook_id: the id of the emission hook, as returned by -g_signal_add_emission_hook() - - -<!-- ##### FUNCTION g_signal_parse_name ##### --> -<para> -Internal function to parse a signal name into its @signal_id -and @detail quark. -</para> - -@detailed_signal: a string of the form "signal-name::detail". -@itype: The interface/instance type that introduced "signal-name". -@signal_id_p: Location to store the signal id. -@detail_p: Location to store the detail quark. -@force_detail_quark: %TRUE forces creation of a #GQuark for the detail. -@Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. - - -<!-- ##### FUNCTION g_signal_get_invocation_hint ##### --> -<para> -Returns the invocation hint of the innermost signal emission of instance. -</para> - -@instance: the instance to query -@Returns: the invocation hint of the innermost signal emission. - - -<!-- ##### FUNCTION g_signal_type_cclosure_new ##### --> -<para> -Creates a new closure which invokes the function found at the offset -@struct_offset in the class structure of the interface or classed type -identified by @itype. -</para> - -@itype: the #GType identifier of an interface or classed type -@struct_offset: the offset of the member function of @itype's class - structure which is to be invoked by the new closure -@Returns: a new #GCClosure - - -<!-- ##### FUNCTION g_signal_accumulator_true_handled ##### --> -<para> -A predefined #GSignalAccumulator for signals that return a -boolean values. The behavior that this accumulator gives is -that a return of %TRUE stops the signal emission: no further -callbacks will be invoked, while a return of %FALSE allows -the emission to coninue. The idea here is that a %TRUE return -indicates that the callback <emphasis>handled</emphasis> the signal, -and no further handling is needed. -</para> - -@ihint: standard #GSignalAccumulator parameter -@return_accu: standard #GSignalAccumulator parameter -@handler_return: standard #GSignalAccumulator parameter -@dummy: standard #GSignalAccumulator parameter -@Returns: standard #GSignalAccumulator result -@Since: 2.4 - - diff --git a/gobject/gclosure.c b/gobject/gclosure.c index b1ca90e83..b16a81145 100644 --- a/gobject/gclosure.c +++ b/gobject/gclosure.c @@ -893,6 +893,18 @@ g_type_iface_meta_marshal (GClosure *closure, callback); } +/** + * g_signal_type_cclosure_new: + * @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 + * + * 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. + * + * Returns: a new #GCClosure + */ GClosure* g_signal_type_cclosure_new (GType itype, guint struct_offset) diff --git a/gobject/gobject.c b/gobject/gobject.c index aba014161..2de811060 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -2845,6 +2845,39 @@ g_value_dup_object (const GValue *value) return value->data[0].v_pointer ? g_object_ref (value->data[0].v_pointer) : NULL; } +/** + * g_signal_connect_object: + * @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. + * + * 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. + * + * 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. + * + * 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> + * + * Returns: the handler id. + */ gulong g_signal_connect_object (gpointer instance, const gchar *detailed_signal, diff --git a/gobject/gsignal.c b/gobject/gsignal.c index 8ce1b6c6a..8a9a33c2f 100644 --- a/gobject/gsignal.c +++ b/gobject/gsignal.c @@ -19,7 +19,67 @@ * this code is based on the original GtkSignal implementation * for the Gtk+ library by Peter Mattis <petm@xcf.berkeley.edu> */ - +/** + * SECTION:signals + * @Short_description: A means for customization of object behaviour and a general purpose notification mechanism + * @Title: Signals + * + * 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 + * i'm referring to those types as "object types" in the following, simply + * because that is the context most users will encounter signals in. + * + * 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. + * + * 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. + */ /* * MT safe */ @@ -746,6 +806,20 @@ _g_signals_destroy (GType itype) 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, @@ -801,6 +875,20 @@ signal_finalize_hook (GHookList *hook_list, } } +/** + * 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. This is possible only + * for signals which don't have #G_SIGNAL_NO_HOOKS flag set. + * + * Returns: the hook id, for later use with g_signal_remove_emission_hook(). + */ gulong g_signal_add_emission_hook (guint signal_id, GQuark detail, @@ -856,6 +944,14 @@ g_signal_add_emission_hook (guint signal_id, 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) @@ -918,6 +1014,19 @@ signal_parse_name (const gchar *name, 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. + * + * Returns: 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, @@ -949,6 +1058,16 @@ g_signal_parse_name (const gchar *detailed_signal, 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) @@ -994,6 +1113,21 @@ g_signal_stop_emission_by_name (gpointer instance, 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. + * + * See g_signal_new() for details on allowed signal names. + * + * Returns: the signal's identifying number, or 0 if no signal was found. + */ guint g_signal_lookup (const gchar *name, GType itype) @@ -1022,6 +1156,17 @@ g_signal_lookup (const gchar *name, 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(). + * + * Returns: Newly allocated array of signal IDs. + */ guint* g_signal_list_ids (GType itype, guint *n_ids) @@ -1069,6 +1214,16 @@ g_signal_list_ids (GType itype, 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. + * + * Returns: the signal name, or %NULL if the signal number was invalid. + */ G_CONST_RETURN gchar* g_signal_name (guint signal_id) { @@ -1083,6 +1238,19 @@ g_signal_name (guint signal_id) return (char*) 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) @@ -1108,6 +1276,38 @@ g_signal_query (guint signal_id, 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. Pass 0 to + * not associate a class method with this signal. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to + * signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. + * @n_params: the number of parameter types to follow. + * @...: a list of types, one for each parameter. + * + * Creates a new signal. (This is usually done in the class initializer.) + * + * 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. + * + * When registering a signal and looking up a signal, either separator can + * be used, but they cannot be mixed. + * + * Returns: the signal id + */ guint g_signal_new (const gchar *signal_name, GType itype, @@ -1210,6 +1410,30 @@ signal_add_class_closure (SignalNode *node, 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; may be %NULL. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to + * signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. + * @n_params: the length of @param_types. + * @param_types: an array types, one for each parameter. + * + * Creates a new signal. (This is usually done in the class initializer.) + * + * See g_signal_new() for details on allowed signal names. + * + * Returns: the signal id + */ guint g_signal_newv (const gchar *signal_name, GType itype, @@ -1344,6 +1568,30 @@ g_signal_newv (const gchar *signal_name, 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; may be %NULL. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to + * signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. + * @n_params: the number of parameter types in @args. + * @args: va_list of #GType, one for each parameter. + * + * Creates a new signal. (This is usually done in the class initializer.) + * + * See g_signal_new() for details on allowed signal names. + * + * Returns: the signal id + */ guint g_signal_new_valist (const gchar *signal_name, GType itype, @@ -1433,6 +1681,17 @@ signal_destroy_R (SignalNode *signal_node) 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, @@ -1459,6 +1718,17 @@ g_signal_override_class_closure (guint signal_id, 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) @@ -1518,6 +1788,14 @@ g_signal_chain_from_overridden (const GValue *instance_and_params, SIGNAL_UNLOCK (); } +/** + * g_signal_get_invocation_hint: + * @instance: the instance to query + * + * Returns the invocation hint of the innermost signal emission of instance. + * + * Returns: the invocation hint of the innermost signal emission. + */ GSignalInvocationHint* g_signal_get_invocation_hint (gpointer instance) { @@ -1532,6 +1810,19 @@ 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. + * + * Returns: the handler id + */ gulong g_signal_connect_closure_by_id (gpointer instance, guint signal_id, @@ -1574,6 +1865,18 @@ g_signal_connect_closure_by_id (gpointer instance, 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. + * + * Returns: the handler id + */ gulong g_signal_connect_closure (gpointer instance, const gchar *detailed_signal, @@ -1620,6 +1923,23 @@ g_signal_connect_closure (gpointer instance, 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 #GClosureNotify for @data. + * @connect_flags: a combination of #GConnectFlags. + * + * Connects a #GCallback function to a signal for a particular object. Similar + * to g_signal_connect(), but allows to provide a #GClosureNotify for the data + * which will be called when the signal handler is disconnected and no longer + * used. Specify @connect_flags if you need <literal>..._after()</literal> or + * <literal>..._swapped()</literal> variants of this function. + * + * Returns: the handler id + */ gulong g_signal_connect_data (gpointer instance, const gchar *detailed_signal, @@ -1672,6 +1992,20 @@ g_signal_connect_data (gpointer instance, 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) @@ -1696,6 +2030,25 @@ g_signal_handler_block (gpointer instance, 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) @@ -1719,6 +2072,18 @@ g_signal_handler_unblock (gpointer instance, 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) @@ -1742,6 +2107,15 @@ g_signal_handler_disconnect (gpointer instance, 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. + * + * Returns: whether @handler_id identifies a handler connected to @instance. + */ gboolean g_signal_handler_is_connected (gpointer instance, gulong handler_id) @@ -1801,6 +2175,25 @@ 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. + * + * Returns: A valid non-0 signal handler id for a successful match. + */ gulong g_signal_handler_find (gpointer instance, GSignalMatchType mask, @@ -1862,6 +2255,27 @@ signal_handlers_foreach_matched_R (gpointer instance, 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. + * + * Returns: The number of handlers that matched. + */ guint g_signal_handlers_block_matched (gpointer instance, GSignalMatchType mask, @@ -1888,6 +2302,28 @@ g_signal_handlers_block_matched (gpointer instance, 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. + * + * Returns: The number of handlers that matched. + */ guint g_signal_handlers_unblock_matched (gpointer instance, GSignalMatchType mask, @@ -1914,6 +2350,27 @@ g_signal_handlers_unblock_matched (gpointer instance, 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. + * + * Returns: The number of handlers that matched. + */ guint g_signal_handlers_disconnect_matched (gpointer instance, GSignalMatchType mask, @@ -1940,6 +2397,24 @@ g_signal_handlers_disconnect_matched (gpointer instance, 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. + * + * Returns: %TRUE if a handler is connected to the signal, + * %FALSE otherwise. + */ gboolean g_signal_has_handler_pending (gpointer instance, guint signal_id, @@ -2023,6 +2498,21 @@ signal_check_skip_emission (SignalNode *node, return TRUE; } +/** + * 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, @@ -2111,6 +2601,20 @@ g_signal_emitv (const GValue *instance_and_params, 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, @@ -2231,6 +2735,20 @@ g_signal_emit_valist (gpointer instance, g_free (free_me); } +/** + * g_signal_emit: + * @instance: the instance the signal is being emitted on. + * @signal_id: the signal id + * @detail: the detail + * @...: 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, @@ -2244,6 +2762,19 @@ g_signal_emit (gpointer instance, 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". + * @...: 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, @@ -2590,6 +3121,24 @@ type_debug_name (GType type) return "<invalid>"; } +/** + * g_signal_accumulator_true_handled: + * @ihint: standard #GSignalAccumulator parameter + * @return_accu: standard #GSignalAccumulator parameter + * @handler_return: standard #GSignalAccumulator parameter + * @dummy: standard #GSignalAccumulator parameter + * + * 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. + * + * Since: 2.4 + * Returns: standard #GSignalAccumulator result + */ gboolean g_signal_accumulator_true_handled (GSignalInvocationHint *ihint, GValue *return_accu, diff --git a/gobject/gsignal.h b/gobject/gsignal.h index 61345dcba..1f703846f 100644 --- a/gobject/gsignal.h +++ b/gobject/gsignal.h @@ -33,11 +33,57 @@ G_BEGIN_DECLS /* --- typedefs --- */ typedef struct _GSignalQuery GSignalQuery; typedef struct _GSignalInvocationHint GSignalInvocationHint; +/** + * GSignalCMarshaller: + * + * 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. + */ typedef GClosureMarshal GSignalCMarshaller; +/** + * GSignalEmissionHook: + * @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. + * + * 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. + * + * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. + * + * Returns: whether it wants to stay connected. If it returns %FALSE, the signal + * hook is disconnected (and destroyed). + */ typedef gboolean (*GSignalEmissionHook) (GSignalInvocationHint *ihint, guint n_param_values, const GValue *param_values, gpointer data); +/** + * GSignalAccumulator: + * @ihint: Signal invocation hint, see #GSignalInvocationHint. + * @return_accu: Accumulator to collect callback return values in, this + * is the return value of the current signal emission. + * @handler_return: A #GValue holding the return value of the signal handler. + * @data: Callback data that was specified when creating the signal. + * + * 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. + * + * 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 gboolean (*GSignalAccumulator) (GSignalInvocationHint *ihint, GValue *return_accu, const GValue *handler_return, @@ -45,6 +91,28 @@ typedef gboolean (*GSignalAccumulator) (GSignalInvocationHint *ihint, /* --- run, match and connect types --- */ +/** + * GSignalFlags: + * @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. + * + * 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. + */ typedef enum { G_SIGNAL_RUN_FIRST = 1 << 0, @@ -55,12 +123,40 @@ typedef enum G_SIGNAL_ACTION = 1 << 5, G_SIGNAL_NO_HOOKS = 1 << 6 } GSignalFlags; +/** + * G_SIGNAL_FLAGS_MASK: + * + * A mask for all #GSignalFlags bits. + */ #define G_SIGNAL_FLAGS_MASK 0x7f +/** + * GConnectFlags: + * @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. + * + * The connection flags are used to specify the behaviour of a signal's + * connection. + */ typedef enum { G_CONNECT_AFTER = 1 << 0, G_CONNECT_SWAPPED = 1 << 1 } GConnectFlags; +/** + * GSignalMatchType: + * @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. + * + * The match types specify what g_signal_handlers_block_matched(), + * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() + * match signals by. + */ typedef enum { G_SIGNAL_MATCH_ID = 1 << 0, @@ -70,17 +166,74 @@ typedef enum G_SIGNAL_MATCH_DATA = 1 << 4, G_SIGNAL_MATCH_UNBLOCKED = 1 << 5 } GSignalMatchType; +/** + * G_SIGNAL_MATCH_MASK: + * + * A mask for all #GSignalMatchType bits. + */ #define G_SIGNAL_MATCH_MASK 0x3f +/** + * G_SIGNAL_TYPE_STATIC_SCOPE: + * + * 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. + * + * To flag a signal argument in this way, add + * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument + * of g_signal_new(). + * |[ + * 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); + * ]| + */ #define G_SIGNAL_TYPE_STATIC_SCOPE (G_TYPE_FLAG_RESERVED_ID_BIT) /* --- signal information --- */ +/** + * GSignalInvocationHint: + * @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. + * + * The #GSignalInvocationHint structure is used to pass on additional information + * to callbacks during a signal emission. + */ struct _GSignalInvocationHint { guint signal_id; GQuark detail; GSignalFlags run_type; }; +/** + * GSignalQuery: + * @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> + * + * A structure holding in-depth information for a specific signal. It is + * filled in by the g_signal_query() function. + */ struct _GSignalQuery { guint signal_id; @@ -236,20 +389,90 @@ void g_signal_chain_from_overridden (const GValue *instance_and_param /* --- convenience --- */ +/** + * g_signal_connect: + * @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. + * + * Connects a #GCallback function to a signal for a particular object. + * + * The handler will be called before the default handler of the signal. + * + * Returns: the handler id + */ #define g_signal_connect(instance, detailed_signal, c_handler, data) \ g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, (GConnectFlags) 0) +/** + * g_signal_connect_after: + * @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. + * + * Connects a #GCallback function to a signal for a particular object. + * + * The handler will be called after the default handler of the signal. + * + * Returns: the handler id + */ #define g_signal_connect_after(instance, detailed_signal, c_handler, data) \ g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_AFTER) +/** + * g_signal_connect_swapped: + * @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. + * + * Connects a #GCallback function to a signal for a particular object. + * + * The instance on which the signal is emitted and @data will be swapped when + * calling the handler. + * + * Returns: the handler id + */ #define g_signal_connect_swapped(instance, detailed_signal, c_handler, data) \ g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_SWAPPED) +/** + * g_signal_handlers_disconnect_by_func: + * @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. + * + * Disconnects all handlers on an instance that match @func and @data. + * + * Returns: The number of handlers that matched. + */ #define g_signal_handlers_disconnect_by_func(instance, func, data) \ g_signal_handlers_disconnect_matched ((instance), \ (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \ 0, 0, NULL, (func), (data)) +/** + * g_signal_handlers_block_by_func: + * @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. + * + * Blocks all handlers on an instance that match @func and @data. + * + * Returns: The number of handlers that matched. + */ #define g_signal_handlers_block_by_func(instance, func, data) \ g_signal_handlers_block_matched ((instance), \ (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \ 0, 0, NULL, (func), (data)) +/** + * g_signal_handlers_unblock_by_func: + * @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. + * + * Unblocks all handlers on an instance that match @func and @data. + * + * Returns: The number of handlers that matched. + */ #define g_signal_handlers_unblock_by_func(instance, func, data) \ g_signal_handlers_unblock_matched ((instance), \ (GSignalMatchType) (G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA), \ |