Envision you've decided to go solo and start an indie game studio to fulfil your lifelong dream - to design and create a turn-based strategy game. You begin your endeavour by outlining the different components and sketch on the overall architecture of the game. The game will have some units which can be moved and controlled by using the mouse. There will be an AI component which will perhaps kick in after the units have completed their movements. The AI will then decide how the enemies should respond.

QObject::connect(serial, SIGNAL(readyRead), SLOT(readcallback)); Source compiles fine, the application runs, I can select my serial port and connect to it. However, the callbacks don't get called at all. I deduced that the signal/slot mechanism isn't set up correctly. Looking into the class source I find the 'old' syntax for connect.

In other words, a sequence of actions need to happen: the mouse click, then the movement of units and then the response of the enemies. However, you probably don't want the mouse logic to directly depend on the unit-classes; it will be used for much more. For the same reason the unit-classes shouldn't need to rely on the AI nor the enemy logic; possibly the same AI will be used for many different enemies. I'm sure you're a great developer so you're aiming to decouple these different components. Nonetheless, the components need to communicate with each other and you need some kind of callback-mechanism. And this, ladies and gentlemen, this is where Qt's signals and slots comes to the rescue.

This is the third post in the series 'Crash course in Qt for C++ developers' covering the signals and slots mechanism. The other topics are listed below.

• In the function FunctionPointer::call, the args0 is meant to receive the return value of the slot. If the signal returns a value, it is a pointer to an object of the return type of the signal, else, it is 0. If the slot returns a value, we need to copy it in arg0. If it returns void, we do nothing.
• A developer can choose to connect to a signal by creating a function (a 'slot') and calling the connect function to relate the signal to the slot. Qt's signals and slots mechanism does not require classes to have knowledge of each other, which makes it much easier to develop highly reusable classes.
• QObject::connect(serial, SIGNAL(readyRead), SLOT(readcallback)); Source compiles fine, the application runs, I can select my serial port and connect to it. However, the callbacks don't get called at all. I deduced that the signal/slot mechanism isn't set up correctly. Looking into the class source I find the 'old' syntax for connect.

Qt Connect Slot

1. Signals and slots - communication between objects
2. Qt Quick/QML example
3. Qt Widgets example
4. Tooling, e.g. Qt Creator
5. Remaining good-to-know topics
6. Where to go from here?

The most common usage of the signals and slots mechanism is for inter-object communication and has been around since the birth of Qt. It's a system where an object broadcasts a signal with data and any listeners, including the sender itself, can subscribe to that signal. The listeners then redirect the data to a member function, or what's so called the slot, where it's then processed.

You might wonder how this system is different from using a standard callback-mechanism used in many other GUI tools. One benefit of Qt's solution is that the sender is not dependent on the listener, it's just firing off the signal. In a callback mechanism the sender usually needs to know which listeners to notify. Another benefit, in contrast to many other callback implementations, is that the signals and slots functions are type safe.

OK - enough text, let's look at some code.

The basics

Signals

Let's start with signals. In order to enable signals for a class, it has to inherit from QObject and use the Q_OBJECT macro. We'll define a signal called signalName with three arguments. The arguments are used to pass in data, which will later be available in the slots.

The signals keyword is essentially a simple macro defined to public but is also used by the MOC (remember from the previous post?) to generate the implementation of the member function signalName(). The implementation can be found in the generated file moc_mysender.cpp. The signal is declared similarly to a regular function, except for a constraint on the return value - it has to be void. To emit the signal, we'll only call the function with the addition of appending emit, i.e.:

emit is a macro defined to do... nothing. It's only used for documentation and readability purposes. You could omit it: the code would compile fine and the outcome would be the same, but again, we want to be explicit that it's a signal. Also, notice that we don't need to depend on any of the listeners, we're only so far just emitting a signal. So how would an object listen to it?

Slots

A listener object will redirect the signal to one of its slots. However, slots are not limited to member functions but can also consist of lambdas, non-member functions and functors. The arguably most common use is to define the slot within an object, so let's start by creating a new class MyReceiver which has a slot called slotName():

Similarly to the signal object, the receiver class needs to inherit from QObject and also use the Q_OBJECT macro. Furthermore, slots is another macro declared to do nothing, but in contrast to emit it's used by the MOC to generate introspection code. Slots-function can be specified as public, protected and private; Signals are always public.

Did I mention that the system is type safe? The signal's and slot's signature must find a match in order to link them: the arguments must be of the same types and qualifiers and declared in the same order. So how do we connect our signal to our slot?

Connect

We'll use the static function QObject::connect():

QObject::connect() takes five arguments, the last one has a default value and will be ignored for now. From left to right:

• Start with the object which emits the signal - the sender.
• Next we have a pointer to a member function - the signal.
• Hook it up to the listener - the receiver.
• Last, we have another pointer to a member function - the slot.

Now, if we emit out signal, the slot will be notified and we get the following output:

Important data that will be sent to all listeners 42 1.618033

You may connect many different signals to the same slot, or use the same signal for many different slots. It's your choice - the system is very flexible. As mentioned, the system even allows to connect functions and lambdas directly, without using a listener, e.g:

The connection is automatically disconnected if either the sender or the receiver becomes deleted. However, as you might have guessed it's also possible to manually disconnect it by using disconnect:

Qt Connect Signal Slot Another Classic

Heads-up when capturing data in a lambda

Be extra careful when capturing data using lambdas or functors as only the sender will automatically control the lifetime of the connection. Consider the following case:

What if data has been deleted prior to emitting the signal? The connection might still be alive (if it hasn't been manually disconnected) and we'll have a naughty bug in our application. However, Qt provides another overload of the connect() function where it's possible to provide a context object. This is used like so:

Notice the third argument. We're now also providing the same captured object as a context object. If the context object is deleted, the connection will automatically disconnect. Note that the context object has to inherit from QObject for this to work.

We've now come to an end of the basics. There should be enough information here to cover the most common cases. But down the development road you might hit some issues and will need some additional information in the future. Perhaps the next section will help you at those times.

Tips and tricks

• In case you have multiple overloads of a signals or slots you'll need to perform a cast within the QObject::connect(), e.g.:

• Although it should be avoided, it's possible to delete a listener (or schedule it for deletion) within its slot by using deletelater().

• There are several different types of connections. The type is defined by the fifth argument in the connect()-function. The type is an enum called Qt::ConnectionType and is defaulted to Qt::AutoConnection. In a single threaded application, the default behaviour is for the signal to directly notify the listeners. However, in a multi threaded application, usually the connections between the threads are queued up on each respective event loop. Threads are outside the scope of this series but is very well documented by Qt.

• It's possible to connect a signal directly to another object's signal. This can be used, for example, to forward signals:

• You might find a different syntax that's used for the connect() function by other tutorials, blogs or even the Qt documentation, see code below. This style was the main syntax used up until Qt5. The syntax shown in this post provides several benefits over the old style. Personally, I believe the best advantage is that it allows compile-time checking of the signals and slots, which wasn't previously possible. However, in some cases the old syntax must be used, for example when connecting C++ functions to QML functions.

Qt5 Signals And Slots Syntax

• Do you remember the slots keyword above (when defining the slot-functions)? It's actually only necessary to define when using the old connect() syntax mentioned in the previous point. The type checking for the old syntax is done at run-time by using type introspection. The MOC generates the introspection code, but only if the slots keyword is defined.

• If you need to know which signals and slots are connected to a specific object at a certain point in time, you'll find QObject::dumpObjectInfo() very helpful. It's especially useful when debugging since it will output all the inbound and outbound signals for the object.

Qt Signal Slot Example

How Qt Signal And Slots Works

Back to the game architecture

You might now have a better understanding on how signals and slots can be used to separate the different game components. For example, let's say that we define four components which should be decoupled: the MouseComponent, the UnitComponent, the AIComponent and lastly the EnemyComponent. Furthermore, we'll use signals in each component to communicate and notify the other components. However to solve the separation, we'll have to introduce another component, the MainController, which will be used to create all the connections and define the game flow. The MainController will obviously need to depend on the different components, however the components are now well isolated from each other and we've achieved our goal. Do you see how this can be used in a GUI application to separate the visuals and user interaction from the actual logic?

Lastly, if you're interested in reading more about the inner-works of the signals and slots mechanism woboq.com has written a great blog series which has got you covered. Let me know if something is unclear or perhaps if I missed something out.

See you next time!

Qt Connect Signal Slot