En esta página

QButtonGroup Class

La clase QButtonGroup proporciona un contenedor para organizar grupos de widgets de botón. Más información...

Encabezado: #include <QButtonGroup>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de: QObject

Propiedades

Funciones públicas

QButtonGroup(QObject *parent = nullptr)
virtual ~QButtonGroup()
void addButton(QAbstractButton *button, int id = -1)
QAbstractButton *button(int id) const
QList<QAbstractButton *> buttons() const
QAbstractButton *checkedButton() const
int checkedId() const
bool exclusive() const
int id(QAbstractButton *button) const
void removeButton(QAbstractButton *button)
void setExclusive(bool)
void setId(QAbstractButton *button, int id)

Señales

void buttonClicked(QAbstractButton *button)
void buttonPressed(QAbstractButton *button)
void buttonReleased(QAbstractButton *button)
void buttonToggled(QAbstractButton *button, bool checked)
void idClicked(int id)
void idPressed(int id)
void idReleased(int id)
void idToggled(int id, bool checked)

Descripción detallada

QButtonGroup proporciona un contenedor abstracto en el que se pueden colocar widgets de botón. No ofrece una representación visual de este contenedor (véase QGroupBox para un widget de contenedor), sino que gestiona los estados de cada uno de los botones del grupo.

Un grupo de botones de tipo « exclusive » desactiva todos los botones marcables (de alternancia) excepto aquel sobre el que se ha hecho clic. Por defecto, un grupo de botones es exclusivo. Los botones de un grupo de botones suelen ser «checkable» QPushButton, « QCheckBox» (normalmente para grupos de botones no exclusivos) o « QRadioButton». Si se crea un grupo de botones exclusivo, hay que asegurarse de que uno de los botones del grupo esté marcado inicialmente; de lo contrario, el grupo se encontrará inicialmente en un estado en el que ningún botón esté marcado.

Se puede añadir un botón al grupo con ` addButton()` y eliminarlo con ` removeButton()`. Si el grupo es exclusivo, el botón marcado actualmente está disponible con ` checkedButton()`. Si se hace clic en un botón, se emite la señal ` buttonClicked()`; en el caso de un botón marcable dentro de un grupo exclusivo, esto significa que el botón se ha marcado. La lista de botones del grupo se obtiene mediante ` buttons()` ().

Además, QButtonGroup puede establecer una correspondencia entre números enteros y botones. Se puede asignar un identificador entero a un botón mediante setId(), y recuperarlo con id(). El identificador del botón actualmente marcado está disponible mediante checkedId(), y existe una señal idClicked() que emite el identificador del botón. El identificador -1 está reservado por QButtonGroup para indicar «no existe tal botón». El objetivo del mecanismo de asignación es simplificar la representación de los valores de enumeración en una interfaz de usuario.

Véase también QGroupBox, QPushButton, QCheckBox y QRadioButton.

Documentación de propiedades

exclusive : bool

Esta propiedad determina si el grupo de botones es exclusivo

Si esta propiedad es « true », solo se puede marcar un botón del grupo en un momento dado. El usuario puede hacer clic en cualquier botón para marcarlo, y ese botón sustituirá al actual como el botón marcado del grupo.

En un grupo exclusivo, el usuario no puede desmarcar el botón marcado actualmente haciendo clic en él; en su lugar, debe hacer clic en otro botón del grupo para establecer el nuevo botón marcado de dicho grupo.

De forma predeterminada, esta propiedad es « true ».

Funciones de Access:

bool exclusive() const
void setExclusive(bool)

Documentación de funciones de miembro

[explicit] QButtonGroup::QButtonGroup(QObject *parent = nullptr)

Crea un nuevo grupo de botones vacío con el parent especificado.

Véase también ` addButton()` y ` setExclusive()`.

[virtual noexcept] QButtonGroup::~QButtonGroup()

Elimina el grupo de botones.

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

Añade el « button » indicado al grupo de botones. Si « id » es -1, se asignará un identificador al botón. Se garantiza que los identificadores asignados automáticamente serán negativos, empezando por -2. Si asignas tus propios identificadores, utiliza valores positivos para evitar conflictos.

Véanse también removeButton() y buttons().

QAbstractButton *QButtonGroup::button(int id) const

Devuelve el botón con el nombre especificado ` id`, o ` nullptr ` si no existe dicho botón.

[signal] void QButtonGroup::buttonClicked(QAbstractButton *button)

Esta señal se emite cuando se hace clic en el elemento « button » indicado. Se considera que se ha hecho clic en un botón cuando se pulsa por primera vez y luego se suelta, cuando se teclea su tecla de acceso rápido, o cuando se invocan mediante programación los métodos « QAbstractButton::click()» o « QAbstractButton::animateClick()».

Véase también checkedButton() y QAbstractButton::clicked().

[signal] void QButtonGroup::buttonPressed(QAbstractButton *button)

Esta señal se emite cuando se pulsa la tecla « button ».

Véase también QAbstractButton::pressed().

[signal] void QButtonGroup::buttonReleased(QAbstractButton *button)

Esta señal se emite cuando se suelta el button indicado.

Véase también QAbstractButton::released().

[signal] void QButtonGroup::buttonToggled(QAbstractButton *button, bool checked)

Esta señal se emite cuando se cambia el estado de la propiedad « button ». La propiedad « checked » es «true» si el botón está marcado, y «false» si no lo está.

Véase también QAbstractButton::toggled().

QList<QAbstractButton *> QButtonGroup::buttons() const

Devuelve la lista de botones del grupo de botones. Puede estar vacía.

Véase también addButton() y removeButton().

QAbstractButton *QButtonGroup::checkedButton() const

Devuelve el botón marcado del grupo de botones, o ` nullptr ` si no hay ningún botón marcado.

Véase también buttonClicked().

int QButtonGroup::checkedId() const

Devuelve el identificador de la función ` checkedButton()`, o -1 si no hay ningún botón marcado.

Véase también setId().

int QButtonGroup::id(QAbstractButton *button) const

Devuelve el identificador del botón especificado button, o -1 si dicho botón no existe.

Véase también setId().

[signal] void QButtonGroup::idClicked(int id)

Esta señal se emite cuando se pulsa un botón con el id indicado.

Véanse también checkedButton() y QAbstractButton::clicked().

[signal] void QButtonGroup::idPressed(int id)

Esta señal se emite cuando se pulsa un botón con el id indicado.

Véase también QAbstractButton::pressed().

[signal] void QButtonGroup::idReleased(int id)

Esta señal se emite cuando se suelta un botón con el id especificado.

Véase también QAbstractButton::released().

[signal] void QButtonGroup::idToggled(int id, bool checked)

Esta señal se emite cuando se activa o desactiva un botón con el id especificado. checked es «true» si el botón está marcado, y «false» si no lo está.

Véase también QAbstractButton::toggled().

void QButtonGroup::removeButton(QAbstractButton *button)

Elimina el « button » indicado del grupo de botones.

Véase también addButton() y buttons().

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

Establece el valor de « id » para el « button » especificado. Ten en cuenta que « id » no puede ser -1.

Véase también id().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.