|
Server : Apache/2.2.17 (Unix) mod_ssl/2.2.17 OpenSSL/0.9.8e-fips-rhel5 DAV/2 PHP/5.2.17 System : Linux localhost 2.6.18-419.el5 #1 SMP Fri Feb 24 22:47:42 UTC 2017 x86_64 User : nobody ( 99) PHP Version : 5.2.17 Disable Function : NONE Directory : /usr/share/gtk-doc/html/gobject/ |
Upload File : |
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Howto create and use signals</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
<link rel="start" href="index.html" title="GObject Reference Manual">
<link rel="up" href="pt02.html" title="Part IV. Tutorial">
<link rel="prev" href="howto-interface-properties.html" title="Interface Properties">
<link rel="next" href="ch07s02.html" title="How to provide more flexibility to users?">
<meta name="generator" content="GTK-Doc V1.6 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="preface" href="pr01.html" title="Introduction">
<link rel="part" href="pt01.html" title="Part I. Concepts">
<link rel="chapter" href="ch01.html" title="Background">
<link rel="chapter" href="ch02.html" title="The Glib Dynamic Type System">
<link rel="chapter" href="chapter-gobject.html" title="The GObject base class">
<link rel="chapter" href="chapter-signal.html" title="The GObject messaging system">
<link rel="reference" href="rn01.html" title="API Reference">
<link rel="reference" href="rn02.html" title="Tools Reference">
<link rel="part" href="pt02.html" title="Part IV. Tutorial">
<link rel="chapter" href="howto-gobject.html" title="How To define and implement a new GObject?">
<link rel="chapter" href="howto-interface.html" title="How To define and implement Interfaces?">
<link rel="chapter" href="howto-signals.html" title="Howto create and use signals">
<link rel="part" href="pt03.html" title="Part V. Related Tools">
<link rel="chapter" href="tools-gob.html" title="GObject builder">
<link rel="chapter" href="tools-ginspector.html" title="Graphical inspection of Gobjects">
<link rel="chapter" href="tools-refdb.html" title="Debugging reference count problems">
<link rel="chapter" href="tools-gtkdoc.html" title="Writing API docs">
<link rel="index" href="ix01.html" title="Index">
<link rel="index" href="ix02.html" title="Index of deprecated symbols">
<link rel="index" href="ix03.html" title="Index of new symbols in 2.2">
<link rel="index" href="ix04.html" title="Index of new symbols in 2.4">
<link rel="index" href="ix05.html" title="Index of new symbols in 2.6">
<link rel="index" href="ix06.html" title="Index of new symbols in 2.8">
<link rel="index" href="ix07.html" title="Index of new symbols in 2.10">
<link rel="index" href="ix08.html" title="Index of new symbols in 2.12">
</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="2"><tr valign="middle">
<td><a accesskey="p" href="howto-interface-properties.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="pt02.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">GObject Reference Manual</th>
<td><a accesskey="n" href="ch07s02.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter" lang="en">
<div class="titlepage"><div><div><h2 class="title">
<a name="howto-signals"></a>Howto create and use signals</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="sect1"><a href="howto-signals.html#howto-simple-signals">Simple use of signals</a></span></dt>
<dt><span class="sect1"><a href="ch07s02.html">How to provide more flexibility to users?</a></span></dt>
<dd><dl><dt><span class="sect2"><a href="ch07s02.html#id2807076">How most people do the same thing with less code</a></span></dt></dl></dd>
<dt><span class="sect1"><a href="ch07s03.html">How users can abuse signals (and why some think it is good)</a></span></dt>
</dl></div>
<p>
The signal system which was built 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)
<sup>[<a name="id2806725" href="#ftn.id2806725">15</a>]</sup>
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 emit events which can be received by numerous clients.
</p>
<div class="sect1" lang="en">
<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>
<p>The most basic use of signals is to implement simple event notification: for example, if we have a
MamanFile object, and if this object has a write method, we might wish to be notified whenever someone
uses this method. The code below shows how the user can connect a callback to the write signal. Full code
for this simple example is located in <code class="filename">sample/signal/maman-file.{h|c}</code> and
in <code class="filename">sample/signal/test.c</code>
</p>
<pre class="programlisting">
file = g_object_new (MAMAN_FILE_TYPE, NULL);
g_signal_connect (G_OBJECT (file), "write",
(GCallback)write_event,
NULL);
maman_file_write (file, buffer, 50);
</pre>
<p>
</p>
<p>
The <span class="type">MamanFile</span> signal is registered in the class_init function:
</p>
<pre class="programlisting">
klass->write_signal_id =
g_signal_newv ("write",
G_TYPE_FROM_CLASS (g_class),
G_SIGNAL_RUN_LAST | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
NULL /* class closure */,
NULL /* accumulator */,
NULL /* accu_data */,
g_cclosure_marshal_VOID__VOID,
G_TYPE_NONE /* return_type */,
0 /* n_params */,
NULL /* param_types */);
</pre>
<p>
and the signal is emited in <code class="function">maman_file_write</code>:
</p>
<pre class="programlisting">
void maman_file_write (MamanFile *self, guint8 *buffer, guint32 size)
{
/* First write data. */
/* Then, notify user of data written. */
g_signal_emit (self, MAMAN_FILE_GET_CLASS (self)->write_signal_id,
0 /* details */,
NULL);
}
</pre>
<p>
As shown above, you can safely set the details parameter to zero if you do not know what it can be used for.
For a discussion of what you could used it for, see <a href="signal.html#signal-detail" title="The detail argument">the section called “The <span class="emphasis"><em>detail</em></span> argument”</a>
</p>
<p>
The signature of the signal handler in the above example is defined as
<code class="function">g_cclosure_marshal_VOID__VOID</code>. Its name follows
a simple convention which encodes the function parameter and return value
types in the function name. Specifically, the value infront of the double
underscore is the type of the return value, while the value(s) after the
double underscore denote the parameter types.
The header <code class="filename">gobject/gmarshal.h</code> defines a set of commonly
needed closures that one can use.
</p>
</div>
<div class="footnotes">
<br><hr width="100" align="left">
<div class="footnote"><p><sup>[<a name="ftn.id2806725" href="#id2806725">15</a>] </sup>A python callback can be connected to any signal on any C-based GObject.
</p></div>
</div>
</div>
</body>
</html>