luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-25 15:06:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

minor markup cleanups

Browse Source
This commit is contained in:
Tim Janik 2001-01-09 15:29:15 +00:00
parent 9e46ef9465
commit 5f130a176c
1 changed files with 77 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
docs/reference/gobject/tmpl/signals.sgml
View File

@ -7,7 +7,8 @@ as general purpose notification mechanism.
<!-- ##### SECTION Long_Description ##### -->
<para>
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 <emphasis>emission</emphasis>
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
<footnote><para> 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.
</para></footnote>
ones and user provided ones.
@ -31,19 +32,19 @@ 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
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 (@after flag @FALSE)
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
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 @after flag of @TRUE
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
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
@ -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 <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
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.
<!-- ##### STRUCT GSignalInvocationHint ##### -->
<para>
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.
</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.
field will contain one of %G_SIGNAL_RUN_FIRST,
%G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP.
<!-- ##### USER_FUNCTION GSignalAccumulator ##### -->
<para>
@ -92,20 +93,20 @@ values is perfomed. The return value of signal emissions is then the
value returned by the last callback.
</para>
@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.
<!-- ##### 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
invocations. It is merely an alias to #GClosureMarshal since the #GClosure
mechanism takes over responsibility of actuall function invocation for the
signal system.
</para>
@ -167,18 +168,18 @@ filled in by the g_signal_query() function.
</para>
@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:
<msgtext><programlisting>
@return_type callback (@gpointer data1,
[@param_types param_names,]
@gpointer data2);
@return_type callback (#gpointer data1,
[#param_types param_names,]
#gpointer data2);
</programlisting></msgtext>
<!-- ##### FUNCTION g_signal_newc ##### -->
@ -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.
</para>
@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().
</para>
@itype: Instance or interface type
@n_ids: Location to store the number of signal ids for @itype
@Returns: Newly allocated array of signal ids
@itype: 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 ##### -->
@ -391,8 +392,8 @@ to be a valid signal handler id, connected to a signal of
@instance.
</para>
@instance: The instance to block the signal handler of
@handler_id: Handler id of the handler to be blocked
@instance: The instance to block the signal handler of.
@handler_id: Handler id of the handler to be blocked.
<!-- ##### FUNCTION g_signal_handler_unblock ##### -->
@ -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.
</para>
@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.
<!-- ##### FUNCTION g_signal_handler_disconnect ##### -->
@ -428,8 +429,8 @@ to be a valid signal handler id, connected to a signal of
@instance.
</para>
@instance: The instance to remove the signal handler from
@handler_id: Handler id of the handler to be disconnected
@instance: The instance to remove the signal handler from.
@handler_id: Handler id of the handler to be disconnected.
<!-- ##### FUNCTION g_signal_handler_find ##### -->
@ -441,15 +442,15 @@ The match @mask has to be non-0 for successfull matches.
If no handler was found, 0 is returned.
</para>
@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.
<!-- ##### FUNCTION g_signal_handlers_block_matched ##### -->
@ -463,15 +464,15 @@ If no handlers were found, 0 is returned, the number of blocked handlers
otherwise.
</para>
@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.
<!-- ##### FUNCTION g_signal_handlers_unblock_matched ##### -->
@ -486,15 +487,15 @@ otherwise. The match criteria should not apply to any handlers that are
not currently blocked.
</para>
@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.
<!-- ##### FUNCTION g_signal_handlers_disconnect_matched ##### -->
@ -508,15 +509,15 @@ If no handlers were found, 0 is returned, the number of disconnected handlers
otherwise.
</para>
@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.
<!-- ##### FUNCTION g_signal_has_handler_pending ##### -->
@ -566,11 +567,11 @@ Internal function to parse a signal names into its @signal_id
and @detail quark.
</para>
@detailed_signal: A string of the form "signal-name::detail"
@itype: The interface/instance type 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.