Signals and Slots

A Small Example

A minimal C++ class declaration might read:

    class Counter
    {
    public:
        Counter() { m_value = 0; }

        int value() const { return m_value; }
        void setValue(int value);

    private:
        int m_value;
    };

A small QObject-based class might read:

    #include <QObject>

    class Counter : public QObject
    {
        Q_OBJECT

    public:
        Counter() { m_value = 0; }

        int value() const { return m_value; }

    public slots:
        void setValue(int value);

    signals:
        void valueChanged(int newValue);

    private:
        int m_value;
    };

The QObject-based version has the same internal state, and provides public methods to access the state, but in addition it has support for component programming using signals and slots. This class can tell the outside world that its state has changed by emitting a signal, valueChanged(), and it has a slot which other objects can send signals to.

All classes that contain signals or slots must mention Q_OBJECT at the top of their declaration. They must also derive (directly or indirectly) from QObject.

Slots are implemented by the application programmer. Here is a possible implementation of the Counter::setValue() slot:

    void Counter::setValue(int value)
    {
        if (value != m_value) {
            m_value = value;
            emit valueChanged(value);
        }
    }

The emit line emits the signal valueChanged() from the object, with the new value as argument.

In the following code snippet, we create two Counter objects and connect the first object's valueChanged() signal to the second object's setValue() slot using QObject::connect():

        Counter a, b;
        QObject::connect(&a, SIGNAL(valueChanged(int)),
                         &b, SLOT(setValue(int)));

        a.setValue(12);     // a.value() == 12, b.value() == 12
        b.setValue(48);     // a.value() == 12, b.value() == 48

Calling a.setValue(12) makes a emit a valueChanged(12) signal, which b will receive in its setValue() slot, i.e. b.setValue(12) is called. Then b emits the same valueChanged() signal, but since no slot has been connected to b's valueChanged() signal, the signal is ignored.

Note that the setValue() function sets the value and emits the signal only if value != m_value. This prevents infinite looping in the case of cyclic connections (e.g., if b.valueChanged() were connected to a.setValue()).

A signal is emitted for every connection you make; if you duplicate a connection, two signals will be emitted. You can always break a connection using QObject::disconnect().

This example illustrates that objects can work together without needing to know any information about each other. To enable this, the objects only need to be connected together, and this can be achieved with some simple QObject::connect() function calls, or with uic's automatic connections feature.

        if (widget->inherits("QAbstractButton")) {
            QAbstractButton *button = static_cast<QAbstractButton *>(widget);
            button->toggle();
        }

        if (QAbstractButton *button = qobject_cast<QAbstractButton *>(widget))
            button->toggle();

    #ifndef LCDNUMBER_H
    #define LCDNUMBER_H

    #include <QFrame>

    class LcdNumber : public QFrame
    {
        Q_OBJECT

    public:
        LcdNumber(QWidget *parent = 0);

    signals:
        void overflow();

    public slots:
        void display(int num);
        void display(double num);
        void display(const QString &str);
        void setHexMode();
        void setDecMode();
        void setOctMode();
        void setBinMode();
        void setSmallDecimalPoint(bool point);
    };

    #endif