|  | Home · Overviews · Examples

# QSignalMapper Class Reference
[com.trolltech.qt.core module]

The `QSignalMapper` class bundles signals from identifiable senders. More...

Inherits `QObject`.

## Detailed Description

The `QSignalMapper` class bundles signals from identifiable senders.

This class collects a set of parameterless signals, and re-emits them with integer, string or widget parameters corresponding to the object that sent the signal.

The class supports the mapping of particular strings or integers with particular objects using `setMapping`. The objects' signals can then be connected to the `map` slot which will emit the mapped() signal with the string or integer associated with the original signalling object. Mappings can be removed later using `removeMappings`.

Example: Suppose we want to create a custom widget that contains a group of buttons (like a tool palette). One approach is to connect each button's `clicked()` signal to its own custom slot; but in this example we want to connect all the buttons to a single slot and parameterize the slot by the button that was clicked.

Here's the definition of a simple custom widget that has a single signal, `clicked()`, which is emitted with the text of the button that was clicked:

        class ButtonWidget : public QWidget
        {
            Q_OBJECT

        public:
            ButtonWidget(QStringList texts, QWidget *parent = 0);

        signals:
            void clicked(const QString &text);

        private:
            QSignalMapper *signalMapper;
        };

The only function that we need to implement is the constructor:

        ButtonWidget::ButtonWidget(QStringList texts, QWidget *parent)
            : QWidget(parent)
        {
            signalMapper = new QSignalMapper(this);

            QGridLayout *gridLayout = new QGridLayout;
            for (int i = 0; i < texts.size(); ++i) {
                QPushButton *button = new QPushButton(texts[i]);
                connect(button, SIGNAL(clicked()), signalMapper, SLOT(map()));
                signalMapper->setMapping(button, texts[i]);
                gridLayout->addWidget(button, i / 3, i % 3);
            }

            connect(signalMapper, SIGNAL(mapped(const QString &)),
                    this, SIGNAL(clicked(const QString &)));

            setLayout(gridLayout);
        }

A list of texts is passed to the constructor. A signal mapper is constructed and for each text in the list a `QPushButton` is created. We connect each button's `clicked()` signal to the signal mapper's `map` slot, and create a mapping in the signal mapper from each button to the button's text. Finally we connect the signal mapper's mapped() signal to the custom widget's `clicked()` signal. When the user clicks a button, the custom widget will emit a single `clicked()` signal whose argument is the text of the button the user clicked.

See also `QObject`, `QButtonGroup`, and `QActionGroup`.