Default page

Edit File: howto-signals.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>How to create and use signals: GObject Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GObject Reference Manual">
<link rel="up" href="pt02.html" title="Part IV. Tutorial">
<link rel="prev" href="howto-interface-override.html" title="Overriding interface methods">
<link rel="next" href="pt03.html" title="Part V. Related Tools">
<meta name="generator" content="GTK-Doc V1.32 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="pt02.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="howto-interface-override.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="pt03.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="howto-signals"></a>How to create and use signals</h2></div></div></div>
<div class="toc"><dl class="toc"><dt><a href="howto-signals.html#howto-simple-signals">Simple use of signals</a></dt></dl></div>

 The signal system in GType is pretty complex and
 flexible: it is possible for its users to connect at runtime any
 number of callbacks (implemented in any language for which a binding
 exists)
 <a href="#ftn.id-1.6.5.2.1" class="footnote" name="id-1.6.5.2.1">[8]</a>
 to any signal and to stop the emission of any signal at any 
 state of the signal emission process. This flexibility makes it
 possible to use GSignal for much more than just emitting signals to
 multiple clients.
 
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="howto-simple-signals"></a>Simple use of signals</h2></div></div></div>

 The most basic use of signals is to implement event
 notification. For example, given a ViewerFile object with
 a <code class="function">write</code> method, a signal could be emitted whenever
 the file is changed using that method.
 The code below shows how the user can connect a callback to the
 "changed" signal.

<div class="informalexample">
 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 <tbody>
 <tr>
 <td class="listing_lines" align="right"><pre>1
2
3
4
5</pre></td>
 <td class="listing_code"><pre class="programlisting">file = g_object_new (VIEWER_FILE_TYPE, NULL);

g_signal_connect (file, "changed", (GCallback) changed_event, NULL);

viewer_file_write (file, buffer, strlen (buffer));</pre></td>
 </tr>
 </tbody>
 </table>
</div>

The ViewerFile signal is registered in the
 <code class="function">class_init</code> function:

<div class="informalexample">
 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 <tbody>
 <tr>
 <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11</pre></td>
 <td class="listing_code"><pre class="programlisting">file_signals[CHANGED] = 
 g_signal_newv ("changed",
 G_TYPE_FROM_CLASS (object_class),
 G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
 NULL /* closure */,
 NULL /* accumulator */,
 NULL /* accumulator data */,
 NULL /* C marshaller */,
 G_TYPE_NONE /* return_type */,
 0 /* n_params */,
 NULL /* param_types */);</pre></td>
 </tr>
 </tbody>
 </table>
</div>

and the signal is emitted in <code class="function">viewer_file_write</code>:

<div class="informalexample">
 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
 <tbody>
 <tr>
 <td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13</pre></td>
 <td class="listing_code"><pre class="programlisting">void
viewer_file_write (ViewerFile *self,
 const guint8 *buffer,
 gsize size)
{
 g_return_if_fail (VIEWER_IS_FILE (self));
 g_return_if_fail (buffer != NULL || size == 0);

/* First write data. */

/* Then, notify user of data written. */
 g_signal_emit (self, file_signals[CHANGED], 0 /* details */);
}</pre></td>
 </tr>
 </tbody>
 </table>
</div>

As shown above, the details parameter can safely be set to zero if no
 detail needs to be conveyed. For a discussion of what it can be used for,
 see <a class="xref" href="signal.html#signal-detail" title="The detail argument">the section called “The detail argument”</a>
 

 The C signal marshaller should always be <code class="literal">NULL</code>, in which
 case the best marshaller for the given closure type will be chosen by
 GLib. This may be an internal marshaller specific to the closure type, or
 <code class="function">g_cclosure_marshal_generic</code>, which implements generic
 conversion of arrays of parameters to C callback invocations. GLib used to
 require the user to write or generate a type-specific marshaller and pass
 that, but that has been deprecated in favour of automatic selection of
 marshallers.
 

 Note that <code class="function">g_cclosure_marshal_generic</code> is slower than
 non-generic marshallers, so should be avoided for performance critical
 code. However, performance critical code should rarely be using signals
 anyway, as emitting a signal blocks on emitting it to all listeners, which
 has potentially unbounded cost.
 
</div>
<div class="footnotes">
 <hr style="width:100; text-align:left;margin-left: 0">
<div id="ftn.id-1.6.5.2.1" class="footnote"><a href="#id-1.6.5.2.1" class="para">[8] </a>A Python callback can be connected to any signal on any
 C-based GObject, and vice versa, assuming that the Python object
 inherits from GObject.</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>