En esta página

QGroupBox Class

El widget QGroupBox ofrece un marco de cuadro de grupo con un título. Más...

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

Propiedades

Funciones públicas

QGroupBox(QWidget *parent = nullptr)
QGroupBox(const QString &title, QWidget *parent = nullptr)
virtual ~QGroupBox()
Qt::Alignment alignment() const
bool isCheckable() const
bool isChecked() const
bool isFlat() const
void setAlignment(int alignment)
void setCheckable(bool checkable)
void setFlat(bool flat)
void setTitle(const QString &title)
QString title() const

Funciones públicas reimplementadas

virtual QSize minimumSizeHint() const override

Ranuras públicas

void setChecked(bool checked)

Señales

void clicked(bool checked = false)
void toggled(bool on)

Funciones protegidas

virtual void initStyleOption(QStyleOptionGroupBox *option) const

Funciones protegidas reimplementadas

virtual void changeEvent(QEvent *ev) override
virtual void childEvent(QChildEvent *c) override
virtual bool event(QEvent *e) override
virtual void focusInEvent(QFocusEvent *fe) override
virtual void mouseMoveEvent(QMouseEvent *event) override
virtual void mousePressEvent(QMouseEvent *event) override
virtual void mouseReleaseEvent(QMouseEvent *event) override
virtual void paintEvent(QPaintEvent *event) override
virtual void resizeEvent(QResizeEvent *e) override

Descripción detallada

Cuadro de grupo que muestra varios botones de opción

Un cuadro de grupo proporciona un marco, un título en la parte superior, un atajo de teclado y muestra otros widgets en su interior. El atajo de teclado desplaza el foco del teclado a uno de los widgets hijos del cuadro de grupo.

QGroupBox también permite establecer la propiedad « title » (que normalmente se configura en el constructor) y la propiedad « alignment » del título. Los cuadros de grupo pueden estar « checkable ». Los widgets hijos de los cuadros de grupo marcables se activan o desactivan dependiendo de si el cuadro de grupo está « checked ».

Se puede minimizar el espacio que ocupa un cuadro de grupo activando la propiedad flat. En la mayoría de los styles, al activar esta propiedad se eliminan los bordes izquierdo, derecho e inferior del marco.

QGroupBox no distribuye automáticamente los widgets hijos (que suelen ser QCheckBoxo QRadioButton, pero pueden ser cualquier tipo de widget). El siguiente ejemplo muestra cómo podemos configurar un QGroupBox con una distribución:

QGroupBox *groupBox = new QGroupBox(tr("Group Box with Layout"));

QRadioButton *radio1 = new QRadioButton(tr("&Radio button 1"));
QRadioButton *radio2 = new QRadioButton(tr("R&adio button 2"));
QRadioButton *radio3 = new QRadioButton(tr("Ra&dio button 3"));

radio1->setChecked(true);

QVBoxLayout *vbox = new QVBoxLayout;
vbox->addWidget(radio1);
vbox->addWidget(radio2);
vbox->addWidget(radio3);
vbox->addStretch(1);
groupBox->setLayout(vbox);

Véase también QButtonGroup.

Documentación de propiedades

alignment : Qt::Alignment

Esta propiedad define la alineación del título del cuadro de grupo.

La mayoría de los estilos sitúan el título en la parte superior del marco. La alineación horizontal del título se puede especificar utilizando uno de los valores de la siguiente lista:

  • Qt::AlignLeft alinea el texto del título con el borde izquierdo del cuadro de grupo.
  • Qt::AlignRight alinea el texto del título con el borde derecho del cuadro de grupo.
  • Qt::AlignHCenter Alinea el texto del título con el centro horizontal del cuadro de grupo.

La alineación predeterminada es « Qt::AlignLeft ».

Funciones de Access:

Qt::Alignment alignment() const
void setAlignment(int alignment)

Véase también « Qt::Alignment ».

checkable : bool

Esta propiedad indica si el cuadro de grupo tiene una casilla de selección en su título

Si esta propiedad tiene el valor « true », el cuadro de grupo muestra su título utilizando una casilla de selección en lugar de una etiqueta normal. Si la casilla de selección está marcada, los elementos secundarios del cuadro de grupo están habilitados; de lo contrario, están deshabilitados y no se puede acceder a ellos.

Por defecto, los cuadros de grupo no se pueden marcar.

Si esta propiedad está habilitada para un cuadro de grupo, este también aparecerá marcado inicialmente para garantizar que sus elementos estén habilitados.

Funciones de Access:

bool isCheckable() const
void setCheckable(bool checkable)

Véase también « checked ».

checked : bool

Esta propiedad indica si el cuadro de grupo está marcado

Si el cuadro de grupo se puede marcar, se muestra con una casilla de selección. Si la casilla de selección está marcada, los elementos secundarios del cuadro de grupo están habilitados; de lo contrario, los elementos secundarios están deshabilitados y el usuario no puede acceder a ellos.

Por defecto, los cuadros de grupo marcables también están marcados.

Nota: El cuadro de grupo en sí no se desactivará cuando la casilla esté desmarcada, y puedes habilitar explícitamente elementos secundarios individuales dentro de un cuadro de grupo que esté desmarcado. Sin embargo, esto no se recomienda, ya que podría generar una experiencia inesperada para el usuario final.

Funciones de acceso:

bool isChecked() const
void setChecked(bool checked)

Señal de notificación:

void toggled(bool on)

Véase también checkable.

flat : bool

Esta propiedad se aplica tanto si el cuadro de grupo se dibuja sin marco como si tiene marco

Un cuadro de grupo suele consistir en un marco que lo rodea con un título en la parte superior. Si esta propiedad está activada, en la mayoría de los estilos solo se dibuja la parte superior del marco; de lo contrario, se dibuja el marco completo.

Por defecto, esta propiedad está desactivada, es decir, los cuadros de grupo no son planos a menos que se especifique explícitamente.

Nota: En algunos estilos, los cuadros de grupo planos y no planos tienen representaciones similares y puede que no sean tan fáciles de distinguir como en otros estilos.

Funciones de Access:

bool isFlat() const
void setFlat(bool flat)

Véase también title.

title : QString

Esta propiedad contiene el texto del título del cuadro de grupo

El texto del título del cuadro de grupo tendrá un atajo de teclado si el título contiene un símbolo «&» seguido de una letra.

g->setTitle("&User information");

En el ejemplo anterior, « Alt+U » desplaza el foco del teclado al cuadro de grupo. Consulta la documentación de QShortcut para obtener más detalles (para mostrar un símbolo «&» real, utiliza «&&»).

No hay ningún texto de título predeterminado.

Funciones de Access:

QString title() const
void setTitle(const QString &title)

Véase también «alineación».

Documentación de funciones de miembro

[explicit] QGroupBox::QGroupBox(QWidget *parent = nullptr)

Crea un widget de cuadro de grupo con el « parent » indicado, pero sin título.

[explicit] QGroupBox::QGroupBox(const QString &title, QWidget *parent = nullptr)

Crea un cuadro de grupo con los valores indicados para « title » y « parent ».

[virtual noexcept] QGroupBox::~QGroupBox()

Elimina el cuadro de grupo.

[override virtual protected] void QGroupBox::changeEvent(QEvent *ev)

Reimplementa: ` QWidget::changeEvent(QEvent *event)`.

[override virtual protected] void QGroupBox::childEvent(QChildEvent *c)

Reimplementa: QObject::childEvent(QChildEvent *event).

[signal] void QGroupBox::clicked(bool checked = false)

Esta señal se emite cuando se activa la casilla de verificación (es decir, al pulsarla y soltarla mientras el cursor del ratón se encuentra dentro del botón) o al pulsar la tecla de acceso rápido. Cabe destacar que esta señal no se emite si se llama a ` setChecked()`.

Si la casilla de selección está marcada, checked es verdadero; es falso si la casilla de selección no está marcada.

Véase también checkable, toggled() y checked.

[override virtual protected] bool QGroupBox::event(QEvent *e)

Reimplementa: ` QWidget::event(QEvent *event)`.

[override virtual protected] void QGroupBox::focusInEvent(QFocusEvent *fe)

Reimplementa: QWidget::focusInEvent(QFocusEvent *event).

[virtual protected] void QGroupBox::initStyleOption(QStyleOptionGroupBox *option) const

Inicializa ` option ` con los valores de esta página: QGroupBox. Este método resulta útil para las subclases cuando necesitan un ` QStyleOptionGroupBox`, pero no quieren introducir toda la información ellas mismas.

Véase también QStyleOption::initFrom().

[override virtual] QSize QGroupBox::minimumSizeHint() const

Reimplementa una función de acceso para la propiedad: QWidget::minimumSizeHint.

[override virtual protected] void QGroupBox::mouseMoveEvent(QMouseEvent *event)

Reimplementa: ` QWidget::mouseMoveEvent(QMouseEvent *event)`.

[override virtual protected] void QGroupBox::mousePressEvent(QMouseEvent *event)

Reimplementa: ` QWidget::mousePressEvent(QMouseEvent *event)`.

[override virtual protected] void QGroupBox::mouseReleaseEvent(QMouseEvent *event)

Reimplementa: ` QWidget::mouseReleaseEvent(QMouseEvent *event)`.

[override virtual protected] void QGroupBox::paintEvent(QPaintEvent *event)

Reimplementa: QWidget::paintEvent(QPaintEvent *event).

[override virtual protected] void QGroupBox::resizeEvent(QResizeEvent *e)

Reimplementa: QWidget::resizeEvent(QResizeEvent *event).

[signal] void QGroupBox::toggled(bool on)

Si el cuadro de grupo permite marcarlo, esta señal se emite cuando se activa o desactiva la casilla de selección. La propiedad ` on ` es verdadera si la casilla de selección está marcada; en caso contrario, es falsa.

Nota: Señalde notificación para la propiedad checked.

Véase también checkable.

© 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.