1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5 \page signalsandslots.html
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}.
20 \section1 Introduction
22 In GUI programming, when we change one widget, we often want
23 another widget to be notified. More generally, we want objects of
24 any kind to be able to communicate with one another. For example,
25 if a user clicks a \uicontrol{Close} button, we probably want the
26 window's \l{QWidget::close()}{close()} function to be called.
28 Other toolkits achieve this kind of communication using
29 callbacks. A callback is a pointer to a function, so if you want
30 a processing function to notify you about some event you pass a
31 pointer to another function (the callback) to the processing
32 function. The processing function then calls the callback when
33 appropriate. While successful frameworks using this method do exist,
34 callbacks can be unintuitive and may suffer from problems in ensuring
35 the type-correctness of callback arguments.
37 \section1 Signals and Slots
39 In Qt, we have an alternative to the callback technique: We use
40 signals and slots. A signal is emitted when a particular event
41 occurs. Qt's widgets have many predefined signals, but we can
42 always subclass widgets to add our own signals to them. A slot
43 is a function that is called in response to a particular signal.
44 Qt's widgets have many pre-defined slots, but it is common
45 practice to subclass widgets and add your own slots so that you
46 can handle the signals that you are interested in.
48 \image abstract-connections.png
50 \caption An abstract view of some signals and slots connections
53 The signals and slots mechanism is type safe: The signature of a
54 signal must match the signature of the receiving slot. (In fact a
55 slot may have a shorter signature than the signal it receives
56 because it can ignore extra arguments.) Since the signatures are
57 compatible, the compiler can help us detect type mismatches when
58 using the function pointer-based syntax. The string-based SIGNAL
59 and SLOT syntax will detect type mismatches at runtime.
60 Signals and slots are loosely coupled: A class which emits a
61 signal neither knows nor cares which slots receive the signal.
62 Qt's signals and slots mechanism ensures that if you connect a
63 signal to a slot, the slot will be called with the signal's
64 parameters at the right time. Signals and slots can take any
65 number of arguments of any type. They are completely type safe.
67 All classes that inherit from QObject or one of its subclasses
68 (e.g., QWidget) can contain signals and slots. Signals are emitted by
69 objects when they change their state in a way that may be interesting
70 to other objects. This is all the object does to communicate. It
71 does not know or care whether anything is receiving the signals it
72 emits. This is true information encapsulation, and ensures that the
73 object can be used as a software component.
75 Slots can be used for receiving signals, but they are also normal
76 member functions. Just as an object does not know if anything receives
77 its signals, a slot does not know if it has any signals connected to
78 it. This ensures that truly independent components can be created with
81 You can connect as many signals as you want to a single slot, and a
82 signal can be connected to as many slots as you need. It is even
83 possible to connect a signal directly to another signal. (This will
84 emit the second signal immediately whenever the first is emitted.)
86 Together, signals and slots make up a powerful component programming
92 Signals are emitted by an object when its internal state has changed
93 in some way that might be interesting to the object's client or owner.
94 Signals are public access functions and can be emitted from anywhere,
95 but we recommend to only emit them from the class that defines the
96 signal and its subclasses.
98 When a signal is emitted, the slots connected to it are usually
99 executed immediately, just like a normal function call. When this
100 happens, the signals and slots mechanism is totally independent of
101 any GUI event loop. Execution of the code following the \c emit
102 statement will occur once all slots have returned. The situation is
103 slightly different when using \l{Qt::ConnectionType}{queued
104 connections}; in such a case, the code following the \c emit keyword
105 will continue immediately, and the slots will be executed later.
107 If several slots are connected to one signal, the slots will be
108 executed one after the other, in the order they have been connected,
109 when the signal is emitted.
111 Signals are automatically generated by the \l moc and must not be
112 implemented in the \c .cpp file.
114 A note about arguments: Our experience shows that signals and slots
115 are more reusable if they do not use special types. If
116 QScrollBar::valueChanged() were to use a special type such as the
117 hypothetical QScrollBar::Range, it could only be connected to
118 slots designed specifically for QScrollBar. Connecting different
119 input widgets together would be impossible.
123 A slot is called when a signal connected to it is emitted. Slots are
124 normal C++ functions and can be called normally; their only special
125 feature is that signals can be connected to them.
127 Since slots are normal member functions, they follow the normal C++
128 rules when called directly. However, as slots, they can be invoked
129 by any component, regardless of its access level, via a signal-slot
130 connection. This means that a signal emitted from an instance of an
131 arbitrary class can cause a private slot to be invoked in an instance
132 of an unrelated class.
134 You can also define slots to be virtual, which we have found quite
137 Compared to callbacks, signals and slots are slightly slower
138 because of the increased flexibility they provide, although the
139 difference for real applications is insignificant. In general,
140 emitting a signal that is connected to some slots, is
141 approximately ten times slower than calling the receivers
142 directly, with non-virtual function calls. This is the overhead
143 required to locate the connection object, to safely iterate over
144 all connections (i.e. checking that subsequent receivers have not
145 been destroyed during the emission), and to marshall any
146 parameters in a generic fashion. While ten non-virtual function
147 calls may sound like a lot, it's much less overhead than any \c
148 new or \c delete operation, for example. As soon as you perform a
149 string, vector or list operation that behind the scene requires
150 \c new or \c delete, the signals and slots overhead is only
151 responsible for a very small proportion of the complete function
152 call costs. The same is true whenever you do a system call in a slot;
153 or indirectly call more than ten functions.
154 The simplicity and flexibility of the signals and slots mechanism is
155 well worth the overhead, which your users won't even notice.
157 Note that other libraries that define variables called \c signals
158 or \c slots may cause compiler warnings and errors when compiled
159 alongside a Qt-based application. To solve this problem, \c
160 #undef the offending preprocessor symbol.
163 \section1 A Small Example
165 A minimal C++ class declaration might read:
167 \snippet signalsandslots/signalsandslots.h 0
169 A small QObject-based class might read:
171 \snippet signalsandslots/signalsandslots.h 1
173 \snippet signalsandslots/signalsandslots.h 2
174 \snippet signalsandslots/signalsandslots.h 3
176 The QObject-based version has the same internal state, and provides
177 public methods to access the state, but in addition it has support
178 for component programming using signals and slots. This class can
179 tell the outside world that its state has changed by emitting a
180 signal, \c{valueChanged()}, and it has a slot which other objects
183 All classes that contain signals or slots must mention
184 Q_OBJECT at the top of their declaration. They must also derive
185 (directly or indirectly) from QObject.
187 Slots are implemented by the application programmer.
188 Here is a possible implementation of the \c{Counter::setValue()}
191 \snippet signalsandslots/signalsandslots.cpp 0
193 The \c{emit} line emits the signal \c valueChanged() from the
194 object, with the new value as argument.
196 In the following code snippet, we create two \c Counter objects
197 and connect the first object's \c valueChanged() signal to the
198 second object's \c setValue() slot using QObject::connect():
200 \snippet signalsandslots/signalsandslots.cpp 1
201 \snippet signalsandslots/signalsandslots.cpp 2
203 \snippet signalsandslots/signalsandslots.cpp 3
204 \snippet signalsandslots/signalsandslots.cpp 4
206 Calling \c{a.setValue(12)} makes \c{a} emit a
207 \c{valueChanged(12)} signal, which \c{b} will receive in its
208 \c{setValue()} slot, i.e. \c{b.setValue(12)} is called. Then
209 \c{b} emits the same \c{valueChanged()} signal, but since no slot
210 has been connected to \c{b}'s \c{valueChanged()} signal, the
213 Note that the \c{setValue()} function sets the value and emits
214 the signal only if \c{value != m_value}. This prevents infinite
215 looping in the case of cyclic connections (e.g., if
216 \c{b.valueChanged()} were connected to \c{a.setValue()}).
218 By default, for every connection you make, a signal is emitted;
219 two signals are emitted for duplicate connections. You can break
220 all of these connections with a single \l{QObject::disconnect()}{disconnect()} call.
221 If you pass the Qt::UniqueConnection \a type, the connection will only
222 be made if it is not a duplicate. If there is already a duplicate
223 (exact same signal to the exact same slot on the same objects),
224 the connection will fail and connect will return \c false.
226 This example illustrates that objects can work together without needing to
227 know any information about each other. To enable this, the objects only
228 need to be connected together, and this can be achieved with some simple
229 QObject::connect() function calls, or with \l{User Interface Compiler
230 (uic)}{uic}'s \l{Automatic Connections}{automatic connections} feature.
233 \section1 A Real Example
235 The following is an example of the header of a simple widget class without
236 member functions. The purpose is to show how you can utilize signals and
237 slots in your own applications.
239 \snippet signalsandslots/lcdnumber.h 0
240 \snippet signalsandslots/lcdnumber.h 1
242 \snippet signalsandslots/lcdnumber.h 2
244 \snippet signalsandslots/lcdnumber.h 3
245 \snippet signalsandslots/lcdnumber.h 4
246 \snippet signalsandslots/lcdnumber.h 5
248 \c LcdNumber inherits QObject, which has most of the signal-slot
249 knowledge, via QFrame and QWidget. It is somewhat similar to the
250 built-in QLCDNumber widget.
252 The Q_OBJECT macro is expanded by the preprocessor to declare
253 several member functions that are implemented by the \c{moc}; if
254 you get compiler errors along the lines of "undefined reference
255 to vtable for \c{LcdNumber}", you have probably forgotten to
256 \l{moc}{run the moc} or to include the moc output in the link
259 \snippet signalsandslots/lcdnumber.h 6
260 \snippet signalsandslots/lcdnumber.h 7
262 \snippet signalsandslots/lcdnumber.h 8
263 \snippet signalsandslots/lcdnumber.h 9
265 After the class constructor and \c public members, we declare the class
266 \c signals. The \c LcdNumber class emits a signal, \c overflow(), when it
267 is asked to show an impossible value.
269 If you don't care about overflow, or you know that overflow
270 cannot occur, you can ignore the \c overflow() signal, i.e. don't
271 connect it to any slot.
273 If on the other hand you want to call two different error
274 functions when the number overflows, simply connect the signal to
275 two different slots. Qt will call both (in the order they were connected).
277 \snippet signalsandslots/lcdnumber.h 10
278 \snippet signalsandslots/lcdnumber.h 11
279 \snippet signalsandslots/lcdnumber.h 12
281 \snippet signalsandslots/lcdnumber.h 13
283 A slot is a receiving function used to get information about
284 state changes in other widgets. \c LcdNumber uses it, as the code
285 above indicates, to set the displayed number. Since \c{display()}
286 is part of the class's interface with the rest of the program,
289 Several of the example programs connect the
290 \l{QScrollBar::valueChanged()}{valueChanged()} signal of a
291 QScrollBar to the \c display() slot, so the LCD number
292 continuously shows the value of the scroll bar.
294 Note that \c display() is overloaded; Qt will select the
295 appropriate version when you connect a signal to the slot. With
296 callbacks, you'd have to find five different names and keep track
297 of the types yourself.
299 \sa QLCDNumber, QObject::connect()
301 \section1 Signals And Slots With Default Arguments
303 The signatures of signals and slots may contain arguments, and the
304 arguments can have default values. Consider QObject::destroyed():
307 void destroyed(QObject* = nullptr);
310 When a QObject is deleted, it emits this QObject::destroyed()
311 signal. We want to catch this signal, wherever we might have a
312 dangling reference to the deleted QObject, so we can clean it up.
313 A suitable slot signature might be:
316 void objectDestroyed(QObject* obj = nullptr);
319 To connect the signal to the slot, we use QObject::connect().
320 There are several ways to connect signal and slots. The first is to use
323 connect(sender, &QObject::destroyed, this, &MyObject::objectDestroyed);
326 There are several advantages to using QObject::connect() with function pointers.
327 First, it allows the compiler to check that the signal's arguments are
328 compatible with the slot's arguments. Arguments can also be implicitly
329 converted by the compiler, if needed.
331 You can also connect to functors or C++11 lambdas:
334 connect(sender, &QObject::destroyed, this, [=](){ this->m_objects.remove(sender); });
337 In both these cases, we provide \a this as context in the call to connect().
338 The context object provides information about in which thread the receiver
339 should be executed. This is important, as providing the context ensures
340 that the receiver is executed in the context thread.
342 The lambda will be disconnected when the sender or context is destroyed.
343 You should take care that any objects used inside the functor are still
344 alive when the signal is emitted.
346 The other way to connect a signal to a slot is to use QObject::connect()
347 and the \c{SIGNAL} and \c{SLOT} macros.
348 The rule about whether to include arguments or not in the \c{SIGNAL()} and
349 \c{SLOT()} macros, if the arguments have default values, is that the
350 signature passed to the \c{SIGNAL()} macro must \e not have fewer arguments
351 than the signature passed to the \c{SLOT()} macro.
353 All of these would work:
355 connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed(Qbject*)));
356 connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed()));
357 connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed()));
359 But this one won't work:
361 connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed(QObject*)));
364 ...because the slot will be expecting a QObject that the signal
365 will not send. This connection will report a runtime error.
367 Note that signal and slot arguments are not checked by the compiler when
368 using this QObject::connect() overload.
370 \section1 Advanced Signals and Slots Usage
372 For cases where you may require information on the sender of the
373 signal, Qt provides the QObject::sender() function, which returns
374 a pointer to the object that sent the signal.
376 Lambda expressions are a convenient way to pass custom arguments to a slot:
379 connect(action, &QAction::triggered, engine,
380 [=]() { engine->processAction(action->text()); });
383 \sa {Meta-Object System}, {Qt's Property System}
385 \target 3rd Party Signals and Slots
386 \section2 Using Qt with 3rd Party Signals and Slots
388 It is possible to use Qt with a 3rd party signal/slot mechanism.
389 You can even use both mechanisms in the same project. To do that,
390 write the following into your CMake project file:
392 \snippet code/doc_src_containers.cpp cmake_no_keywords
394 In a qmake project (.pro) file, you need to write:
396 \snippet code/doc_src_containers.cpp 22
398 It tells Qt not to define the moc keywords \c{signals}, \c{slots},
399 and \c{emit}, because these names will be used by a 3rd party
400 library, e.g. Boost. Then to continue using Qt signals and slots
401 with the \c{no_keywords} flag, simply replace all uses of the Qt
402 moc keywords in your sources with the corresponding Qt macros
403 Q_SIGNALS (or Q_SIGNAL), Q_SLOTS (or Q_SLOT), and Q_EMIT.
405 \section2 Signals and slots in Qt-based libraries
407 The public API of Qt-based libraries should use the keywords
408 \c{Q_SIGNALS} and \c{Q_SLOTS} instead of \c{signals} and
409 \c{slots}. Otherwise it is hard to use such a library in a project
410 that defines \c{QT_NO_KEYWORDS}.
412 To enforce this restriction, the library creator may set the
413 preprocessor define \c{QT_NO_SIGNALS_SLOTS_KEYWORDS} when building
416 This define excludes signals and slots without affecting whether
417 other Qt-specific keywords can be used in the library
1.10.0