Debian Codegraph @

Documentation/Overview/signals.xml

raw
1 <xml>
2 <head>
3 <title>Signals and Slots</title>
4 </head>
5 <body>
6
7 <p>Signals and slots are used for communication between objects. In GUI programming we often
8 want a change in one component to be notified to another component. More generally, we want objects
9 of any kind to be able to communicate with one another. In ClanLib we started using signals
10 in ClanGUI, but broadened it up into other areas, like network and input.</p>
11
12 <p>Older toolkits achieve this kind of communication using callbacks. A callback is a pointer to a
13 function, so if you want a processing function to notify you about some event you pass a pointer
14 to another function (the callback) to the processing function. The processing function then calls
15 the callback when appropriate. Callbacks have two fundamental flaws. Firstly they are not type safe.
16 We can never be certain that the processing function will call the callback with the correct arguments.
17 Secondly the callback is strongly coupled to the processing function since the processing function must
18 know which callback to call.</p>
19
20 <p>In ClanLib we have an alternative to the callback technique. We use signals and slots. A signal is
21 emitted when a particular event occurs. ClanLib's components have many pre-defined signals. To handle
22 the signals that you are interested in, you connect the signal to a slot.</p>
23
24 <p>Signals are emitted by objects when they change their state in a way that may be interesting to
25 the outside world. This is all the object does to communicate. It does not know or care whether
26 anything is receiving the signals it emits. This is true information encapsulation. A signal can be
27 connected to as many slots as you desire.</p>
28
29 <p>A list box, for example, emits both highlighted() and activated() signals. Most objects will probably only be
30 interested in activated() but some may want to know about which item in the list box is currently highlighted.
31 If the signal is interesting to two different objects you just connect the signal to slots in both objects.</p>
32
33 <p>When a signal is emitted, the slots connected to it are executed immediately, just like a normal function
34 call. The emit will return when all slots have returned.</p>
35
36 <p>Slots can be used for receiving signals, but they are normal member functions. A slot does not
37 know if it has any signals connected to it.</p>
38
39 <p>Slot objects maintains connection state to the signals to which they are connected. When a slot
40 object is destroyed, the signals to which it was connected will be automatically informed,
41 and subsequently disconnected. However, this also means that it's important to be aware that
42 you have to store the slots somewhere (even though they slots themselves are never used actively).</p>
43
44 <p>A minimal C++ class declaration might read:</p>
45 <code>
46 class Foo
47 {
48 public:
49 Foo();
50 int get_value() const { return val; }
51 void set_value(int);
52
53 private:
54 int val;
55 };
56 </code>
57
58 <p>Adding a signal to this:</p>
59
60 <code>
61 class Foo
62 {
63 public:
64 Foo();
65 int get_value() const { return val; }
66 void set_value(int);
67
68 CL_Signal_v1<int> sig_value_changed;
69
70 private:
71 int val;
72 };
73 </code>
74
75 <p>This class has the same internal state, and public methods to access the state, but in addition it has
76 support for component programming using signals and slots: this class can tell the outside world that
77 its state has changed by emitting a signal, sig_value_changed.</p>
78
79 <p>The template-type of the signal class is called CL_Signal_v1. The _v1 means void, 1 parameter. If we
80 wanted a type with 2 parameters, we would create a signal of type CL_Signal_v2:</p>
81 <code>
82 CL_Signal_v2<int, const std::string &text> sig_another_example;
83 CL_Signal_v3<char, char, int> sig_yet_another_example;
84 </code>
85 <p>Currently void is the only return type supported, so all signals are called CL_Signal_v?.</p>
86
87 <h3>Emitting signals</h3>
88 <p>Here is a possible implementation of Foo::set_value():</p>
89
90 <code>
91 void Foo::set_value(int v)
92 {
93 if (v != val)
94 {
95 val = v;
96 sig_value_changed(v);
97 }
98 }
99 </code>
100
101 <p>The line sig_value_changed(v) emits the signal sig_value_changed from the object. As you can see, you emit
102 a signal by calling the signal as a function(arguments). Examples on the _v2 and _v3 signals mentioned above:</p>
103 <code>
104 sig_another_example(10, "Hello world");
105 sig_yet_another_example('a', 'b', 10);
106 </code>
107
108 <h3>Connecting to signals</h3>
109
110 <p>Connecting to a signal is pretty straightforward as well:</p>
111 <code>
112 class FooTester
113 {
114 public:
115 FooTester();
116 void test();
117
118 private:
119 void on_value_changed(int val);
120
121 Foo foo;
122 CL_Slot slot_value_changed;
123 }
124
125 FooTester::FooTester()
126 {
127 slot_value_changed = foo.sig_value_changed.connect(this, &FooTester::on_value_changed);
128 }
129
130 void FooTester::test()
131 {
132 foo.set_value(49);
133 }
134
135 void FooTester::on_value_changed(int val)
136 {
137 std::cout << "New value from foo object is " << val << std::endl;
138 }
139 </code>
140
141 <p>Explanation:</p>
142 <code>
143 CL_Slot slot_value_changed;
144 </code>
145 <p>Make sure you store the CL_Slot object somewhere, otherwise the slot is disconnected when it is destroyed
146 (goes out of scope for instance). Put it in your class definition or similar; just don't make it a local variable.</p>
147
148 <code>
149 slot_value_changed = foo.sig_value_changed.connect(this, &FooTester::on_value_changed);
150 </code>
151 <p>Each signal has a connect() function, which returns a CL_Slot object you need to keep. It takes
152 two parameters; the object of the receiving slot, and the definition of the receiving slot. Most often the first
153 argument will be <b>this</b>, but you can actually connect it to another class than your current object:</p>
154 <code>
155 slot_value_changed = foo.sig_value_changed.connect(myOtherObject, &OtherObject::on_value_changed);
156 </code>
157
158 <h3>Slot Container</h3>
159 <p>CL_SlotContainer is a utility class which can store CL_Slots for you. Its syntax is as follows:
160 <code>
161 CL_SlotContainer slots;
162 ...
163 slots.connect(mySignal1, this, &MyApp::on_signal1);
164 slots.connect(mySignal2, this, &MyApp::on_signal2);
165 slots.connect(mySignal3, this, &MyApp::on_signal3);
166 </code>
167 <p>You see the syntax for connecting signals using a CL_SlotContainer is a little bit different than the
168 CL_Slot method (example below).</p>
169 <code>
170 CL_Slot slot1, slot2, slot3;
171 ...
172 slot1 = mySignal1.connect(this, &MyApp::on_signal1);
173 slot2 = mySignal2.connect(this, &MyApp::on_signal2);
174 slot3 = mySignal3.connect(this, &MyApp::on_signal3);
175 </code>
176
177 <h3>Disconnecting slots</h3>
178
179 <p>It is possible to disconnect a slot from its signal. This is automatically done when the slot
180 is deleted/leaves scope, but you can also call the signal.disconnect() function to disable a slot.</p>
181
182 <code>
183 CL_Slot slot1;
184 slot1 = mySignal1.connect(this, &MyApp::on_signal1);
185
186 ...
187
188 mySignal1.disconnect(slot1);
189 </code>
190
191 <h3>Virtual slots</h3>
192
193 <p>ClanLib supports "virtual" slots, meaning you can override previously connected slots.
194 This works like the inheritage in C++, you can call earlier hooked up signals from the
195 overridden slot.</p>
196
197 <p>A normal connect looks like this:</p>
198
199 <code>
200 CL_Slot slot = window.sig_close().connect(this, &App::on_close);
201
202 void App::on_close() { ... }
203
204 </code>
205
206 <p>But to override any previously connected signals, you use the connect_virtual method:</p>
207
208 <code>
209 CL_Slot slot = window.sig_close().connect_virtual(this, &App::on_close);
210
211 void App::on_close(CL_SlotParent_v0 &super)
212 {
213 if(I_want_to_call_parent_slow)
214 super();
215 }
216
217 </code>
218
219 <p>Note that the connected function must have an extra parameter, the CL_SlotParent.
220 This is a reference to the previously connected signal, and you can call it if
221 you want, just like virtual methods in C++.</p>
222
223 <h3>Userdata</h3>
224
225 <p>When a signal is fired, the connected slots are called with the parameters defined in the signal.
226 Sometimes you want to add extra information to each slot, and for that ClanLib provides userdata.
227 It is used by adding an extra variable when connecting to the signal.</p>
228
229 <code>
230 void App::on_signal(int a, int b)
231 {
232 }
233
234 CL_Signal_v2<int, int> mySignal;
235
236 CL_Slot slot = mySignal.connect(this, &App::on_signal);
237 </code>
238
239 <p>This is how you would connect to a normal signal, without using any userdata. The signal
240 requires two params, and you supply a function with two params.</p>
241
242 <code>
243 void App::on_signal(int a, int b, std::string userdata)
244 {
245 }
246
247 CL_Signal_v2<int, int> mySignal;
248
249 std::string text = "Hello";
250
251 CL_Slot slot = mySignal.connect(this, &App::on_signal, text);
252 </code>
253
254 <p>Here we used the exact same signal, but added a string parameters as a userdata. Each
255 time the signal is now fired, the userdata string will contain the string "hello".</p>
256
257 <p>You can use any type for the userdata, be it string, ints, whatever.</p>
258
259 <code>
260 CL_SlotContainer slots;
261 slots.connect(button1.sig_button_press(), this, &App::on_button_press, 1);
262 slots.connect(button2.sig_button_press(), this, &App::on_button_press, 2);
263 slots.connect(button3.sig_button_press(), this, &App::on_button_press, 3);
264 </code>
265
266 <p>In this example, userdata is used to connect several button clicks to the same function,
267 but with an extra userdata integer describing which button was pressed.</p>
268
269 <h3>Specific ClanLib signals</h3>
270
271 <p>All signals in ClanLib is a little bit different than explained in this overview so far - they are all functions.
272 The only effect this has on your code is that you put parenthesis behind the signal when connecting to it.
273 Some examples:</p>
274
275 <code>
276 CL_Mouse: (clanDisplay)
277 static CL_Signal_v2<int, int> &sig_move();
278 static CL_Signal_v1<const CL_InputEvent &> &sig_button_press();
279 static CL_Signal_v1<const CL_InputEvent &> &sig_button_release();
280
281 CL_Component: (clanGUI)
282 CL_Signal_v1<const CL_InputEvent &> & sig_mouse_down();
283
284 CL_Button: (clanGUI)
285 CL_Signal_v1<bool> &sig_toggled();
286 CL_Signal_v0 &sig_clicked();
287
288 Usage examples:
289 CL_Slot slot1 = CL_Mouse::sig_move().connect(this, &App::on_mouse_move);
290 CL_Slot slot2 = button->sig_clicked().connect(this, &GUIApp::on_button_clicked);
291 CL_Slot slot3 = component->sig_mouse_down().connect(this, &GUIApp::on_component_mouse_down);
292
293 void App::on_mouse_move(int x, int y);
294 void GUIApp::on_button_toggled(bool state);
295 void GUIApp::on_component_mouse_down(const CL_InputEvent &key);
296 </code>
297
298 <p>As you see, the only different is the parenthesis - sig_clicked() instead of sig_clicked.</p>
299
300 <h3>More examples</h3>
301
302 <p>If you need to see some real world examples of signals and slots, have a look at the <a href="gui_overview.html">GUI overview</a>.</p>
303
304 <p>Thanks to TrollTech and their QT toolkit for their Signal & Slot explanation; this overview was
305 based on theirs.</p>
306
307 </body>
308 </xml>