|
Packit |
ae235b |
|
|
Packit |
ae235b |
<html>
|
|
Packit |
ae235b |
<head>
|
|
Packit |
ae235b |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
Packit |
ae235b |
<title>Signals: GObject Reference Manual</title>
|
|
Packit |
ae235b |
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
|
Packit |
ae235b |
<link rel="home" href="index.html" title="GObject Reference Manual">
|
|
Packit |
ae235b |
<link rel="up" href="chapter-signal.html" title="The GObject messaging system">
|
|
Packit |
ae235b |
<link rel="prev" href="chapter-signal.html" title="The GObject messaging system">
|
|
Packit |
ae235b |
<link rel="next" href="rn01.html" title="API Reference">
|
|
Packit |
ae235b |
<meta name="generator" content="GTK-Doc V1.27 (XML mode)">
|
|
Packit |
ae235b |
<link rel="stylesheet" href="style.css" type="text/css">
|
|
Packit |
ae235b |
</head>
|
|
Packit |
ae235b |
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Signals
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GObject's signals have nothing to do with standard UNIX signals: they connect
|
|
Packit |
ae235b |
arbitrary application-specific events with any number of listeners.
|
|
Packit |
ae235b |
For example, in GTK+, every user event (keystroke or mouse move) is received
|
|
Packit |
ae235b |
from the windowing system and generates a GTK+ event in the form of a signal emission
|
|
Packit |
ae235b |
on the widget object instance.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Each signal is registered in the type system together with the type on which
|
|
Packit |
ae235b |
it can be emitted: users of the type are said to connect
|
|
Packit |
ae235b |
to the signal on a given type instance when they register a closure to be
|
|
Packit |
ae235b |
invoked upon the signal emission. Users can also emit the signal by themselves
|
|
Packit |
ae235b |
or stop the emission of the signal from within one of the closures connected
|
|
Packit |
ae235b |
to the signal.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
When a signal is emitted on a given type instance, all the closures
|
|
Packit |
ae235b |
connected to this signal on this type instance will be invoked. All the closures
|
|
Packit |
ae235b |
connected to such a signal represent callbacks whose signature looks like:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
1
|
|
Packit |
ae235b |
return_type function_callback (gpointer instance, …, gpointer user_data);
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Signal registration
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
To register a new signal on an existing type, we can use any of g_signal_newv,
|
|
Packit |
ae235b |
g_signal_new_valist or g_signal_new functions:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
1
|
|
Packit |
ae235b |
2
|
|
Packit |
ae235b |
3
|
|
Packit |
ae235b |
4
|
|
Packit |
ae235b |
5
|
|
Packit |
ae235b |
6
|
|
Packit |
ae235b |
7
|
|
Packit |
ae235b |
8
|
|
Packit |
ae235b |
9
|
|
Packit |
ae235b |
10
|
|
Packit |
ae235b |
guint g_signal_newv (const gchar *signal_name,
|
|
Packit |
ae235b |
GType itype,
|
|
Packit |
ae235b |
GSignalFlags signal_flags,
|
|
Packit |
ae235b |
GClosure *class_closure,
|
|
Packit |
ae235b |
GSignalAccumulator accumulator,
|
|
Packit |
ae235b |
gpointer accu_data,
|
|
Packit |
ae235b |
GSignalCMarshaller c_marshaller,
|
|
Packit |
ae235b |
GType return_type,
|
|
Packit |
ae235b |
guint n_params,
|
|
Packit |
ae235b |
GType *param_types);
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The number of parameters to these functions is a bit intimidating but they are relatively
|
|
Packit |
ae235b |
simple:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
signal_name: is a string which can be used to uniquely identify a given signal.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
itype: is the instance type on which this signal can be emitted.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
signal_flags: partly defines the order in which closures which were connected to the
|
|
Packit |
ae235b |
signal are invoked.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
class_closure: this is the default closure for the signal: if it is not NULL upon
|
|
Packit |
ae235b |
the signal emission, it will be invoked upon this emission of the signal. The
|
|
Packit |
ae235b |
moment where this closure is invoked compared to other closures connected to that
|
|
Packit |
ae235b |
signal depends partly on the signal_flags.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
accumulator: this is a function pointer which is invoked after each closure
|
|
Packit |
ae235b |
has been invoked. If it returns FALSE, signal emission is stopped. If it returns
|
|
Packit |
ae235b |
TRUE, signal emission proceeds normally. It is also used to compute the return
|
|
Packit |
ae235b |
value of the signal based on the return value of all the invoked closures.
|
|
Packit |
ae235b |
For example, an accumulator could ignore
|
|
Packit |
ae235b |
NULL returns from closures; or it
|
|
Packit |
ae235b |
could build a list of the values returned by the
|
|
Packit |
ae235b |
closures.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
accu_data: this pointer will be passed down to each invocation of the
|
|
Packit |
ae235b |
accumulator during emission.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
c_marshaller: this is the default C marshaller for any closure which is connected to
|
|
Packit |
ae235b |
this signal.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
return_type: this is the type of the return value of the signal.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
n_params: this is the number of parameters this signal takes.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
param_types: this is an array of GTypes which indicate the type of each parameter
|
|
Packit |
ae235b |
of the signal. The length of this array is indicated by n_params.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
As you can see from the above definition, a signal is basically a description
|
|
Packit |
ae235b |
of the closures which can be connected to this signal and a description of the
|
|
Packit |
ae235b |
order in which the closures connected to this signal will be invoked.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Signal connection
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
If you want to connect to a signal with a closure, you have three possibilities:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
You can register a class closure at signal registration: this is a
|
|
Packit |
ae235b |
system-wide operation. i.e.: the class closure will be invoked during each emission
|
|
Packit |
ae235b |
of a given signal on any of the instances of the type which supports that signal.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
You can use g_signal_override_class_closure which
|
|
Packit |
ae235b |
overrides the class closure of a given type. It is possible to call this function
|
|
Packit |
ae235b |
only on a derived type of the type on which the signal was registered.
|
|
Packit |
ae235b |
This function is of use only to language bindings.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
You can register a closure with the g_signal_connect
|
|
Packit |
ae235b |
family of functions. This is an instance-specific operation: the closure
|
|
Packit |
ae235b |
will be invoked only during emission of a given signal on a given instance.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
It is also possible to connect a different kind of callback on a given signal:
|
|
Packit |
ae235b |
emission hooks are invoked whenever a given signal is emitted whatever the instance on
|
|
Packit |
ae235b |
which it is emitted. Emission hooks are used for example to get all mouse_clicked
|
|
Packit |
ae235b |
emissions in an application to be able to emit the small mouse click sound.
|
|
Packit |
ae235b |
Emission hooks are connected with g_signal_add_emission_hook
|
|
Packit |
ae235b |
and removed with g_signal_remove_emission_hook.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Signal emission
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Signal emission is done through the use of the g_signal_emit family
|
|
Packit |
ae235b |
of functions.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
1
|
|
Packit |
ae235b |
2
|
|
Packit |
ae235b |
3
|
|
Packit |
ae235b |
4
|
|
Packit |
ae235b |
void g_signal_emitv (const GValue *instance_and_params,
|
|
Packit |
ae235b |
guint signal_id,
|
|
Packit |
ae235b |
GQuark detail,
|
|
Packit |
ae235b |
GValue *return_value);
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The instance_and_params array of GValues contains the list of input
|
|
Packit |
ae235b |
parameters to the signal. The first element of the array is the
|
|
Packit |
ae235b |
instance pointer on which to invoke the signal. The following elements of
|
|
Packit |
ae235b |
the array contain the list of parameters to the signal.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
signal_id identifies the signal to invoke.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
detail identifies the specific detail of the signal to invoke. A detail is a kind of
|
|
Packit |
ae235b |
magic token/argument which is passed around during signal emission and which is used
|
|
Packit |
ae235b |
by closures connected to the signal to filter out unwanted signal emissions. In most
|
|
Packit |
ae235b |
cases, you can safely set this value to zero. See the section called “The detail argument” for
|
|
Packit |
ae235b |
more details about this parameter.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
return_value holds the return value of the last closure invoked during emission if
|
|
Packit |
ae235b |
no accumulator was specified. If an accumulator was specified during signal creation,
|
|
Packit |
ae235b |
this accumulator is used to calculate the return value as a function of the return
|
|
Packit |
ae235b |
values of all the closures invoked during emission.
|
|
Packit |
ae235b |
If no closure is invoked during
|
|
Packit |
ae235b |
emission, the return_value is nonetheless initialized to zero/null.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Signal emission can be decomposed in 5 steps:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
RUN_FIRST: if the
|
|
Packit |
ae235b |
G_SIGNAL_RUN_FIRST flag was used
|
|
Packit |
ae235b |
during signal registration and if there exists a class closure for this signal,
|
|
Packit |
ae235b |
the class closure is invoked.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
EMISSION_HOOK: if any emission hook was added to
|
|
Packit |
ae235b |
the signal, they are invoked from first to last added. Accumulate return values.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
HANDLER_RUN_FIRST: if any closure were connected
|
|
Packit |
ae235b |
with the g_signal_connect family of
|
|
Packit |
ae235b |
functions, and if they are not blocked (with the g_signal_handler_block
|
|
Packit |
ae235b |
family of functions) they are run here, from first to last connected.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
RUN_LAST: if the G_SIGNAL_RUN_LAST
|
|
Packit |
ae235b |
flag was set during registration and if a class closure
|
|
Packit |
ae235b |
was set, it is invoked here.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
HANDLER_RUN_LAST: if any closure were connected
|
|
Packit |
ae235b |
with the g_signal_connect_after family of
|
|
Packit |
ae235b |
functions, if they were not invoked during HANDLER_RUN_FIRST and if they
|
|
Packit |
ae235b |
are not blocked, they are run here, from first to last connected.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
RUN_CLEANUP: if the G_SIGNAL_RUN_CLEANUP flag
|
|
Packit |
ae235b |
was set during registration and if a class closure was set,
|
|
Packit |
ae235b |
it is invoked here. Signal emission is completed here.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
If, at any point during emission (except in RUN_CLEANUP or
|
|
Packit |
ae235b |
EMISSION_HOOK state), one of the closures stops the signal emission with
|
|
Packit |
ae235b |
g_signal_stop_emission,
|
|
Packit |
ae235b |
emission jumps to RUN_CLEANUP state.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
If, at any point during emission, one of the closures or emission hook
|
|
Packit |
ae235b |
emits the same signal on the same instance, emission is restarted from
|
|
Packit |
ae235b |
the RUN_FIRST state.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The accumulator function is invoked in all states, after invocation
|
|
Packit |
ae235b |
of each closure (except in RUN_EMISSION_HOOK and
|
|
Packit |
ae235b |
RUN_CLEANUP). It accumulates
|
|
Packit |
ae235b |
the closure return value into the signal return value and returns TRUE or
|
|
Packit |
ae235b |
FALSE. If, at any point, it does not return TRUE, emission jumps
|
|
Packit |
ae235b |
to RUN_CLEANUP state.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
If no accumulator function was provided, the value returned by the last handler
|
|
Packit |
ae235b |
run will be returned by g_signal_emit.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The detail argument
|
|
Packit |
ae235b |
All the functions related to signal emission or signal connection have a parameter
|
|
Packit |
ae235b |
named the detail. Sometimes, this parameter is hidden by the API
|
|
Packit |
ae235b |
but it is always there, in one form or another.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Of the three main connection functions,
|
|
Packit |
ae235b |
only one has an explicit detail parameter as a GQuark:
|
|
Packit |
ae235b |
g_signal_connect_closure_by_id.
|
|
Packit |
ae235b |
<sup class="footnote">[6]</sup>
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The two other functions,
|
|
Packit |
ae235b |
g_signal_connect_closure and
|
|
Packit |
ae235b |
g_signal_connect_data
|
|
Packit |
ae235b |
hide the detail parameter in the signal name identification.
|
|
Packit |
ae235b |
Their detailed_signal parameter is a
|
|
Packit |
ae235b |
string which identifies the name of the signal to connect to.
|
|
Packit |
ae235b |
The format of this string should match
|
|
Packit |
ae235b |
signal_name::detail_name. For example,
|
|
Packit |
ae235b |
connecting to the signal named
|
|
Packit |
ae235b |
notify::cursor_position will actually
|
|
Packit |
ae235b |
connect to the signal named notify with the
|
|
Packit |
ae235b |
cursor_position detail.
|
|
Packit |
ae235b |
Internally, the detail string is transformed to a GQuark if it is present.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Of the four main signal emission functions, one hides it in its
|
|
Packit |
ae235b |
signal name parameter:
|
|
Packit |
ae235b |
g_signal_connect.
|
|
Packit |
ae235b |
The other three have an explicit detail parameter as a
|
|
Packit |
ae235b |
GQuark again:
|
|
Packit |
ae235b |
g_signal_emit,
|
|
Packit |
ae235b |
g_signal_emitv and
|
|
Packit |
ae235b |
g_signal_emit_valist.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
If a detail is provided by the user to the emission function, it is used during emission to match
|
|
Packit |
ae235b |
against the closures which also provide a detail.
|
|
Packit |
ae235b |
If a closure's detail does not match the detail provided by the user, it
|
|
Packit |
ae235b |
will not be invoked (even though it is connected to a signal which is
|
|
Packit |
ae235b |
being emitted).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
This completely optional filtering mechanism is mainly used as an optimization for signals
|
|
Packit |
ae235b |
which are often emitted for many different reasons: the clients can filter out which events they are
|
|
Packit |
ae235b |
interested in before the closure's marshalling code runs. For example, this is used extensively
|
|
Packit |
ae235b |
by the notify signal of GObject: whenever a property is modified on a GObject,
|
|
Packit |
ae235b |
instead of just emitting the notify signal, GObject associates as a detail to this
|
|
Packit |
ae235b |
signal emission the name of the property modified. This allows clients who wish to be notified of changes
|
|
Packit |
ae235b |
to only one property to filter most events before receiving them.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
As a simple rule, users can and should set the detail parameter to zero: this will disable completely
|
|
Packit |
ae235b |
this optional filtering for that signal.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
back and forth between the integer and string representations with the functions
|
|
Packit |
ae235b |
g_quark_from_string and g_quark_to_string.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Generated by GTK-Doc V1.27
|
|
Packit |
ae235b |
</body>
|
|
Packit |
ae235b |
</html>
|