Eli Bendersky's website - Qt

Passing extra arguments to Qt slots

2011-07-09T10:45:11-07:00

A few months ago I wrote about passing extra arguments to slots in PyQt. Here, I want to briefly discuss how the same effect can be achieved with Qt itself.

C++ is not as dynamic as Python, so Python's approaches of using lambda or functools.partial won't work [1]. Fortunately, the Qt folks provided a solution that can make passing extra arguments to slots relatively simple. This is the QSignalMapper class.

I'll just show a partial code sample. Suppose we have two different QAction objects, and we want to connect both to the slot:

void onAction(const QString& what);

Further, we want each action to pass a different argument to onAction. Here's the relevant connections using QSignalMapper:

// #1
m_sigmapper = new QSignalMapper(this);

// #2
connect(m_action_file_new, SIGNAL(triggered()),
        m_sigmapper, SLOT(map()));
connect(m_action_file_open, SIGNAL(triggered()),
        m_sigmapper, SLOT(map()));

// #3
m_sigmapper->setMapping(m_action_file_new, "File->New");
m_sigmapper->setMapping(m_action_file_open, "File->Open");

// #4
connect(m_sigmapper, SIGNAL(mapped(QString)),
        this, SLOT(onAction(const QString&)));

There are four distinct steps here:

Create a new QSignalMapper object.
Connect the triggered slots of the actions to the mapper's map slot.
Let the mapper know via setMapping which action should pass which extra argument.
Finally, connect the mapper's mapped(QString) signal to onAction.

This is it. Now, when m_action_file_new is triggered, onAction will be called with the argument "File->New", and so on.

Internally, QSignalMapper is quite simple. It contains a hash table mapping the sender QObject* to the argument (filled in setMapping). When its map slot is invoked, it looks up the sender in the hash and fires mapped with the appropriate argument.

There are some limitations to QSignalMapper - for example, you can't map arguments with arbitrary type [2], or map multiple arguments. The only mappings supported are:

void setMapping(QObject *sender, int id);
void setMapping(QObject *sender, const QString &text);
void setMapping(QObject *sender, QWidget *widget);
void setMapping(QObject *sender, QObject *object);

So if you need to pass some complex information to a slot, create a class derived from QObject and use that.

[1]	Well, C++ does have some high-level constructs like `boost::bind` and the new C++0x standard support for lambdas, but I don't believe either approach is formally supported by Qt's `connect` methods yet.

[2]	Though I guess Qt could have implemented this with templates.

DLL hell problems with Qt Creator

2011-07-08T06:06:19-07:00

Yesterday I installed the latest version of the Qt SDK on my home machine (selecting only the desktop version for MinGW in the installation). Then I opened Qt Creator, selected one of the bundled example projects, built it and...

And then I got this error:

Starting D:\QtSDK\...\debug\mandelbrot.exe...
D:\QtSDK\...\debug\mandelbrot.exe exited with code -1073741511

Well, -1073741511 is just an obscene way of saying 0xC0000139, which on Windows means that some function wasn't found in a DLL. So this is Windows DLL hell (who would've thought...).

Naturally, I first suspected that Qt Creator is the culprit here. This is because when I went to directory this executable was created in and copied the relevant DLLs into it, it worked. So I started digging around the project settings in Qt Creator, but it appeared that it set up the PATH correctly to point to the installed Qt and MinGW runtime DLLs. Furthermore, it was properly appending to the beginning of PATH, so other versions of Qt potentially installed elsewhere couldn't affect it. Or could they?

The DLL search order on Windows, whichever way it is configured, always looks in the system and windows directories before it looks at the dirs on PATH. Indeed, when I went to c:\WINDOWS\system32, I was surprised (and delighted) to find a few stray Qt DLLs in there. Deleting them solved the problem!

The morale of the story: always think about the "DLL search order" when debugging problems like this. Dependency walker can help greatly here too. If your executable finds a DLL somewhere you wouldn't expect it to, depends will tell you about it.

P.S. How did the debug DLLs of Qt get into my system32? Either some application put them there during installation (a bad, bad thing to do), or I put them there for some obscure testing purpose a while ago and forgot all about them. Therefore, another morale of the story: never, EVER, put stuff in system32. Just distribute your DLLs in the same directory with the executable. Modern hard-drives are large enough to make the storage savings of DLL sharing negligible.

Code sample - socket client based on Twisted with PyQt

2011-05-26T05:28:59-07:00

In an earlier post, I discussed one way of combining blocking socket I/O with a GUI, by means of a separate thread in which the I/O runs. I've also mentioned that one alternative is using asynchronous I/O with callbacks integrated into the GUI event loop. Here I want to present some sample code for this alternative.

One of the first things Python programmers will think about then considering asynchronous I/O is Twisted, which is an event-driven networking library written in pure Python. Twisted is a huge library, and it's quite a job to learn how to use it properly. Here I'll demonstrate just enough to accomplish the task at hand - re-create the simple socket client from the previous post that works as part of a PyQt GUI.

The full code sample is available for download - socket_client_twisted_pyqt. Here is the socket client class using Twisted:

import struct

from twisted.internet.protocol import Protocol, ClientFactory
from twisted.protocols.basic import IntNStringReceiver


class SocketClientProtocol(IntNStringReceiver):
    """ The protocol is based on twisted.protocols.basic
        IntNStringReceiver, with little-endian 32-bit
        length prefix.
    """
    structFormat = "<L"
    prefixLength = struct.calcsize(structFormat)

    def stringReceived(self, s):
        self.factory.got_msg(s)

    def connectionMade(self):
        self.factory.clientReady(self)


class SocketClientFactory(ClientFactory):
    """ Created with callbacks for connection and receiving.
        send_msg can be used to send messages when connected.
    """
    protocol = SocketClientProtocol

    def __init__(
            self,
            connect_success_callback,
            connect_fail_callback,
            recv_callback):
        self.connect_success_callback = connect_success_callback
        self.connect_fail_callback = connect_fail_callback
        self.recv_callback = recv_callback
        self.client = None

    def clientConnectionFailed(self, connector, reason):
        self.connect_fail_callback(reason)

    def clientReady(self, client):
        self.client = client
        self.connect_success_callback()

    def got_msg(self, msg):
        self.recv_callback(msg)

    def send_msg(self, msg):
        if self.client:
            self.client.sendString(msg)

A couple of notes:

Since I want to re-create the same length-prefixed protocol from the previous post, the IntNStringReceiver protocol class from twisted.protocols.basic comes in handy - it's designed especially for strings prefixed by integer length headers. In our case, the prefix is a 4-byte little-endian unsigned integer, which I specify with the structFormat and prefixLength attributes. In addition I implement a couple of callbacks of the IProtocol interface.
SocketClientFactory is a straightforward subclass of Twisted's ClientFactory, implementing the callbacks we're interested in here.

This is all quite simple. The bigger problem was finding how to interface Twisted with PyQt. Since Twisted and a typical GUI library are both event-loop based, to make them work together we should use a custom reactor. Unfortunately, due to licensing issues, Twisted doesn't come with a reactor for PyQt pre-packaged, and it should be obtained separately. Even more unfortunately, the PyQt reactor (qt4reactor.py) doesn't appear to have a single well-defined address on the web - several slightly different versions of it can be found floating online. In my code sample I've included a version of qt4reactor.py which I found to work for my needs.

So, back to the code. This is the implementation of the PyQt client GUI that uses Twisted. Similarly to the thread-based sample, it keeps drawing a nice circle animation to demonstrate it's never blocked. The full code is in the zip archive, here is only the interesting part:

class SampleGUIClientWindow(QMainWindow):
    def __init__(self, reactor, parent=None):
        super(SampleGUIClientWindow, self).__init__(parent)
        self.reactor = reactor

        self.create_main_frame()
        self.create_client()
        self.create_timer()

    def create_main_frame(self):
        self.circle_widget = CircleWidget()
        self.doit_button = QPushButton('Do it!')
        self.doit_button.clicked.connect(self.on_doit)
        self.log_widget = LogWidget()

        hbox = QHBoxLayout()
        hbox.addWidget(self.circle_widget)
        hbox.addWidget(self.doit_button)
        hbox.addWidget(self.log_widget)

        main_frame = QWidget()
        main_frame.setLayout(hbox)

        self.setCentralWidget(main_frame)

    def create_timer(self):
        self.circle_timer = QTimer(self)
        self.circle_timer.timeout.connect(self.circle_widget.next)
        self.circle_timer.start(25)

    def create_client(self):
        self.client = SocketClientFactory(
                        self.on_client_connect_success,
                        self.on_client_connect_fail,
                        self.on_client_receive)

    def on_doit(self):
        self.log('Connecting...')
        # When the connection is made, self.client calls the on_client_connect
        # callback.
        #
        self.connection = self.reactor.connectTCP(SERVER_HOST, SERVER_PORT, self.client)

    def on_client_connect_success(self):
        self.log('Connected to server. Sending...')
        self.client.send_msg('hello')

    def on_client_connect_fail(self, reason):
        # reason is a twisted.python.failure.Failure  object
        self.log('Connection failed: %s' % reason.getErrorMessage())

    def on_client_receive(self, msg):
        self.log('Client reply: %s' % msg)
        self.log('Disconnecting...')
        self.connection.disconnect()

    def log(self, msg):
        timestamp = '[%010.3f]' % time.clock()
        self.log_widget.append(timestamp + ' ' + str(msg))

    def closeEvent(self, e):
        self.reactor.stop()


#-------------------------------------------------------------------------------
if __name__ == "__main__":
    app = QApplication(sys.argv)

    try:
        import qt4reactor
    except ImportError:
        # Maybe qt4reactor is placed inside twisted.internet in site-packages?
        from twisted.internet import qt4reactor
    qt4reactor.install()

    from twisted.internet import reactor
    mainwindow = SampleGUIClientWindow(reactor)
    mainwindow.show()

    reactor.run()

The most important part of this code is in the last section, where the Twisted reactor and PyQt application are set up. A few steps have to be performed in a careful order:

An QApplication is created
qt4reactor is imported and installed into Twisted
The main window is created
Finally, the singleton Twisted reactor (which is actually a qt4reactor, since that's the one we've installed) is run

Note that there's no app.exec_() here, contrary to what you'd expect from a PyQt program. Since both PyQt and Twisted are based on event loops (in app.exec_() and reactor.run(), respectively), one of them should drive the other. The Twisted way is to let the reactor drive (hence we only call reactor.run() here). Inside its implementation, qt4reactor takes care of running an event loop in a way that dispatches events to both Twisted and PyQt.

Some additional notes:

The PyQt main window no longer needs a timer to query results from the client thread. When SocketClientFactory is created in create_client, some methods are passed to it as callbacks. These callbacks will be invoked when interesting events happen.
Even though Twisted's reactor is a global singleton object, it's good practice to pass it around in the application, instead of importing it from Twisted in multiple places. Here, SampleGUIClientWindow accepts the reactor object in its constructor and uses it later.
Twisted's reactor keeps running until explicitly stopped. The user of a GUI expects the program to exit then the GUI is closed, so I call reactor.stop() in the main window's closeEvent.

This is it. Once set up, Twisted integrates quite nicely with PyQt. Since both the GUI framework and Twisted are based on the concept of an event loop with callbacks, this is a natural symbiosis.

A final note: I'm very far from being a Twisted expert. In fact, this is the first time I really use it, so may be doing things not in the most idiomatic or optimal way. If you can recommend a better way to implement some parts of this sample, I'll be very happy to hear about it.

Passing extra arguments to PyQt slots

2011-04-25T13:38:41-07:00

A frequent question coming up when programming with PyQt is how to pass extra arguments to slots. After all, the signal-slot connection mechanism only specifies how to connect a signal to a slot - the signal's arguments are passed to the slot, but no additional (user-defined) arguments may be directly passed.

But passing extra arguments can be quite useful. You can have a single slot handling signals from multiple widgets, and sometimes you need to pass extra information.

One way to do this is using lambda. Here's a complete code sample:

from PyQt4.QtCore import *
from PyQt4.QtGui import *

class MyForm(QMainWindow):
    def __init__(self, parent=None):
        super(MyForm, self).__init__(parent)
        button1 = QPushButton('Button 1')
        button2 = QPushButton('Button 1')
        button1.clicked.connect(lambda: self.on_button(1))
        button2.clicked.connect(lambda: self.on_button(2))

        layout = QHBoxLayout()
        layout.addWidget(button1)
        layout.addWidget(button2)

        main_frame = QWidget()
        main_frame.setLayout(layout)

        self.setCentralWidget(main_frame)

    def on_button(self, n):
        print('Button {0} clicked'.format(n))

if __name__ == "__main__":
    import sys
    app = QApplication(sys.argv)
    form = MyForm()
    form.show()
    app.exec_()

Note how the on_button slot is used to handle signals from both buttons. Here we use lambda to pass the button number to the slot, but anything can be passed - even the button widget itself (suppose the slot wants to deactivate the button that sent the signal).

There's an alternative to lambda - using functools.partial. We can replace the connection lines with:

button1.clicked.connect(partial(self.on_button, 1))
button2.clicked.connect(partial(self.on_button, 2))

Which method is better? It's really a matter of style. Personally, I prefer the lambda because it's more explicit and flexible.

New-style signal-slot connection mechanism in PyQt

2011-04-24T18:49:42-07:00

In most of the PyQt code samples you find online and in books (including, I confess, my examples and blog posts) the "old-style" signal-slot connection mechanism is used. For example, here's a basic push-button window:

from PyQt4.QtCore import *
from PyQt4.QtGui import *

class MyForm(QMainWindow):
    def __init__(self, parent=None):
        super(MyForm, self).__init__(parent)
        the_button = QPushButton('Hello')
        self.connect(the_button, SIGNAL('clicked()'), self.on_hello)
        self.setCentralWidget(the_button)

    def on_hello(self):
        print('hello!!')

if __name__ == "__main__":
    import sys
    app = QApplication(sys.argv)
    form = MyForm()
    form.show()
    app.exec_()

The relevant code is:

self.connect(the_button, SIGNAL('clicked()'), self.on_hello)

Apart from being verbose and un-Pythonic, this syntax has a serious problem. You must type in the C++ signature of the signal exactly. Otherwise, the signal just won't fire, without an exception or any warning. This is a very common mistake. If you think that clicked() is a simple enough signature to write, how about these ones (taken from real code):

SIGNAL("currentRowChanged(QModelIndex,QModelIndex)")
SIGNAL('marginClicked(int, int, Qt::KeyboardModifiers)')

The "new-style" signal-slot connection mechanism is much better. Here's how the button click connection is done:

the_button.clicked.connect(self.on_hello)

This mechanism is supported by PyQt since version 4.5, and provides a safer and much more convenient way to connect signals and slots. Each signal is now an attribute that gets automatically bound once you access it. It has a connect method that simply accepts the slot as a Python callable. No more C++ signatures, yay!

PyQt 4.5 was released almost 2 years ago - it's time to switch to the new mechanism.