This article is part 5 of 8 in the series Python PySide/PyQt Tutorial

Last Updated: Tuesday 9th December 2014

You don't have to rely solely on the signals that are provided by Qt widgets, however; you can create your own. Signals are created using the Signal class. A simple signal definition would be:

Then, when the conditions for the object being tapped are satisfied, you call the signal's emit method, and the signal is emitted, calling any slots to which it is connected:

This is good for two reasons; first, it allows users of your objects to interact with them in familiar ways; and second, it allows your objects to be used more flexibly, leaving the definition effects of actions on your object to the code that uses them.

A Simple PySide/PyQt Signal Emitting Example

Let's define a simple PunchingBag class that does only one thing: when its punch is called, it emits a punched signal:

You can easily see what we've done. The PunchingBag inherits from QObject so it can emit signals; it has a signal called punched, which carries no data; and it has a punch method which does nothing but emit the punched signal.

To make our PunchingBag useful, we need to connect its punched signal to a slot that does something. We'll define a simple one that prints, "Bag was punched" to the console, instantiate our PunchingBag, and connect its punched signal to the slot:

Then, we'll punch the bag and see what happens:

When you put it all in a script and run it, it will print:

Effective, but not particularly impressive. However, you can see the usefulness of it: our punching bag would be a good fit anywhere you need a bag that reacts to punching, because the PunchingBag leaves implementation of a reaction to punching to the code that uses it.

Data-Carrying PySide/PyQt Signals

One of the most interesting things you can do when creating signals is to make them carry data. For example, you could make a signal carry an integer, thus:

or a string:

The datatype may be any Python type name or a string identifying a C++ datatype. Since this tutorial presupposes no C++ knowledge, we'll stick to Python types.

A PySide/PyQt Signal-Sending Circle

Let's define a Circle with properties x, y, and r, denoting the x and y position of the center of the circle, and its radius, respectively. You might want to have one signal that is emitted when the circle is resized, and another that is emitted when it is moved; we'll call them resized and moved, respectively.

It would be possible to have the slots to which the resized and moved signals are connected check the new position or size of the circle and respond accordingly, but it's more convenient and requires less knowledge of circles by the slot functions if the signal that is sent can include that information.

Note these salient points:

  • The Circle inherits from QObject so it can emit signals.
  • The signals are created with the signature of the slot to which they will be connected.
  • The same signal can be emitted in multiple places.

Now, let's define some slots that can be connected to the Circle's signals. Remember last time, when we said we'd see more about the @Slot decorator? We now have signals that carry data, so we'll see how to make slots that can receive it. To make a slot accept data from a signal, we simply define it with the same signature as its signal:

Very simple and intuitive. For more information on Python decorators, you might want to checkout the article - Python Decorators Overview to familiarise yourself.

Finally, let's instantiate a Circle, hook up the signals to the slots, and move and resize it:

When you run the resulting script, your output should be:

Now that we've developed a better understanding of signals and slots, we are ready to use some more advanced widgets. In our next instalment, we will begin to discuss the QListWidget and QListView, two ways of creating list box controls.

To Practice: Try this interactive course on the basics of Lists, Functions, Packages and NumPy in Python.

  • DrTebi

    Great article, thanks for posting, it really helped me with the program I am working on.

    I think one feature worth mentioning, specific to Python as far as I know, is that one can use functools.partial for callback functions.
    So instead of carrying the coordinates within the signal, one could also do something like:


    Now “on_moved” will be called with the arguments x and y.

    Well, something like that; it may not make sense in this case, but it is very useful at times.

    • Hmm, I didn’t know you could do that, looks like we’re teaching each other something!

      We’re in the process of re-organising and publishing more articles for the series. I’ll be sure to point this out. Thanks!

  • Eric

    Good stuff. Perhaps Slot() should have @ in front of say_punched function?

    • Yeah you’re right, thanks for pointing that out, it’s been fixed.

  • hank

    Thanks for sharing. I have a confusion here. Do not see any import things about the Signal class, so I want to know if it is a standard module or defined all by yourself. How can I import the class or where can I find its definition. Thank you!

    • Hi Hank, for PySide the Signal class is in PySide.QtCore, so you can use from PySide.QtCore import QObject, Signal, Slot. For PyQt, the class names are prepended with “pyqt”, from PyQt4.QtCore import QObject, pyqtSignal, pyqtSlot. I’ve updated the article with both examples, and the source’s available to download.

  • Sven

    Great Tutorial. Really helped me to understand the architecture and solved my problem.
    Thank you!