QSignalMapper Class

Description détaillée

Cette classe collecte un ensemble de signaux sans paramètre et les réémet avec des paramètres de type entier, chaîne ou widget correspondant à l'objet qui a envoyé le signal. Notez que dans la plupart des cas, vous pouvez utiliser des lambdas pour passer des paramètres personnalisés aux slots. Cela est moins coûteux et simplifie le code.

La classe prend en charge le mappage de chaînes, d'entiers, d'objets et de widgets particuliers avec des objets particuliers à l'aide de setMapping(). Les signaux des objets peuvent alors être connectés au slot map() qui émettra un signal (il pourrait s'agir de mappedInt(), mappedString() et mappedObject()) avec une valeur associée à l'objet de signalisation d'origine. Les correspondances peuvent être supprimées ultérieurement à l'aide de removeMappings().

Exemple : Supposons que nous voulions créer un widget personnalisé contenant un groupe de boutons (comme une palette d'outils). Une approche consiste à connecter le signal clicked() de chaque bouton à son propre slot personnalisé ; mais dans cet exemple, nous voulons connecter tous les boutons à un seul slot et paramétrer ce dernier en fonction du bouton sur lequel on a cliqué.

Voici la définition d'un widget personnalisé simple qui a un seul signal, clicked(), qui est émis avec le texte du bouton qui a été cliqué :

class ButtonWidget : public QWidget
{
    Q_OBJECT

public:
    ButtonWidget(const QStringList &texts, QWidget *parent = nullptr);

signals:
    void clicked(const QString &text);

private:
    QSignalMapper *signalMapper;
};

La seule fonction que nous devons implémenter est le constructeur :

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

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

    connect(signalMapper, &QSignalMapper::mappedString,
            this, &ButtonWidget::clicked);
}

Une liste de textes est transmise au constructeur. Un mappeur de signaux est construit et pour chaque texte de la liste, un QPushButton est créé. Nous connectons le signal clicked() de chaque bouton au slot map() du mappeur de signaux, et nous créons une correspondance dans le mappeur de signaux entre chaque bouton et le texte du bouton. Enfin, nous connectons le signal mappedString() du mappeur de signaux au signal clicked() du widget personnalisé. Lorsque l'utilisateur clique sur un bouton, le widget personnalisé émet un seul signal clicked() dont l'argument est le texte du bouton sur lequel l'utilisateur a cliqué.

Cette classe était surtout utile avant que les fonctions lambda puissent être utilisées comme des slots. L'exemple ci-dessus peut être réécrit plus simplement sans QSignalMapper en se connectant à une fonction lambda.

ButtonWidget::ButtonWidget(const QStringList &texts, QWidget *parent)
    : QWidget(parent)
{
    QGridLayout *gridLayout = new QGridLayout(this);
    for (int i = 0; i < texts.size(); ++i) {
        QString text = texts[i];
        QPushButton *button = new QPushButton(text);
        connect(button, &QPushButton::clicked, [this, text] { clicked(text); });
        gridLayout->addWidget(button, i / 3, i % 3);
    }
}