1
1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5
5
<title>Signals</title>
6
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
7
<link rel="start" href="index.html" title="GObject Reference Manual">
6
<meta name="generator" content="DocBook XSL Stylesheets V1.74.0">
7
<link rel="home" href="index.html" title="GObject Reference Manual">
8
8
<link rel="up" href="chapter-signal.html" title="The GObject messaging system">
9
9
<link rel="prev" href="chapter-signal.html" title="The GObject messaging system">
10
10
<link rel="next" href="rn01.html" title="API Reference">
11
<meta name="generator" content="GTK-Doc V1.9 (XML mode)">
11
<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
12
12
<link rel="stylesheet" href="style.css" type="text/css">
13
13
<link rel="preface" href="pr01.html" title="Introduction">
14
<link rel="part" href="pt01.html" title="Part I. Concepts">
14
<link rel="part" href="pt01.html" title="Part I. Concepts">
15
15
<link rel="chapter" href="chapter-intro.html" title="Background">
16
16
<link rel="chapter" href="chapter-gtype.html" title="The GLib Dynamic Type System">
17
17
<link rel="chapter" href="chapter-gobject.html" title="The GObject base class">
18
18
<link rel="chapter" href="chapter-signal.html" title="The GObject messaging system">
19
19
<link rel="reference" href="rn01.html" title="API Reference">
20
20
<link rel="reference" href="rn02.html" title="Tools Reference">
21
<link rel="part" href="pt02.html" title="Part IV. Tutorial">
21
<link rel="part" href="pt02.html" title="Part IV. Tutorial">
22
22
<link rel="chapter" href="howto-gobject.html" title="How to define and implement a new GObject">
23
23
<link rel="chapter" href="howto-interface.html" title="How to define and implement interfaces">
24
24
<link rel="chapter" href="howto-signals.html" title="How to create and use signals">
25
<link rel="part" href="pt03.html" title="Part V. Related Tools">
25
<link rel="part" href="pt03.html" title="Part V. Related Tools">
26
<link rel="chapter" href="tools-vala.html" title="Vala">
26
27
<link rel="chapter" href="tools-gob.html" title="GObject builder">
27
28
<link rel="chapter" href="tools-ginspector.html" title="Graphical inspection of GObjects">
28
29
<link rel="chapter" href="tools-refdb.html" title="Debugging reference count problems">
36
37
<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
37
38
<link rel="index" href="ix08.html" title="Index of new symbols in 2.12">
38
39
<link rel="index" href="ix09.html" title="Index of new symbols in 2.14">
40
<link rel="index" href="ix10.html" title="Index of new symbols in 2.14">
40
42
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
41
43
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
77
79
<div class="titlepage"><div><div><h3 class="title">
78
80
<a name="signal-registration"></a>Signal registration</h3></div></div></div>
80
To register a new signal on an existing type, we can use any of <code class="function"><a class="link" href="gobject-Signals.html#g-signal-newv">g_signal_newv</a></code>,
81
<code class="function"><a class="link" href="gobject-Signals.html#g-signal-new-valist">g_signal_new_valist</a></code> or <code class="function"><a class="link" href="gobject-Signals.html#g-signal-new">g_signal_new</a></code> functions:
82
To register a new signal on an existing type, we can use any of <code class="function"><a class="link" href="gobject-Signals.html#g-signal-newv" title="g_signal_newv ()">g_signal_newv</a></code>,
83
<code class="function"><a class="link" href="gobject-Signals.html#g-signal-new-valist" title="g_signal_new_valist ()">g_signal_new_valist</a></code> or <code class="function"><a class="link" href="gobject-Signals.html#g-signal-new" title="g_signal_new ()">g_signal_new</a></code> functions:
83
85
<pre class="programlisting">
84
guint g_signal_newv (const gchar *signal_name,
86
GSignalFlags signal_flags,
87
GClosure *class_closure,
88
GSignalAccumulator accumulator,
90
GSignalCMarshaller c_marshaller,
86
guint g_signal_newv (const gchar *signal_name,
88
GSignalFlags signal_flags,
89
GClosure *class_closure,
90
GSignalAccumulator accumulator,
92
GSignalCMarshaller c_marshaller,
96
98
The number of parameters to these functions is a bit intimidating but they are relatively
159
161
of a given signal on all the instances of the type which supports that signal.
162
You can use <code class="function"><a class="link" href="gobject-Signals.html#g-signal-override-class-closure">g_signal_override_class_closure</a></code> which
164
You can use <code class="function"><a class="link" href="gobject-Signals.html#g-signal-override-class-closure" title="g_signal_override_class_closure ()">g_signal_override_class_closure</a></code> which
163
165
overrides the class_closure of a given type. It is possible to call this function
164
166
only on a derived type of the type on which the signal was registered.
165
167
This function is of use only to language bindings.
168
You can register a closure with the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-connect">g_signal_connect</a></code>
170
You can register a closure with the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-connect" title="g_signal_connect()">g_signal_connect</a></code>
169
171
family of functions. This is an instance-specific operation: the closure
170
172
will be invoked only during emission of a given signal on a given instance.
175
177
emission hooks are invoked whenever a given signal is emitted whatever the instance on
176
178
which it is emitted. Emission hooks are used for example to get all mouse_clicked
177
179
emissions in an application to be able to emit the small mouse click sound.
178
Emission hooks are connected with <code class="function"><a class="link" href="gobject-Signals.html#g-signal-add-emission-hook">g_signal_add_emission_hook</a></code>
179
and removed with <code class="function"><a class="link" href="gobject-Signals.html#g-signal-remove-emission-hook">g_signal_remove_emission_hook</a></code>.
180
Emission hooks are connected with <code class="function"><a class="link" href="gobject-Signals.html#g-signal-add-emission-hook" title="g_signal_add_emission_hook ()">g_signal_add_emission_hook</a></code>
181
and removed with <code class="function"><a class="link" href="gobject-Signals.html#g-signal-remove-emission-hook" title="g_signal_remove_emission_hook ()">g_signal_remove_emission_hook</a></code>.
182
184
<div class="sect2" lang="en">
183
185
<div class="titlepage"><div><div><h3 class="title">
184
186
<a name="signal-emission"></a>Signal emission</h3></div></div></div>
186
Signal emission is done through the use of the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-emit">g_signal_emit</a></code> family
188
Signal emission is done through the use of the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-emit" title="g_signal_emit ()">g_signal_emit</a></code> family
189
191
<pre class="programlisting">
190
void g_signal_emitv (const GValue *instance_and_params,
193
GValue *return_value);
192
void g_signal_emitv (const GValue *instance_and_params,
195
GValue *return_value);
208
210
detail identifies the specific detail of the signal to invoke. A detail is a kind of
209
211
magic token/argument which is passed around during signal emission and which is used
210
212
by closures connected to the signal to filter out unwanted signal emissions. In most
211
cases, you can safely set this value to zero. See <a class="xref" href="signal.html#signal-detail" title="The detail argument">the section called “The <span class="emphasis"><em>detail</em></span> argument”</a> for
213
cases, you can safely set this value to zero. See <a class="xref" href="signal.html#signal-detail" title="The detail argument">the section called “The detail argument”</a> for
212
214
more details about this parameter.
216
218
no accumulator was specified. If an accumulator was specified during signal creation,
217
219
this accumulator is used to calculate the return_value as a function of the return
218
220
values of all the closures invoked during emission.
219
<sup>[<a name="id2817323" href="#ftn.id2817323" class="footnote">10</a>]</sup>
221
<sup>[<a name="id3016697" href="#ftn.id3016697" class="footnote">10</a>]</sup>
220
222
If no closure is invoked during
221
223
emission, the return_value is nonetheless initialized to zero/null.
243
245
<span class="emphasis"><em>HANDLER_RUN_FIRST</em></span>: if any closure were connected
244
with the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-connect">g_signal_connect</a></code> family of
245
functions, and if they are not blocked (with the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-handler-block">g_signal_handler_block</a></code>
246
with the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-connect" title="g_signal_connect()">g_signal_connect</a></code> family of
247
functions, and if they are not blocked (with the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-handler-block" title="g_signal_handler_block ()">g_signal_handler_block</a></code>
246
248
family of functions) they are run here, from first to last connected.
247
249
Jump to <span class="emphasis"><em>RUN_LAST</em></span> state.
287
289
If no accumulator function was provided, the value returned by the last handler
288
run will be returned by <code class="function"><a class="link" href="gobject-Signals.html#g-signal-emit">g_signal_emit</a></code>.
290
run will be returned by <code class="function"><a class="link" href="gobject-Signals.html#g-signal-emit" title="g_signal_emit ()">g_signal_emit</a></code>.
291
293
<div class="sect2" lang="en">
300
302
only one has an explicit detail parameter as a <span class="type"><a
301
303
href="./../glib/glib/glib-Quarks.html#GQuark"
302
304
>GQuark</a></span>
303
<sup>[<a name="id2817537" href="#ftn.id2817537" class="footnote">11</a>]</sup>:
305
<sup>[<a name="id3016912" href="#ftn.id3016912" class="footnote">11</a>]</sup>:
305
307
<pre class="programlisting">
306
308
gulong g_signal_connect_closure_by_id (gpointer instance,
364
366
The format of the detailed_signal parameter is exactly the same as the format used by
365
the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-connect">g_signal_connect</a></code> functions: <span class="emphasis"><em>signal_name::detail_name</em></span>.
367
the <code class="function"><a class="link" href="gobject-Signals.html#g-signal-connect" title="g_signal_connect()">g_signal_connect</a></code> functions: <span class="emphasis"><em>signal_name::detail_name</em></span>.
368
370
If a detail is provided by the user to the emission function, it is used during emission to match
387
389
<div class="footnotes">
388
390
<br><hr width="100" align="left">
389
<div class="footnote"><p><sup>[<a name="ftn.id2817323" href="#id2817323" class="para">10</a>] </sup>
391
<div class="footnote"><p><sup>[<a name="ftn.id3016697" href="#id3016697" class="para">10</a>] </sup>
390
392
James (again!!) gives a few non-trivial examples of accumulators:
391
“<span class="quote">
393
“<span class="quote">
392
394
For instance, you may have an accumulator that ignores NULL returns from
393
395
closures, and only accumulates the non-NULL ones. Another accumulator may try
394
396
to return the list of values returned by the closures.
397
<div class="footnote"><p><sup>[<a name="ftn.id2817537" href="#id2817537" class="para">11</a>] </sup>A GQuark is an integer which uniquely represents a string. It is possible to transform
399
<div class="footnote"><p><sup>[<a name="ftn.id3016912" href="#id3016912" class="para">11</a>] </sup>A GQuark is an integer which uniquely represents a string. It is possible to transform
398
400
back and forth between the integer and string representations with the functions
399
401
<code class="function"><a
400
402
href="./../glib/glib/glib-Quarks.html#g-quark-from-string"
added
removed
docs/reference/gobject/html/signal.html
