1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
<!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"/>
<meta name="generator" content="Doxygen 1.8.8"/>
<title>Dillo: lout::signal Namespace Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="https://www.dillo.org/dw/html/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">Dillo
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.8 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li class="current"><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 id="navrow2" class="tabs2">
<ul class="tablist">
<li><a href="namespaces.html"><span>Namespace List</span></a></li>
<li><a href="namespacemembers.html"><span>Namespace Members</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="namespacelout.html">lout</a></li><li class="navelem"><a class="el" href="namespacelout_1_1signal.html">signal</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="namespacelout_1_1signal.html#nested-classes">Classes</a> </div>
<div class="headertitle">
<div class="title">lout::signal Namespace Reference</div> </div>
</div><!--header-->
<div class="contents">
<p>This namespace provides base classes to define signals.
<a href="namespacelout_1_1signal.html#details">More...</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Classes</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class  </td><td class="memItemRight" valign="bottom"><a class="el" href="classlout_1_1signal_1_1Emitter.html">Emitter</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">The base class for signal emitters. <a href="classlout_1_1signal_1_1Emitter.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class  </td><td class="memItemRight" valign="bottom"><a class="el" href="classlout_1_1signal_1_1ObservedObject.html">ObservedObject</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">An observed object has a signal emitter, which tells the receivers, when the object is deleted. <a href="classlout_1_1signal_1_1ObservedObject.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class  </td><td class="memItemRight" valign="bottom"><a class="el" href="classlout_1_1signal_1_1Receiver.html">Receiver</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">The base class for signal receiver base classes. <a href="classlout_1_1signal_1_1Receiver.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>This namespace provides base classes to define signals. </p>
<p>By using signals, objects may be connected at run-time, e.g. a general button widget may be connected to another application-specific object, which reacts on the operations on the button by the user. In this case, the button e.g. defines a signal "clicked", which is "emitted" each time the user clicks on the button. After the application-specific object has been connected to this signal, a specific method of it will be called each time, this button emits the "clicked" signal.</p>
<p>Below, we will call the level, on which signals are defined, the "general level", and the level, on which the signals are connected, the "caller level".</p>
<h3>Defining Signals</h3>
<p>Typically, signals are grouped. To define a signal group <em>bar</em> for your class <em>Foo</em>, you have to define two classes, the emitter and the receiver (BarEmitter and BarReceiver), and instantiate the emitter:</p>
<div align="center">
<img src="dot_inline_dotgraph_22.png" alt="dot_inline_dotgraph_22.png" border="0" usemap="#dot_inline_dotgraph_22.map"/>
<map name="dot_inline_dotgraph_22.map" id="dot_inline_dotgraph_22.map"><area shape="rect" id="node1" href="classlout_1_1signal_1_1Emitter.html" title="\N" alt="" coords="27,52,99,101"/><area shape="rect" id="node2" href="classlout_1_1signal_1_1Receiver.html" title="\N" alt="" coords="123,52,197,101"/></map>
</div>
<center>[<a class="el" href="uml-legend.html">legend</a>]</center><p>BarEmitter (class and instance) may be kept private, but BarReceiver must be public, since the caller of Foo must create a sub class of it. For BarEmitter, several methods must be implemented, see <a class="el" href="classlout_1_1signal_1_1Emitter.html" title="The base class for signal emitters. ">signal::Emitter</a> for details. In BarReceiver, only some virtual abstract methods are defined, which the caller must implement. In this case, it is recommended to define a connectBar(BarReceiver*) method in Foo, which is delegated to the BarEmitter.</p>
<h3>Connecting to Signals</h3>
<p>A caller, which wants to connect to a signal, must define a sub class of the receiver, and implement the virtual methods. A typical design looks like this:</p>
<div align="center">
<img src="dot_inline_dotgraph_23.png" alt="dot_inline_dotgraph_23.png" border="0" usemap="#dot_inline_dotgraph_23.map"/>
<map name="dot_inline_dotgraph_23.map" id="dot_inline_dotgraph_23.map"></map>
</div>
<center>[<a class="el" href="uml-legend.html">legend</a>]</center><p>(We skip "baz" in the canon, for better readability.)</p>
<p>Here, the QixBarReceiver is connected to the Qix, so that the signals can be delegated to the Qix. Notice that the receiver gets automatically disconnected, when deleted (see <a class="el" href="classlout_1_1signal_1_1Receiver.html#a160d99de16e066e25f9fc580955e6e49">signal::Receiver::~Receiver</a>).</p>
<h3>Void and Boolean Signals</h3>
<p>In the simplest case, signal emitting involves calling a list of signal receivers (void signals). For boolean signals, the receivers return a boolean value, and the result of the signal emission (the return value of <a class="el" href="classlout_1_1signal_1_1Emitter.html#a86a15101d775b2065432a34ca2a8d843" title="Emit a boolean signal. ">signal::Emitter::emitBool</a>) returns the disjunction of the values returned by the receivers. Typically, a receiver states with its return value, whether the signal was used in any way, the resulting return value so indicates, whether at least one receiver has used the signal.</p>
<p>In Dw, events are processed this way. In the simplest case, they are delegated to the parent widget, if the widget does not process them (by returning false). As an addition, signals are emitted, and if a receiver processes the event, this is handled the same way, as if the widget itself would have processed it.</p>
<p>Notice, that also for boolean signals, all receivers are called, even after one receiver has already returned true.</p>
<h3>Memory Management</h3>
<h4>Emitters</h4>
<p>Emitters are typically instantiated one, for one object emitting the signals. In the example above, the class Foo will contain a field "BarEmitter barEmitter" (not as a pointer, "BarEmitter *barEmitter").</p>
<h4>Receivers</h4>
<p>It is important, that a emitter never deletes a receiver, it just removes them from the receivers list. Likewise, when a receiver is deleted, it unconnects itself from all emitters. (The same receiver instance can indeed be connected to multiple emitters.) So, the caller has to care about deleting receivers.</p>
<p>In the example above, something like that will work:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Qix</div>
<div class="line">{</div>
<div class="line"><span class="keyword">private</span>:</div>
<div class="line"> <span class="keyword">class </span>QixBarReceiver</div>
<div class="line"> {</div>
<div class="line"> <span class="keyword">public</span>:</div>
<div class="line"> Qix *qix;</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line"> };</div>
<div class="line"></div>
<div class="line"> QixBarReceiver barReceiver;</div>
<div class="line"></div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">};</div>
</div><!-- fragment --><p>The constructor of Qix should then set <em>qix:</em> </p>
<div class="fragment"><div class="line">Qix::Qix ()</div>
<div class="line">{</div>
<div class="line"> barReceiver.qix = this.</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>After this, &<em>barReceiver</em> can be connected to all instances of BarEmitter, also multiple times. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sat May 28 2016 11:47:45 for Dillo by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.8
</small></address>
</body>
</html>
|
