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.
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. They can never have return types
115 A note about arguments: Our experience shows that signals and slots
116 are more reusable if they do not use special types. If
117 QScrollBar::valueChanged() were to use a special type such as the
118 hypothetical QScrollBar::Range, it could only be connected to
119 slots designed specifically for QScrollBar. Connecting different
120 input widgets together would be impossible.
124 A slot is called when a signal connected to it is emitted. Slots are
125 normal C++ functions and can be called normally; their only special
126 feature is that signals can be connected to them.
128 Since slots are normal member functions, they follow the normal C++
129 rules when called directly. However, as slots, they can be invoked
130 by any component, regardless of its access level, via a signal-slot
131 connection. This means that a signal emitted from an instance of an
132 arbitrary class can cause a private slot to be invoked in an instance
133 of an unrelated class.
135 You can also define slots to be virtual, which we have found quite
138 Compared to callbacks, signals and slots are slightly slower
139 because of the increased flexibility they provide, although the
140 difference for real applications is insignificant. In general,
141 emitting a signal that is connected to some slots, is
142 approximately ten times slower than calling the receivers
143 directly, with non-virtual function calls. This is the overhead
144 required to locate the connection object, to safely iterate over
145 all connections (i.e. checking that subsequent receivers have not
146 been destroyed during the emission), and to marshall any
147 parameters in a generic fashion. While ten non-virtual function
148 calls may sound like a lot, it's much less overhead than any \c
149 new or \c delete operation, for example. As soon as you perform a
150 string, vector or list operation that behind the scene requires
151 \c new or \c delete, the signals and slots overhead is only
152 responsible for a very small proportion of the complete function
153 call costs. The same is true whenever you do a system call in a slot;
154 or indirectly call more than ten functions.
155 The simplicity and flexibility of the signals and slots mechanism is
156 well worth the overhead, which your users won't even notice.
158 Note that other libraries that define variables called \c signals
159 or \c slots may cause compiler warnings and errors when compiled
160 alongside a Qt-based application. To solve this problem, \c
161 #undef the offending preprocessor symbol.
164 \section1 A Small Example
166 A minimal C++ class declaration might read:
168 \snippet signalsandslots/signalsandslots.h 0
170 A small QObject-based class might read:
172 \snippet signalsandslots/signalsandslots.h 1
174 \snippet signalsandslots/signalsandslots.h 2
175 \snippet signalsandslots/signalsandslots.h 3
177 The QObject-based version has the same internal state, and provides
178 public methods to access the state, but in addition it has support
179 for component programming using signals and slots. This class can
180 tell the outside world that its state has changed by emitting a
181 signal, \c{valueChanged()}, and it has a slot which other objects
184 All classes that contain signals or slots must mention
185 Q_OBJECT at the top of their declaration. They must also derive
186 (directly or indirectly) from QObject.
188 Slots are implemented by the application programmer.
189 Here is a possible implementation of the \c{Counter::setValue()}
192 \snippet signalsandslots/signalsandslots.cpp 0
194 The \c{emit} line emits the signal \c valueChanged() from the
195 object, with the new value as argument.
197 In the following code snippet, we create two \c Counter objects
198 and connect the first object's \c valueChanged() signal to the
199 second object's \c setValue() slot using QObject::connect():
201 \snippet signalsandslots/signalsandslots.cpp 1
202 \snippet signalsandslots/signalsandslots.cpp 2
204 \snippet signalsandslots/signalsandslots.cpp 3
205 \snippet signalsandslots/signalsandslots.cpp 4
207 Calling \c{a.setValue(12)} makes \c{a} emit a
208 \c{valueChanged(12)} signal, which \c{b} will receive in its
209 \c{setValue()} slot, i.e. \c{b.setValue(12)} is called. Then
210 \c{b} emits the same \c{valueChanged()} signal, but since no slot
211 has been connected to \c{b}'s \c{valueChanged()} signal, the
214 Note that the \c{setValue()} function sets the value and emits
215 the signal only if \c{value != m_value}. This prevents infinite
216 looping in the case of cyclic connections (e.g., if
217 \c{b.valueChanged()} were connected to \c{a.setValue()}).
219 By default, for every connection you make, a signal is emitted;
220 two signals are emitted for duplicate connections. You can break
221 all of these connections with a single \l{QObject::disconnect()}{disconnect()} call.
222 If you pass the Qt::UniqueConnection \a type, the connection will only
223 be made if it is not a duplicate. If there is already a duplicate
224 (exact same signal to the exact same slot on the same objects),
225 the connection will fail and connect will return \c false.
227 This example illustrates that objects can work together without needing to
228 know any information about each other. To enable this, the objects only
229 need to be connected together, and this can be achieved with some simple
230 QObject::connect() function calls, or with \l{User Interface Compiler
231 (uic)}{uic}'s \l{Automatic Connections}{automatic connections} feature.
234 \section1 A Real Example
236 The following is an example of the header of a simple widget class without
237 member functions. The purpose is to show how you can utilize signals and
238 slots in your own applications.
240 \snippet signalsandslots/lcdnumber.h 0
241 \snippet signalsandslots/lcdnumber.h 1
243 \snippet signalsandslots/lcdnumber.h 2
245 \snippet signalsandslots/lcdnumber.h 3
246 \snippet signalsandslots/lcdnumber.h 4
247 \snippet signalsandslots/lcdnumber.h 5
249 \c LcdNumber inherits QObject, which has most of the signal-slot
250 knowledge, via QFrame and QWidget. It is somewhat similar to the
251 built-in QLCDNumber widget.
253 The Q_OBJECT macro is expanded by the preprocessor to declare
254 several member functions that are implemented by the \c{moc}; if
255 you get compiler errors along the lines of "undefined reference
256 to vtable for \c{LcdNumber}", you have probably forgotten to
257 \l{moc}{run the moc} or to include the moc output in the link
260 \snippet signalsandslots/lcdnumber.h 6
261 \snippet signalsandslots/lcdnumber.h 7
263 \snippet signalsandslots/lcdnumber.h 8
264 \snippet signalsandslots/lcdnumber.h 9
266 After the class constructor and \c public members, we declare the class
267 \c signals. The \c LcdNumber class emits a signal, \c overflow(), when it
268 is asked to show an impossible value.
270 If you don't care about overflow, or you know that overflow
271 cannot occur, you can ignore the \c overflow() signal, i.e. don't
272 connect it to any slot.
274 If on the other hand you want to call two different error
275 functions when the number overflows, simply connect the signal to
276 two different slots. Qt will call both (in the order they were connected).
278 \snippet signalsandslots/lcdnumber.h 10
279 \snippet signalsandslots/lcdnumber.h 11
280 \snippet signalsandslots/lcdnumber.h 12
282 \snippet signalsandslots/lcdnumber.h 13
284 A slot is a receiving function used to get information about
285 state changes in other widgets. \c LcdNumber uses it, as the code
286 above indicates, to set the displayed number. Since \c{display()}
287 is part of the class's interface with the rest of the program,
290 Several of the example programs connect the
291 \l{QScrollBar::valueChanged()}{valueChanged()} signal of a
292 QScrollBar to the \c display() slot, so the LCD number
293 continuously shows the value of the scroll bar.
295 Note that \c display() is overloaded; Qt will select the
296 appropriate version when you connect a signal to the slot. With
297 callbacks, you'd have to find five different names and keep track
298 of the types yourself.
300 \sa QLCDNumber, QObject::connect()
302 \section1 Signals And Slots With Default Arguments
304 The signatures of signals and slots may contain arguments, and the
305 arguments can have default values. Consider QObject::destroyed():
308 void destroyed(QObject* = nullptr);
311 When a QObject is deleted, it emits this QObject::destroyed()
312 signal. We want to catch this signal, wherever we might have a
313 dangling reference to the deleted QObject, so we can clean it up.
314 A suitable slot signature might be:
317 void objectDestroyed(QObject* obj = nullptr);
320 To connect the signal to the slot, we use QObject::connect().
321 There are several ways to connect signal and slots. The first is to use
324 connect(sender, &QObject::destroyed, this, &MyObject::objectDestroyed);
327 There are several advantages to using QObject::connect() with function pointers.
328 First, it allows the compiler to check that the signal's arguments are
329 compatible with the slot's arguments. Arguments can also be implicitly
330 converted by the compiler, if needed.
332 You can also connect to functors or C++11 lambdas:
335 connect(sender, &QObject::destroyed, this, [=](){ this->m_objects.remove(sender); });
338 In both these cases, we provide \a this as context in the call to connect().
339 The context object provides information about in which thread the receiver
340 should be executed. This is important, as providing the context ensures
341 that the receiver is executed in the context thread.
343 The lambda will be disconnected when the sender or context is destroyed.
344 You should take care that any objects used inside the functor are still
345 alive when the signal is emitted.
347 The other way to connect a signal to a slot is to use QObject::connect()
348 and the \c{SIGNAL} and \c{SLOT} macros.
349 The rule about whether to include arguments or not in the \c{SIGNAL()} and
350 \c{SLOT()} macros, if the arguments have default values, is that the
351 signature passed to the \c{SIGNAL()} macro must \e not have fewer arguments
352 than the signature passed to the \c{SLOT()} macro.
354 All of these would work:
356 connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed(Qbject*)));
357 connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed()));
358 connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed()));
360 But this one won't work:
362 connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed(QObject*)));
365 ...because the slot will be expecting a QObject that the signal
366 will not send. This connection will report a runtime error.
368 Note that signal and slot arguments are not checked by the compiler when
369 using this QObject::connect() overload.
371 \section1 Advanced Signals and Slots Usage
373 For cases where you may require information on the sender of the
374 signal, Qt provides the QObject::sender() function, which returns
375 a pointer to the object that sent the signal.
377 Lambda expressions are a convenient way to pass custom arguments to a slot:
380 connect(action, &QAction::triggered, engine,
381 [=]() { engine->processAction(action->text()); });
384 \sa {Meta-Object System}, {Qt's Property System}
386 \target 3rd Party Signals and Slots
387 \section2 Using Qt with 3rd Party Signals and Slots
389 It is possible to use Qt with a 3rd party signal/slot mechanism.
390 You can even use both mechanisms in the same project. To do that,
391 write the following into your CMake project file:
393 \snippet code/doc_src_containers.cpp cmake_no_keywords
395 In a qmake project (.pro) file, you need to write:
397 \snippet code/doc_src_containers.cpp 22
399 It tells Qt not to define the moc keywords \c{signals}, \c{slots},
400 and \c{emit}, because these names will be used by a 3rd party
401 library, e.g. Boost. Then to continue using Qt signals and slots
402 with the \c{no_keywords} flag, simply replace all uses of the Qt
403 moc keywords in your sources with the corresponding Qt macros
404 Q_SIGNALS (or Q_SIGNAL), Q_SLOTS (or Q_SLOT), and Q_EMIT.
406 \section2 Signals and slots in Qt-based libraries
408 The public API of Qt-based libraries should use the keywords
409 \c{Q_SIGNALS} and \c{Q_SLOTS} instead of \c{signals} and
410 \c{slots}. Otherwise it is hard to use such a library in a project
411 that defines \c{QT_NO_KEYWORDS}.
413 To enforce this restriction, the library creator may set the
414 preprocessor define \c{QT_NO_SIGNALS_SLOTS_KEYWORDS} when building
417 This define excludes signals and slots without affecting whether
418 other Qt-specific keywords can be used in the library
1.9.7