En esta página

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

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

Casilla de selección para la opción de guardar

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.

Grupo de casillas de selección que solo permite marcar una opciónGrupo de casillas de selección que permite marcar varias opciones

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:

QCheckBox *checkbox = new QCheckBox("C&ase sensitive", this);

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.