Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
signalsandslots.qdoc
Go to the documentation of this file.
1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \page signalsandslots.html
6 \title Signals & Slots
7 \keyword Signals and Slots
8 \ingroup qt-basic-concepts
9 \brief An overview of Qt's signals and slots inter-object
10 communication mechanism.
11 \ingroup explanations-basics
12 Signals and slots are used for communication between objects. The
13 signals and slots mechanism is a central feature of Qt and
14 probably the part that differs most from the features provided by
15 other frameworks. Signals and slots are made possible by Qt's
16 \l{The Meta-Object System}{meta-object system}.
17
18 \section1 Introduction
19
20 In GUI programming, when we change one widget, we often want
21 another widget to be notified. More generally, we want objects of
22 any kind to be able to communicate with one another. For example,
23 if a user clicks a \uicontrol{Close} button, we probably want the
24 window's \l{QWidget::close()}{close()} function to be called.
25
26 Other toolkits achieve this kind of communication using
27 callbacks. A callback is a pointer to a function, so if you want
28 a processing function to notify you about some event you pass a
29 pointer to another function (the callback) to the processing
30 function. The processing function then calls the callback when
31 appropriate. While successful frameworks using this method do exist,
32 callbacks can be unintuitive and may suffer from problems in ensuring
33 the type-correctness of callback arguments.
34
35 \section1 Signals and Slots
36
37 In Qt, we have an alternative to the callback technique: We use
38 signals and slots. A signal is emitted when a particular event
39 occurs. Qt's widgets have many predefined signals, but we can
40 always subclass widgets to add our own signals to them. A slot
41 is a function that is called in response to a particular signal.
42 Qt's widgets have many pre-defined slots, but it is common
43 practice to subclass widgets and add your own slots so that you
44 can handle the signals that you are interested in.
45
46 \image abstract-connections.svg "Connections between objects"
47 \omit
48 \caption An abstract view of some signals and slots connections
49 \endomit
50
51 The signals and slots mechanism is type safe: The signature of a
52 signal must match the signature of the receiving slot. (In fact a
53 slot may have a shorter signature than the signal it receives
54 because it can ignore extra arguments.) Since the signatures are
55 compatible, the compiler can help us detect type mismatches when
56 using the function pointer-based syntax. The string-based SIGNAL
57 and SLOT syntax will detect type mismatches at runtime.
58 Signals and slots are loosely coupled: A class which emits a
59 signal neither knows nor cares which slots receive the signal.
60 Qt's signals and slots mechanism ensures that if you connect a
61 signal to a slot, the slot will be called with the signal's
62 parameters at the right time. Signals and slots can take any
63 number of arguments of any type. They are completely type safe.
64
65 All classes that inherit from QObject or one of its subclasses
66 (e.g., QWidget) can contain signals and slots. Signals are emitted by
67 objects when they change their state in a way that may be interesting
68 to other objects. This is all the object does to communicate. It
69 does not know or care whether anything is receiving the signals it
70 emits. This is true information encapsulation, and ensures that the
71 object can be used as a software component.
72
73 Slots can be used for receiving signals, but they are also normal
74 member functions. Just as an object does not know if anything receives
75 its signals, a slot does not know if it has any signals connected to
76 it. This ensures that truly independent components can be created with
77 Qt.
78
79 You can connect as many signals as you want to a single slot, and a
80 signal can be connected to as many slots as you need. It is even
81 possible to connect a signal directly to another signal. (This will
82 emit the second signal immediately whenever the first is emitted.)
83
84 Together, signals and slots make up a powerful component programming
85 mechanism.
86
87
88 \section1 Signals
89
90 Signals are emitted by an object when its internal state has changed
91 in some way that might be interesting to the object's client or owner.
92 Signals are public access functions and can be emitted from anywhere,
93 but we recommend to only emit them from the class that defines the
94 signal and its subclasses.
95
96 When a signal is emitted, the slots connected to it are usually
97 executed immediately, just like a normal function call. When this
98 happens, the signals and slots mechanism is totally independent of
99 any GUI event loop. Execution of the code following the \c emit
100 statement will occur once all slots have returned. The situation is
101 slightly different when using \l{Qt::ConnectionType}{queued
102 connections}; in such a case, the code following the \c emit keyword
103 will continue immediately, and the slots will be executed later.
104
105 If several slots are connected to one signal, the slots will be
106 executed one after the other, in the order they have been connected,
107 when the signal is emitted.
108
109 Signals are automatically generated by the \l moc and must not be
110 implemented in the \c .cpp file.
111
112 A note about arguments: Our experience shows that signals and slots
113 are more reusable if they do not use special types. If
114 QScrollBar::valueChanged() were to use a special type such as the
115 hypothetical QScrollBar::Range, it could only be connected to
116 slots designed specifically for QScrollBar. Connecting different
117 input widgets together would be impossible.
118
119 \section1 Slots
120
121 A slot is called when a signal connected to it is emitted. Slots are
122 normal C++ functions and can be called normally; their only special
123 feature is that signals can be connected to them.
124
125 Since slots are normal member functions, they follow the normal C++
126 rules when called directly. However, as slots, they can be invoked
127 by any component, regardless of its access level, via a signal-slot
128 connection. This means that a signal emitted from an instance of an
129 arbitrary class can cause a private slot to be invoked in an instance
130 of an unrelated class.
131
132 You can also define slots to be virtual, which we have found quite
133 useful in practice.
134
135 Compared to callbacks, signals and slots are slightly slower
136 because of the increased flexibility they provide, although the
137 difference for real applications is insignificant. In general,
138 emitting a signal that is connected to some slots, is
139 approximately ten times slower than calling the receivers
140 directly, with non-virtual function calls. This is the overhead
141 required to locate the connection object, to safely iterate over
142 all connections (i.e. checking that subsequent receivers have not
143 been destroyed during the emission), and to marshall any
144 parameters in a generic fashion. While ten non-virtual function
145 calls may sound like a lot, it's much less overhead than any \c
146 new or \c delete operation, for example. As soon as you perform a
147 string, vector or list operation that behind the scene requires
148 \c new or \c delete, the signals and slots overhead is only
149 responsible for a very small proportion of the complete function
150 call costs. The same is true whenever you do a system call in a slot;
151 or indirectly call more than ten functions.
152 The simplicity and flexibility of the signals and slots mechanism is
153 well worth the overhead, which your users won't even notice.
154
155 Note that other libraries that define variables called \c signals
156 or \c slots may cause compiler warnings and errors when compiled
157 alongside a Qt-based application. To solve this problem, \c
158 #undef the offending preprocessor symbol.
159
160
161 \section1 A Small Example
162
163 A minimal C++ class declaration might read:
164
165 \snippet signalsandslots/signalsandslots.h 0
166
167 A small QObject-based class might read:
168
169 \snippet signalsandslots/signalsandslots.h 1
170 \codeline
171 \snippet signalsandslots/signalsandslots.h 2
172 \snippet signalsandslots/signalsandslots.h 3
173
174 The QObject-based version has the same internal state, and provides
175 public methods to access the state, but in addition it has support
176 for component programming using signals and slots. This class can
177 tell the outside world that its state has changed by emitting a
178 signal, \c{valueChanged()}, and it has a slot which other objects
179 can send signals to.
180
181 All classes that contain signals or slots must mention
182 Q_OBJECT at the top of their declaration. They must also derive
183 (directly or indirectly) from QObject.
184
185 Slots are implemented by the application programmer.
186 Here is a possible implementation of the \c{Counter::setValue()}
187 slot:
188
189 \snippet signalsandslots/signalsandslots.cpp 0
190
191 The \c{emit} line emits the signal \c valueChanged() from the
192 object, with the new value as argument.
193
194 In the following code snippet, we create two \c Counter objects
195 and connect the first object's \c valueChanged() signal to the
196 second object's \c setValue() slot using QObject::connect():
197
198 \snippet signalsandslots/signalsandslots.cpp 1
199 \snippet signalsandslots/signalsandslots.cpp 2
200 \codeline
201 \snippet signalsandslots/signalsandslots.cpp 3
202 \snippet signalsandslots/signalsandslots.cpp 4
203
204 Calling \c{a.setValue(12)} makes \c{a} emit a
205 \c{valueChanged(12)} signal, which \c{b} will receive in its
206 \c{setValue()} slot, i.e. \c{b.setValue(12)} is called. Then
207 \c{b} emits the same \c{valueChanged()} signal, but since no slot
208 has been connected to \c{b}'s \c{valueChanged()} signal, the
209 signal is ignored.
210
211 Note that the \c{setValue()} function sets the value and emits
212 the signal only if \c{value != m_value}. This prevents infinite
213 looping in the case of cyclic connections (e.g., if
214 \c{b.valueChanged()} were connected to \c{a.setValue()}).
215
216 By default, for every connection you make, a signal is emitted;
217 two signals are emitted for duplicate connections. You can break
218 all of these connections with a single \l{QObject::disconnect()}{disconnect()} call.
219 If you pass the Qt::UniqueConnection \a type, the connection will only
220 be made if it is not a duplicate. If there is already a duplicate
221 (exact same signal to the exact same slot on the same objects),
222 the connection will fail and connect will return \c false.
223
224 This example illustrates that objects can work together without needing to
225 know any information about each other. To enable this, the objects only
226 need to be connected together, and this can be achieved with some simple
227 QObject::connect() function calls, or with \l{User Interface Compiler
228 (uic)}{uic}'s \l{Automatic Connections}{automatic connections} feature.
229
230
231 \section1 A Real Example
232
233 The following is an example of the header of a simple widget class without
234 member functions. The purpose is to show how you can utilize signals and
235 slots in your own applications.
236
237 \snippet signalsandslots/lcdnumber.h 0
238 \snippet signalsandslots/lcdnumber.h 1
239 \codeline
240 \snippet signalsandslots/lcdnumber.h 2
241 \codeline
242 \snippet signalsandslots/lcdnumber.h 3
243 \snippet signalsandslots/lcdnumber.h 4
244 \snippet signalsandslots/lcdnumber.h 5
245
246 \c LcdNumber inherits QObject, which has most of the signal-slot
247 knowledge, via QFrame and QWidget. It is somewhat similar to the
248 built-in QLCDNumber widget.
249
250 The Q_OBJECT macro is expanded by the preprocessor to declare
251 several member functions that are implemented by the \c{moc}; if
252 you get compiler errors along the lines of "undefined reference
253 to vtable for \c{LcdNumber}", you have probably forgotten to
254 \l{moc}{run the moc} or to include the moc output in the link
255 command.
256
257 \snippet signalsandslots/lcdnumber.h 6
258 \snippet signalsandslots/lcdnumber.h 7
259 \codeline
260 \snippet signalsandslots/lcdnumber.h 8
261 \snippet signalsandslots/lcdnumber.h 9
262
263 After the class constructor and \c public members, we declare the class
264 \c signals. The \c LcdNumber class emits a signal, \c overflow(), when it
265 is asked to show an impossible value.
266
267 If you don't care about overflow, or you know that overflow
268 cannot occur, you can ignore the \c overflow() signal, i.e. don't
269 connect it to any slot.
270
271 If on the other hand you want to call two different error
272 functions when the number overflows, simply connect the signal to
273 two different slots. Qt will call both (in the order they were connected).
274
275 \snippet signalsandslots/lcdnumber.h 10
276 \snippet signalsandslots/lcdnumber.h 11
277 \snippet signalsandslots/lcdnumber.h 12
278 \codeline
279 \snippet signalsandslots/lcdnumber.h 13
280
281 A slot is a receiving function used to get information about
282 state changes in other widgets. \c LcdNumber uses it, as the code
283 above indicates, to set the displayed number. Since \c{display()}
284 is part of the class's interface with the rest of the program,
285 the slot is public.
286
287 Several of the example programs connect the
288 \l{QScrollBar::valueChanged()}{valueChanged()} signal of a
289 QScrollBar to the \c display() slot, so the LCD number
290 continuously shows the value of the scroll bar.
291
292 Note that display() is overloaded. Qt's signals and slots give you
293 strongly-typed connections. They're safer at compile time than traditional
294 callbacks. With callbacks, you'd need different function names and manual
295 type tracking. But with overloaded functions, you need to specify which
296 version to use. The next section shows you how.
297
298 \sa QLCDNumber, QObject::connect()
299
300 \target connecting-overloaded-signals
301 \target connecting-overloaded-slots
302 \section1 Connecting to Overloaded Signals and Slots
303
304 When signals or slots are overloaded (have multiple versions with different
305 parameters), you need to explicitly specify which version you want to
306 connect to using the function pointer syntax. You can use qOverload() or
307 \c {static_cast} to disambiguate:
308
309 \code
310 // Connect to the int overload of QComboBox::currentIndexChanged(int)
311 connect(comboBox, qOverload<int>(&QComboBox::currentIndexChanged),
312 this, &MyClass::handleIndexChanged);
313
314 // Or select QLCDNumber::display(int) when connecting from QSlider::valueChanged(int)
315 connect(slider, &QSlider::valueChanged,
316 lcd, qOverload<int>(&QLCDNumber::display));
317
318 // Using static_cast (more verbose):
319 connect(comboBox, static_cast<void(QComboBox::*)(int)>(&QComboBox::currentIndexChanged),
320 this, &MyClass::handleIndexChanged);
321
322 // Or using a lambda to call the correct overload:
323 connect(slider, &QSlider::valueChanged,
324 this, [lcd](int value) { lcd->display(value); });
325 \endcode
326
327 \section1 Automatic Connection Management
328
329 Qt automatically manages the lifetime of connections between
330 \l {QObject}-derived types. When either the sender or receiver object is
331 destroyed, the connection is automatically removed, preventing calls to
332 deleted objects. This applies to both the function-pointer syntax and the
333 string-based SIGNAL/SLOT syntax.
334
335 For lambda connections, provide a context object (usually \c this) to ensure
336 the lambda is disconnected when the context is destroyed:
337
338 \code
339 connect(button, &QPushButton::clicked, this, [this]{ handleClick(); });
340 \endcode
341
342 While Qt protects against signal delivery to fully destroyed objects,
343 signals may still be delivered during object destruction after a derived
344 class destructor has finished but before reaching \c{~QObject}. This
345 limitation applies specifically to connections made with the
346 function-pointer syntax. It can occur when a base class destructor emits
347 signals that the already-destroyed derived class was connected to.
348 Consider explicitly disconnecting such signals in destructors if this
349 could be problematic for your class.
350
351 \section1 Signals And Slots With Default Arguments
352
353 The signatures of signals and slots may contain arguments, and the
354 arguments can have default values. Consider QObject::destroyed():
355
356 \code
357 void destroyed(QObject* = nullptr);
358 \endcode
359
360 When a QObject is deleted, it emits this QObject::destroyed()
361 signal. We want to catch this signal, wherever we might have a
362 dangling reference to the deleted QObject, so we can clean it up.
363 A suitable slot signature might be:
364
365 \code
366 void objectDestroyed(QObject* obj = nullptr);
367 \endcode
368
369 To connect the signal to the slot, we use QObject::connect().
370 There are several ways to connect signal and slots. The first is to use
371 function pointers:
372 \code
373 connect(sender, &QObject::destroyed, this, &MyObject::objectDestroyed);
374 \endcode
375
376 There are several advantages to using QObject::connect() with function pointers.
377 First, it allows the compiler to check that the signal's arguments are
378 compatible with the slot's arguments. Arguments can also be implicitly
379 converted by the compiler, if needed.
380
381 You can also connect to functors or C++11 lambdas:
382
383 \code
384 connect(sender, &QObject::destroyed, this, [=](){ this->m_objects.remove(sender); });
385 \endcode
386
387 In both these cases, we provide \a this as context in the call to connect().
388 The context object provides information about in which thread the receiver
389 should be executed. This is important, as providing the context ensures
390 that the receiver is executed in the context thread.
391
392 The lambda will be disconnected when the sender or context is destroyed.
393 You should take care that any objects used inside the functor are still
394 alive when the signal is emitted.
395
396 The other way to connect a signal to a slot is to use QObject::connect()
397 and the \c{SIGNAL} and \c{SLOT} macros.
398 The rule about whether to include arguments or not in the \c{SIGNAL()} and
399 \c{SLOT()} macros, if the arguments have default values, is that the
400 signature passed to the \c{SIGNAL()} macro must \e not have fewer arguments
401 than the signature passed to the \c{SLOT()} macro.
402
403 All of these would work:
404 \code
405 connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed(Qbject*)));
406 connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed()));
407 connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed()));
408 \endcode
409 But this one won't work:
410 \code
411 connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed(QObject*)));
412 \endcode
413
414 ...because the slot will be expecting a QObject that the signal
415 will not send. This connection will report a runtime error.
416
417 Note that signal and slot arguments are not checked by the compiler when
418 using this QObject::connect() overload.
419
420 \section1 Advanced Signals and Slots Usage
421
422 For cases where you may require information on the sender of the
423 signal, Qt provides the QObject::sender() function, which returns
424 a pointer to the object that sent the signal.
425
426 Lambda expressions are a convenient way to pass custom arguments to a slot:
427
428 \code
429 connect(action, &QAction::triggered, engine,
430 [=]() { engine->processAction(action->text()); });
431 \endcode
432
433 \sa {Meta-Object System}, {Qt's Property System}
434
435 \target 3rd Party Signals and Slots
436 \section2 Using Qt with 3rd Party Signals and Slots
437
438 It is possible to use Qt with a 3rd party signal/slot mechanism.
439 You can even use both mechanisms in the same project. To do that,
440 write the following into your CMake project file:
441
442 \snippet code/doc_src_containers.cpp cmake_no_keywords
443
444 In a qmake project (.pro) file, you need to write:
445
446 \snippet code/doc_src_containers.cpp 22
447
448 It tells Qt not to define the moc keywords \c{signals}, \c{slots},
449 and \c{emit}, because these names will be used by a 3rd party
450 library, e.g. Boost. Then to continue using Qt signals and slots
451 with the \c{no_keywords} flag, simply replace all uses of the Qt
452 moc keywords in your sources with the corresponding Qt macros
453 Q_SIGNALS (or Q_SIGNAL), Q_SLOTS (or Q_SLOT), and Q_EMIT.
454
455 \section2 Signals and slots in Qt-based libraries
456
457 The public API of Qt-based libraries should use the keywords
458 \c{Q_SIGNALS} and \c{Q_SLOTS} instead of \c{signals} and
459 \c{slots}. Otherwise it is hard to use such a library in a project
460 that defines \c{QT_NO_KEYWORDS}.
461
462 To enforce this restriction, the library creator may set the
463 preprocessor define \c{QT_NO_SIGNALS_SLOTS_KEYWORDS} when building
464 the library.
465
466 This define excludes signals and slots without affecting whether
467 other Qt-specific keywords can be used in the library
468 implementation.
469 */