<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>GG: Signals and Slots</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">GG
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Signals and Slots </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="sigs_n_slots_definition"></a>
Sig-who? Slo-what?</h1>
<p>If you've never been exposed to the signals and slots pattern before, it can be a little confusing. Simply put, a slot is a function or function object that is "listening" for a signal. A slot "listening" to a certain signal is said to be connected to that signal. When a signal is emitted, all slots that are connected to that signal are called (since they are all functions/function objects). If a signal is emitted to which no slots are connected, nothing happens.</p>
<h1><a class="anchor" id="sigs_n_slots_motivation"></a>
Motivation for the Signals and Slots Pattern</h1>
<h2><a class="anchor" id="prob"></a>
The Problem</h2>
<p>Originally, <a class="el" href="namespaceGG.html" title="The namespace that encloses all GG classes, functions, typedefs, enums, etc.">GG</a> used a very simple strategy for passing messages between windows/controls. The method was to call a Command() function, which passed to the callee an integer representing the type of message (button click, scroll, or whatever), an ID number associated with the calling control, and a single integer parameter. It could have been made more general and even less typesafe by replacing the int parameter with a void pointer, but in either case it suffers from two huge limitations. First, the type of message and the parameter must be known to both caller and callee; this means that, for example, the user must keep track of the integer value representing a button click message, and make sure that separate sections of code are using the same value to represent it. Second, any code that doesn't contain a control, but that wants to know about button pushes, scrolling scrollbars, etc., must deal with that control's parent (or break encapsulation). This creates a lot of chains of passed messages, and a large number of kludges to get messages to the sections of code that need them.</p>
<h2><a class="anchor" id="sigs_n_slots_soln"></a>
The Solution</h2>
<p>Now, each control emits a signal every time a significant event occurs. If no processing needs to be associated with such an event, its signal need not be connected to anything. Futhermore, no matter how many modules need to react to a certain signal, they can all be connected.</p>
<h1><a class="anchor" id="sigs_n_slots_use"></a>
Using Signals and Slots</h1>
<h2><a class="anchor" id="sigs_n_slots_connecting"></a>
Connecting Signals To Slots</h2>
<p>There are two types of connections between signals and slots. The first type of connection is between a signal and a slot, which may be a functor (which in turn may be a boost::bind object), a free function or a static member function or function object. Just call Connect(sig, slot). The second type is between a signal and a non-static member function. In this case, the call to <a class="el" href="namespaceGG.html#a0ec79e1f371bfd7ed25b88e4a7f1d67c">Connect()</a> requires a third parameter: a pointer to the object whose member function is to be called. For instance, if I have a class Foo and an object foo1 of class Foo, I cannot call foo1.bar() by simply knowing the address of bar(). I need to call Connect(sig, &Foo::bar, &foo1) so that the signal knows which object's bar() to call. Both versions of <a class="el" href="namespaceGG.html#a0ec79e1f371bfd7ed25b88e4a7f1d67c">Connect()</a> return a connection object. By keeping this connection object, you can later disconnect() the connection you made. In addition, signal-signal connections are possible. Calling Connect(sig1, sig2) forwards all sig1's signal emissions to sig2. This is provided as a convenience to avoid having to write dummy forwarding functions that do this.</p>
<h2><a class="anchor" id="sigs_n_slots_emitting"></a>
Emitting Signals</h2>
<p>To emit a signal from a signal object "sig", just use its function call operator ("operator()"), like this: "sig();"</p>
<h2><a class="anchor" id="disconnecting"></a>
Disconnecting Signals and Slots</h2>
<p>If you kept the connection object returned by <a class="el" href="namespaceGG.html#a0ec79e1f371bfd7ed25b88e4a7f1d67c">Connect()</a>, a connection_obj.disconnect() call will disconnect the associated signal and slot. Also, consider this: what happens if a signal A is connected to a slot consisting of a member function of object B, B is deleted, and then A() is called? A segfault, unless the B's class inherits from boost::trackable, which auto-disconnects slots in its destructor. <a class="el" href="classGG_1_1Wnd.html" title="This is the basic GG window class.">GG::Wnd</a> is derived from boost::trackable, so all <a class="el" href="classGG_1_1Wnd.html" title="This is the basic GG window class.">GG::Wnd</a>-derived classes should handle such situations gracefully. See the Boost tutorial below for details. </p>
<dl class="section see"><dt>See also:</dt><dd><a href="http://boost.org/doc/html/signals.html">http://boost.org/doc/html/signals.html</a> for a tutorial on other aspects of signals and slots; you can create connections that have scope, control the order of the invocation of multiple slots that are called by a signal, and combine the return values of such slots (take the first return value, the last, the average of all of them, etc.). </dd></dl>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Jun 15 2012 15:13:31 for GG by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.1
</small></address>
</body>
</html>
