Qt Python Signal Slot

 
  1. Qt Python Signal Slot Machine
  2. Qt Designer Python Signal Slot

I have a number of different signals connected to one slot. Is there any disconnect function that can be used to disconnect everything connected to a specific slot? For example: @QObject::connect(object1, SIGNAL(a), receiver, SLOT(slot)); QObject::con. Each PyQt widget, which is derived from QObject class, is designed to emit ‘ signal ’ in response to one or more events. The signal on its own does not perform any action. Instead, it is ‘connected’ to a ‘ slot ’. The slot can be any callable Python function. Widget.signal.connect (slot) Which means that whenever a signal is triggered by a widget, the connected slot function will be executed. In summary, signals and slots are used by Qt to communicate between objects and facilitate component reusability and interactivity.

This blog is part of a series of blogs explaining the internals of signals and slots.

In this article, we will explore the mechanisms powering the Qt queued connections.

Summary from Part 1

In the first part, we saw that signalsare just simple functions, whose body is generated by moc. They are just calling QMetaObject::activate, with an array of pointers to arguments on the stack.Here is the code of a signal, as generated by moc: (from part 1)

QMetaObject::activatewill then look in internal data structures to find out what are the slots connected to that signal.As seen in part 1, for each slot, the following code will be executed:

So in this blog post we will see what exactly happens in queued_activateand other parts that were skipped for the BlockingQueuedConnection

Qt Event Loop

A QueuedConnection will post an event to the event loop to eventually be handled.

When posting an event (in QCoreApplication::postEvent),the event will be pushed in a per-thread queue(QThreadData::postEventList).The event queued is protected by a mutex, so there is no race conditions when threadspush events to another thread's event queue.

Once the event has been added to the queue, and if the receiver is living in another thread,we notify the event dispatcher of that thread by calling QAbstractEventDispatcher::wakeUp.This will wake up the dispatcher if it was sleeping while waiting for more events.If the receiver is in the same thread, the event will be processed later, as the event loop iterates.

The event will be deleted right after being processed in the thread that processes it.

An event posted using a QueuedConnection is a QMetaCallEvent. When processed, that event will call the slot the same way we call them for direct connections.All the information (slot to call, parameter values, ...) are stored inside the event.

Slot

Copying the parameters

The argv coming from the signal is an array of pointers to the arguments. The problem is that these pointers point to the stack of the signal where the arguments are. Once the signal returns, they will not be valid anymore. So we'll have to copy the parameter values of the function on the heap. In order to do that, we just ask QMetaType. We have seen in the QMetaType article that QMetaType::create has the ability to copy any type knowing it's QMetaType ID and a pointer to the type.

To know the QMetaType ID of a particular parameter, we will look in the QMetaObject, which contains the name of all the types. We will then be able to look up the particular type in the QMetaType database.

queued_activate

We can now put it all together and read through the code ofqueued_activate, which is called by QMetaObject::activate to prepare a Qt::QueuedConnection slot call.The code showed here has been slightly simplified and commented:

Upon reception of this event, QObject::event will set the sender and call QMetaCallEvent::placeMetaCall. That later function will dispatch just the same way asQMetaObject::activate would do it for direct connections, as seen in Part 1

BlockingQueuedConnection

BlockingQueuedConnection is a mix between DirectConnection and QueuedConnection. Like with aDirectConnection, the arguments can stay on the stack since the stack is on the thread thatis blocked. No need to copy the arguments.Like with a QueuedConnection, an event is posted to the other thread's event loop. The event also containsa pointer to a QSemaphore. The thread that delivers the event will release thesemaphore right after the slot has been called. Meanwhile, the thread that called the signal will acquirethe semaphore in order to wait until the event is processed.

It is the destructor of QMetaCallEvent which will release the semaphore. This is good becausethe event will be deleted right after it is delivered (i.e. the slot has been called) but also whenthe event is not delivered (e.g. because the receiving object was deleted).

A BlockingQueuedConnection can be useful to do thread communication when you want to invoke afunction in another thread and wait for the answer before it is finished. However, it must be donewith care.

The dangers of BlockingQueuedConnection

You must be careful in order to avoid deadlocks.

Obviously, if you connect two objects using BlockingQueuedConnection living on the same thread,you will deadlock immediately. You are sending an event to the sender's own thread and then are locking thethread waiting for the event to be processed. Since the thread is blocked, the event will never beprocessed and the thread will be blocked forever. Qt detects this at run time and prints a warning,but does not attempt to fix the problem for you.It has been suggested that Qt could then just do a normal DirectConnection if both objects are inthe same thread. But we choose not to because BlockingQueuedConnection is something that can only beused if you know what you are doing: You must know from which thread to what other thread theevent will be sent.

The real danger is that you must keep your design such that if in your application, you do aBlockingQueuedConnection from thread A to thread B, thread B must never wait for thread A, or you willhave a deadlock again.

When emitting the signal or calling QMetaObject::invokeMethod(), you must not have any mutex lockedthat thread B might also try locking.

A problem will typically appear when you need to terminate a thread using a BlockingQueuedConnection, for example in thispseudo code:

You cannot just call wait here because the child thread might have already emitted, or is about to emitthe signal that will wait for the parent thread, which won't go back to its event loop. All the thread cleanup information transfer must only happen withevents posted between threads, without using wait(). A better way to do it would be:

The downside is that MyOperation::cleanup() is now called asynchronously, which may complicate the design.

Conclusion

This article should conclude the series. I hope these articles have demystified signals and slots,and that knowing a bit how this works under the hood will help you make better use of them in yourapplications.

This section describes the new style of connecting signals and slotsintroduced in PyQt4 v4.5.

One of the key features of Qt is its use of signals and slots to communicatebetween objects. Their use encourages the development of reusable components.

A signal is emitted when something of potential interest happens. A slot is aPython callable. If a signal is connected to a slot then the slot is calledwhen the signal is emitted. If a signal isn’t connected then nothing happens.The code (or component) that emits the signal does not know or care if thesignal is being used.

The signal/slot mechanism has the following features.

  • A signal may be connected to many slots.
  • A signal may also be connected to another signal.
  • Signal arguments may be any Python type.
  • A slot may be connected to many signals.
  • Connections may be direct (ie. synchronous) or queued (ie. asynchronous).
  • Connections may be made across threads.
  • Signals may be disconnected.

Qt Python Signal Slot Machine

Unbound and Bound Signals¶

A signal (specifically an unbound signal) is an attribute of a class that is asub-class of QObject. When a signal is referenced as an attribute of aninstance of the class then PyQt4 automatically binds the instance to the signalin order to create a bound signal. This is the same mechanism that Pythonitself uses to create bound methods from class functions.

A bound signal has connect(), disconnect() and emit() methods thatimplement the associated functionality. It also has a signal attributethat is the signature of the signal that would be returned by Qt’s SIGNAL()macro.

A signal may be overloaded, ie. a signal with a particular name may supportmore than one signature. A signal may be indexed with a signature in order toselect the one required. A signature is a sequence of types. A type is eithera Python type object or a string that is the name of a C++ type. The name of aC++ type is automatically normalised so that, for example, QString can beused instead of the non-normalised constQString&.

If a signal is overloaded then it will have a default that will be used if noindex is given.

Qt Designer Python Signal Slot

When a signal is emitted then any arguments are converted to C++ types ifpossible. If an argument doesn’t have a corresponding C++ type then it iswrapped in a special C++ type that allows it to be passed around Qt’s meta-typesystem while ensuring that its reference count is properly maintained.

Defining New Signals with pyqtSignal()

PyQt4 automatically defines signals for all Qt’s built-in signals. New signalscan be defined as class attributes using the pyqtSignal()factory.

PyQt4.QtCore.pyqtSignal(types[, name])

Create one or more overloaded unbound signals as a class attribute.

Parameters:
  • types – the types that define the C++ signature of the signal. Each type maybe a Python type object or a string that is the name of a C++ type.Alternatively each may be a sequence of type arguments. In this caseeach sequence defines the signature of a different signal overload.The first overload will be the default.
  • name – the name of the signal. If it is omitted then the name of the classattribute is used. This may only be given as a keyword argument.
Return type:

an unbound signal

The following example shows the definition of a number of new signals:

New signals should only be defined in sub-classes of QObject. They must bepart of the class definition and cannot be dynamically added as classattributes after the class has been defined.

New signals defined in this way will be automatically added to the class’sQMetaObject. This means that they will appear in Qt Designer and can beintrospected using the QMetaObject API.

Overloaded signals should be used with care when an argument has a Python typethat has no corresponding C++ type. PyQt4 uses the same internal C++ class torepresent such objects and so it is possible to have overloaded signals withdifferent Python signatures that are implemented with identical C++ signatureswith unexpected results. The following is an example of this:

Connecting, Disconnecting and Emitting Signals¶

Signals are connected to slots using the connect() method of a boundsignal.

connect(slot[, type=PyQt4.QtCore.Qt.AutoConnection[, no_receiver_check=False]])

Connect a signal to a slot. An exception will be raised if the connectionfailed.

Parameters:
  • slot – the slot to connect to, either a Python callable or another boundsignal.
  • type – the type of the connection to make.
  • no_receiver_check – suppress the check that the underlying C++ receiver instance stillexists and deliver the signal anyway.

Signals are disconnected from slots using the disconnect() method of abound signal.

disconnect([slot])
Python

Disconnect one or more slots from a signal. An exception will be raised ifthe slot is not connected to the signal or if the signal has no connectionsat all.

Parameters:slot – the optional slot to disconnect from, either a Python callable oranother bound signal. If it is omitted then all slots connected to thesignal are disconnected.

Signals are emitted from using the emit() method of a bound signal.

emit(*args)

Emit a signal.

Parameters:args – the optional sequence of arguments to pass to any connected slots.

The following code demonstrates the definition, connection and emit of asignal without arguments:

The following code demonstrates the connection of overloaded signals:

Connecting Signals Using Keyword Arguments¶

It is also possible to connect signals by passing a slot as a keyword argumentcorresponding to the name of the signal when creating an object, or using thepyqtConfigure() method of QObject. For example the following threefragments are equivalent:

The pyqtSlot() Decorator¶

Although PyQt4 allows any Python callable to be used as a slot when connectingsignals, it is sometimes necessary to explicitly mark a Python method as beinga Qt slot and to provide a C++ signature for it. PyQt4 provides thepyqtSlot() function decorator to do this.

PyQt4.QtCore.pyqtSlot(types[, name[, result]])

Decorate a Python method to create a Qt slot.

Parameters:
  • types – the types that define the C++ signature of the slot. Each type may bea Python type object or a string that is the name of a C++ type.
  • name – the name of the slot that will be seen by C++. If omitted the name ofthe Python method being decorated will be used. This may only be givenas a keyword argument.
  • result – the type of the result and may be a Python type object or a string thatspecifies a C++ type. This may only be given as a keyword argument.

Connecting a signal to a decorated Python method also has the advantage ofreducing the amount of memory used and is slightly faster.

For example:

It is also possible to chain the decorators in order to define a Python methodseveral times with different signatures. For example:

Connecting Slots By Name¶

PyQt4 supports the QtCore.QMetaObject.connectSlotsByName() function thatis most commonly used by pyuic4 generated Python code toautomatically connect signals to slots that conform to a simple namingconvention. However, where a class has overloaded Qt signals (ie. with thesame name but with different arguments) PyQt4 needs additional information inorder to automatically connect the correct signal.

For example the QtGui.QSpinBox class has the following signals:

When the value of the spin box changes both of these signals will be emitted.If you have implemented a slot called on_spinbox_valueChanged (whichassumes that you have given the QSpinBox instance the name spinbox)then it will be connected to both variations of the signal. Therefore, whenthe user changes the value, your slot will be called twice - once with aninteger argument, and once with a unicode or QString argument.

This also happens with signals that take optional arguments. Qt implementsthis using multiple signals. For example, QtGui.QAbstractButton has thefollowing signal:

Qt implements this as the following:

The pyqtSlot() decorator can be used to specify which ofthe signals should be connected to the slot.

For example, if you were only interested in the integer variant of the signalthen your slot definition would look like the following:

If you wanted to handle both variants of the signal, but with different Pythonmethods, then your slot definitions might look like the following:

The following shows an example using a button when you are not interested inthe optional argument:

Mixing New-style and Old-style Connections¶

The implementation of new-style connections is slightly different to theimplementation of old-style connections. An application can freely use bothstyles subject to the restriction that any individual new-style connectionshould only be disconnected using the new style. Similarly any individualold-style connection should only be disconnected using the old style.

You should also be aware that pyuic4 generates code that usesold-style connections.