Introdução ao QButtonGroup

O QButtonGroup é um componente do framework Qt que serve como um contêiner para objetos da classe QAbstractButton. Diferente de contêineres visuais como QGroupBox, ele não fornece interface gráfica, focando-se exclusivamente na gestão lógica de botões. Essa classe é particularmente útil ao tratar múltiplos botões com funcionalidades semelhantes, permitindo um controle centralizado e reduzindo a complexidade do código.

Por padrão, o QButtonGroup opera em modo exclusivo, o que significa que apenas um botão dentro do grupo pode estar marcado (checked) por vez. Isso pode ser alterado conforme necessário. As principais operações incluem adicionar e remover botões, acessar seus identificadores e responder a eventos através de sinais.

Adicionando e Removendo Botões

Para inserir um botão no grupo, utiliza-se a função addButton. Seu protótipo é:

void QButtonGroup::addButton(QAbstractButton *button, int id = -1);

O parâmetro button refere-se ao botão a ser adicionado, enquanto id opcional define um identificador personalizado. Se omitido ou definido como -1, o sistema atribui automaticamentee um ID, começando em -2 e decrementando para cada novo botão sem ID explícito.

Exemplos ilustrativos:

QButtonGroup grupo1;
grupo1.addButton(botaoX);  // ID atribuído automaticamente: -2
grupo1.addButton(botaoY);  // ID atribuído automaticamente: -3
grupo1.addButton(botaoZ);  // ID atribuído automaticamente: -4

QButtonGroup grupo2;
grupo2.addButton(botaoA, 5);
grupo2.addButton(botaoB, 10);
grupo2.addButton(botaoC);  // ID automático: -2 (menor ID existente menos 1, mas como o grupo estava vazio antes de adicionar botaoC? Correção: após adicionar botaoA e botaoB com IDs 5 e 10, o ID automático para botaoC seria -2, assumindo que a lógica decrementa a partir do mínimo existente ou padrão. Para clareza, ajuste: grupo2.addButton(botaoC); // ID: -2, já que o grupo tinha IDs 5 e 10, o mínimo é 5, então 5-1=4? No original, a lógica é: se o grupo tem botões, o novo ID automático é o menor ID existente menos 1. Corrijo: após adicionar botaoA (id 5) e botaoB (id 10), o menor ID é 5, então botaoC com id automático seria 4. Para simplificar o exemplo, use uma sequência clara.)
// Corrigindo para refletir a lógica: se o grupo tem IDs explícitos, o automático decrementa a partir do menor.
// Novo exemplo:
QButtonGroup grupo;
grupo.addButton(botao1, 3);
grupo.addButton(botao2);    // ID automático: 2 (menor ID existente é 3, então 3-1=2)
grupo.addButton(botao3, 1); // ID explícito: 1
grupo.addButton(botao4);    // ID automático: 0 (menor ID agora é 1, então 1-1=0)

A remoção de botões é feita com removeButton:

void QButtonGroup::removeButton(QAbstractButton *button);

Este método desvincula o botão especificado do grupo.

Gerenciamento de Identificadores de Botões

Para consultar o ID de um botão, emprega-se a função id, e para redefinir um ID, utiliza-se setId:

int QButtonGroup::id(QAbstractButton *button) const;
void QButtonGroup::setId(QAbstractButton *button, int id);

Esses métodos permitem ajustar ou inspecionar os identificadores conforme a lógica da aplicação.

Obtendo o Botão Atualmente Selecionado

O QButtonGroup oferece funções para acessar o botão que está marcado no momento. Se nenhum botão estiver selecionado, retorna-se um ponteiro nulo:

QAbstractButton *QButtonGroup::checkedButton() const;
int QButtonGroup::checkedId() const;

checkedButton retorna o objeto do botão, enquanto checkedId fornece seu ID correspondente.

Configurando a Exclusividade do Grupo

Por padrão, o QButtonGroup é exclusivo, garantindo que somente um botão esteja marcado por vez. Para desativar essa restrição, chama-se setExclusive com o valor false:

void QButtonGroup::setExclusive(bool exclusive);

Isso permite que múltiplos botões sejam selecionados simultaneamente, útil em cenários como caixas de seleção.

Conectando Sinais e Slots

O QButtonGroup emite diversos sinais para interações com botões, facilitando a execução de ações específicas. Estes sinais podem ser conectados a slots para tratamento de eventos.

Sinais que retornam o botão pressionado como um objeto QAbstractButton:

void QButtonGroup::buttonClicked(QAbstractButton *button);
void QButtonGroup::buttonPressed(QAbstractButton *button);
void QButtonGroup::buttonReleased(QAbstractButton *button);
void QButtonGroup::buttonToggled(QAbstractButton *button, bool checked);

Como esses sinais são sobrecarregados, ao usar ponteiros de função para conexão, pode-se empregar QOverload:

connect(grupoBotoes, QOverload<QAbstractButton *>::of(&QButtonGroup::buttonClicked),
    [listaDeCaptura](QAbstractButton *btn) { /* Lógica de tratamento */ });

Alternativamente, há sinais que retornam o ID do botão:

void QButtonGroup::idClicked(int id);
void QButtonGroup::idPressed(int id);
void QButtonGroup::idReleased(int id);
void QButtonGroup::idToggled(int id, bool checked);

Esses sinais são úteis quando a identificação por ID é mais conveniente do que referenciar o objeto do botão diretamente.