O QSignalMapper é uma ferramenta útil na biblioteca Qt que facilita o gerenciamento de sinais e slots, especialmente quando você tem múltiplos objetos emitindo sinais semelhantes e deseja conectá-los a um único slot com parâmetros distintos.

Utilização

A principal função do QSignalMapper é atuar como um intermediário. Ele intercepta um sinal sem parâmetros de um objeto emissor e, com base em um mapeamento pré-definido, reemite um novo sinal com um parâmetro associado a esse objeto emissor. Isso evita a necessidade de criar múltiplos slots ou usar lambdas para cada conexão individual, simplificando o código.

Exemplo Prático

Considere um cenário onde você tem vários botões e deseja que cada um, ao ser clicado, acione uma ação específica, identificada por um texto único. Sem o QSignalMapper, você poderia conectar cada botão a um slot lambda diferente:

QSignalMapper *mapper = new QSignalMapper(this);
QStringList buttonLabels = {"Botão Um", "Botão Dois", "Botão Três"};

for (int i = 0; i < buttonLabels.size(); ++i) {
   QString label = buttonLabels.at(i);
   QPushButton *button = new QPushButton(label, this);
   connect(button, &QPushButton::clicked, [=]() {
       qDebug() << "Botão clicado:" << label;
   });
}
   

Com o QSignalMapper, o processo é mais organizado:

QSignalMapper *mapper = new QSignalMapper(this);
QStringList buttonLabels = {"Botão Um", "Botão Dois", "Botão Três"};

for (int i = 0; i < buttonLabels.size(); ++i) {
   QPushButton *button = new QPushButton(buttonLabels.at(i), this);
   // 1. Conecta o sinal 'clicked' do botão ao slot 'map' do QSignalMapper.
   connect(button, &QPushButton::clicked, mapper, static_cast<void>(&QSignalMapper::map));
   // 2. Define o mapeamento: este botão (emissor) será associado a esta string (parâmetro).
   mapper->setMapping(button, buttonLabels.at(i));
}

// 3. Conecta o sinal 'mapped' do QSignalMapper a um slot que recebe o parâmetro mapeado.
connect(mapper, QOverload<const qstring="">::of(&QSignalMapper::mapped),
       [=](const QString &text) {
           qDebug() << "Ação acionada para:" << text;
       });
   </const></void>

Principais Funções

• setMapping(QObject *emissor, QVariant parametro): Estabelece a relação entre um objeto emissor e o parâmetro que será enviado quando o sinal desse emissor for mapeado. O parâmetro pode ser de diversos tipos, como int, QString, QWidget*, etc.
• removeMappings(QObject *emissor): Remove todas as relações de mapeamento associadas a um objeto emissor específico.
• mapping(QVariant parametro) const: Retorna o objeto emissor que foi originalmente associado a um determinado parâmetro.

Sinais e Slots do QSignalMapper

• Slot: map(): Este slot é conectado aos sinais dos objetos emissores. Quando um desses sinais é emitido, o QSignalMapper utiliza o mapeamento configurado para reemitir seu próprio sinal mapped com o parâmetro associado.
• Sinal: mapped(QVariant parametro): Este sinal é emitido pelo QSignalMapper após receber um sinal de um emissor mapeado. O parametro transmitido é aquele que foi defiindo durante o mapeamento. Como este sinal é sobrecarregado para diferentes tipos de parâmetros, é comum usar QOverload para especificar qual versão do sinal se deseja conectar.