QCheckBox Class
El widget QCheckBox ofrece una casilla de selección con una etiqueta de texto. Más información...
| Encabezado: | #include <QCheckBox> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | QAbstractButton |
Propiedades
- tristate : bool
Funciones públicas
| QCheckBox(QWidget *parent = nullptr) | |
| QCheckBox(const QString &text, QWidget *parent = nullptr) | |
| virtual | ~QCheckBox() |
| Qt::CheckState | checkState() const |
| bool | isTristate() const |
| void | setCheckState(Qt::CheckState state) |
| void | setTristate(bool y = true) |
Funciones públicas reimplementadas
| virtual QSize | minimumSizeHint() const override |
| virtual QSize | sizeHint() const override |
Señales
(since 6.7) void | checkStateChanged(Qt::CheckState state) |
Funciones protegidas
| virtual void | initStyleOption(QStyleOptionButton *option) const |
Funciones protegidas reimplementadas
| virtual void | checkStateSet() override |
| virtual bool | event(QEvent *e) override |
| virtual bool | hitButton(const QPoint &pos) const override |
| virtual void | mouseMoveEvent(QMouseEvent *e) override |
| virtual void | nextCheckState() override |
| virtual void | paintEvent(QPaintEvent *) override |
Descripción detallada

Un QCheckBox es un botón de opción que se puede activar (marcar) o desactivar (desmarcar). Las casillas de selección se suelen utilizar para representar características de una aplicación que pueden activarse o desactivarse sin que ello afecte a otras. Se pueden implementar diferentes tipos de comportamiento. Por ejemplo, se puede utilizar un « QButtonGroup » para agrupar botones de selección de forma lógica, lo que permite el uso de casillas de selección exclusivas. Sin embargo, « QButtonGroup » no proporciona ninguna representación visual.
La imagen siguiente ilustra con más detalle las diferencias entre las casillas de selección exclusivas y no exclusivas.
![]() | ![]() |
Cada vez que se marca o desmarca una casilla de selección, esta emite la señal checkStateChanged(). Conéctate a esta señal si deseas activar una acción cada vez que la casilla cambie de estado. Puedes utilizar isChecked() para comprobar si una casilla de selección está marcada o no.
Además de los estados habituales «marcado» y «desmarcado», QCheckBox ofrece opcionalmente un tercer estado para indicar «sin cambios». Esto resulta útil cuando necesitas dar al usuario la opción de no marcar ni desmarcar una casilla de selección. Si necesitas este tercer estado, actívalo con ` setTristate()` y utiliza ` checkState()` para consultar el estado actual de la casilla.
Al igual que QPushButton, una casilla de selección muestra texto y, opcionalmente, un pequeño icono. El icono se establece con setIcon(). El texto se puede establecer en el constructor o con setText(). Se puede especificar una tecla de acceso rápido anteponiendo un símbolo «&» al carácter deseado. Por ejemplo:
En este ejemplo, la combinación de teclas es Alt+A. Consulta la documentación de QShortcut para obtener más detalles. Para mostrar un símbolo «&» real, utiliza «&&».
Véase también QAbstractButton y QRadioButton.
Documentación sobre propiedades
tristate : bool
Esta propiedad indica si la casilla de selección es de tres estados
El valor por defecto es «false», es decir, la casilla de selección solo tiene dos estados.
Funciones de Access:
| bool | isTristate() const |
| void | setTristate(bool y = true) |
Documentación de las funciones de miembro
[explicit] QCheckBox::QCheckBox(QWidget *parent = nullptr)
Crea una casilla de selección con el objeto ` parent` indicado, pero sin texto.
parent Se pasa al constructor de ` QAbstractButton `.
[explicit] QCheckBox::QCheckBox(const QString &text, QWidget *parent = nullptr)
Crea una casilla de selección con los valores proporcionados en ` parent ` y ` text`.
parent se pasa al constructor de QAbstractButton.
[virtual noexcept] QCheckBox::~QCheckBox()
Destructor.
Qt::CheckState QCheckBox::checkState() const
Devuelve el estado de selección de la casilla de verificación. Si no necesitas compatibilidad con el modo de tres estados, también puedes utilizar QAbstractButton::isChecked(), que devuelve un valor booleano.
Véase también setCheckState() y Qt::CheckState.
[signal, since 6.7] void QCheckBox::checkStateChanged(Qt::CheckState state)
Esta señal se emite cada vez que cambia el estado de la casilla de selección, es decir, cada vez que el usuario la marca o la desmarca.
state contiene el nuevo « Qt::CheckState » de la casilla de selección.
Esta función se introdujo en Qt 6.7.
[override virtual protected] void QCheckBox::checkStateSet()
Reimplementa: QAbstractButton::checkStateSet().
[override virtual protected] bool QCheckBox::event(QEvent *e)
Reimplementa: QAbstractButton::event(QEvent *e).
[override virtual protected] bool QCheckBox::hitButton(const QPoint &pos) const
Reimplementa: ` QAbstractButton::hitButton(const QPoint &pos) const`.
[virtual protected] void QCheckBox::initStyleOption(QStyleOptionButton *option) const
Inicializa ` option ` con los valores de este ` QCheckBox`. Este método resulta útil para las subclases que necesitan un ` QStyleOptionButton`, pero no desean rellenar toda la información por sí mismas.
Véase también QStyleOption::initFrom().
[override virtual] QSize QCheckBox::minimumSizeHint() const
Reimplementa una función de acceso para la propiedad: QWidget::minimumSizeHint.
[override virtual protected] void QCheckBox::mouseMoveEvent(QMouseEvent *e)
Reimplementa: QAbstractButton::mouseMoveEvent(QMouseEvent *e).
[override virtual protected] void QCheckBox::nextCheckState()
Reimplementa: QAbstractButton::nextCheckState().
[override virtual protected] void QCheckBox::paintEvent(QPaintEvent *)
Reimplementa: QAbstractButton::paintEvent(QPaintEvent *e).
void QCheckBox::setCheckState(Qt::CheckState state)
Establece el estado de la casilla de selección en « state ». Si no necesitas compatibilidad con el modo de tres estados, también puedes utilizar « QAbstractButton::setChecked()», que admite un valor booleano.
Véase también checkState() y Qt::CheckState.
[override virtual] QSize QCheckBox::sizeHint() const
Reimplementa una función de acceso para la propiedad: QWidget::sizeHint.
© 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.

