diff --git a/docs/reference/gobject/tmpl/signals.sgml b/docs/reference/gobject/tmpl/signals.sgml index 55123003a..558b97388 100644 --- a/docs/reference/gobject/tmpl/signals.sgml +++ b/docs/reference/gobject/tmpl/signals.sgml @@ -7,7 +7,8 @@ as general purpose notification mechanism. -The basic concept of the signal system is that of the @emission of a signal. +The basic concept of the signal system is that of the emission +of a signal. Signals are introduced per-type and are identified through strings. Signals introduced for a parent type are availale in derived types as well, so basically they are a per-type facility that is inherited. @@ -15,7 +16,7 @@ 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 Although signals can deal with any kind of type, i'm - referring to those types as "@object @types" in the following, simply + 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. @@ -31,19 +32,19 @@ signal on certain object instances. A signal emission consists of five stages, unless prematurely stopped: - 1 - Invocation of the object method handler for @G_SIGNAL_RUN_FIRST signals + 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - 2 - Invocation of normal user-provided signal handlers (@after flag @FALSE) + 2 - Invocation of normal user-provided signal handlers (after flag %FALSE) - 3 - Invocation of the object method handler for @G_SIGNAL_RUN_LAST signals + 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - 4 - Invocation of user provided signal handlers, connected with an @after flag of @TRUE + 4 - Invocation of user provided signal handlers, connected with an after flag of %TRUE - 5 - Invocation of the object method handler for @G_SIGNAL_RUN_CLEANUP signals + 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals The user provided signal handlers are called in the order they were @@ -53,11 +54,11 @@ 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 @blocked, blocked handlers are omitted +First, user handlers may be blocked, 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 +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 @@ -72,15 +73,15 @@ wildcard and matches any detail argument passed in to emission. -The @GSignalInvocationHint structure is used to pass on additional information +The #GSignalInvocationHint structure is used to pass on additional information to callbacks during a signal emission. @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. + field will contain one of %G_SIGNAL_RUN_FIRST, + %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. @@ -92,20 +93,20 @@ values is perfomed. The return value of signal emissions is then the value returned by the last callback. -@ihint: Signal invokation hint, see @GSignalInvocationHint +@ihint: Signal invokation hint, see #GSignalInvocationHint. @return_accu: Accumulator to collect callback return values in, this - is the return value of the current signal emission -@return_value: The return value of the most recent callback function + is the return value of the current signal emission. +@return_value: The return value of the most recent callback function. @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. + should be aborted. Returning %FALSE means to abort the + current emission and %TRUE is returned for continuation. 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 +invocations. It is merely an alias to #GClosureMarshal since the #GClosure mechanism takes over responsibility of actuall function invocation for the signal system. @@ -167,18 +168,18 @@ filled in by the g_signal_query() function. @signal_id: The signal id of the signal being querried, or 0 if the - signal to be querried 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 + signal to be querried 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: -@return_type callback (@gpointer data1, - [@param_types param_names,] - @gpointer data2); +@return_type callback (#gpointer data1, + [#param_types param_names,] + #gpointer data2); @@ -237,12 +238,12 @@ filled in by the g_signal_query() function. 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 -dignal id is passed in, the @signal_id member of the @GSignalQuery -is 0. All members filled into the @GSignalQuery structure should +dignal 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. -@signal_id: The signal id of the signal to query information for +@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. @@ -273,9 +274,9 @@ created. Further information about the signals can be aquired through g_signal_query(). -@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: Instance or interface type. +@n_ids: Location to store the number of signal ids for @itype. +@Returns: Newly allocated array of signal IDs. @@ -391,8 +392,8 @@ to be a valid signal handler id, connected to a signal of @instance. -@instance: The instance to block the signal handler of -@handler_id: Handler id of the handler to be blocked +@instance: The instance to block the signal handler of. +@handler_id: Handler id of the handler to be blocked. @@ -413,8 +414,8 @@ to be a valid id of a signal handler that is connected to a signal of @instance and is currently blocked. -@instance: The instance to unblock the signal handler of -@handler_id: Handler id of the handler to be unblocked +@instance: The instance to unblock the signal handler of. +@handler_id: Handler id of the handler to be unblocked. @@ -428,8 +429,8 @@ to be a valid signal handler id, connected to a signal of @instance. -@instance: The instance to remove the signal handler from -@handler_id: Handler id of the handler to be disconnected +@instance: The instance to remove the signal handler from. +@handler_id: Handler id of the handler to be disconnected. @@ -441,15 +442,15 @@ The match @mask has to be non-0 for successfull matches. If no handler was found, 0 is returned. -@instance: The instance owning the signal handler to be found +@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 successfull match + @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 successfull match. @@ -463,15 +464,15 @@ If no handlers were found, 0 is returned, the number of blocked handlers otherwise. -@instance: The instance to block handlers from +@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 + @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. @@ -486,15 +487,15 @@ otherwise. The match criteria should not apply to any handlers that are not currently blocked. -@instance: The instance to unblock handlers from +@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 + @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. @@ -508,15 +509,15 @@ If no handlers were found, 0 is returned, the number of disconnected handlers otherwise. -@instance: The instance to remove handlers from +@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 + @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. @@ -566,11 +567,11 @@ Internal function to parse a signal names into its @signal_id and @detail quark. -@detailed_signal: A string of the form "signal-name::detail" -@itype: The interface/instance type taht 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 +@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.