Back to Qt.io
Contact Us Blog Download Qt
En esta página

QGroupBox Class

El widget QGroupBox proporciona un marco de caja de grupo con un título. Más...

Cabecera: #include <QGroupBox>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Hereda: 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 con 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 dentro de sí mismo. El atajo de teclado mueve el foco del teclado a uno de los widgets hijos del cuadro de grupo.

QGroupBox también permite establecer el title (normalmente establecido en el constructor) y el alignment del título. Los cuadros de grupo pueden ser checkable. Los widgets hijos de las cajas de grupo seleccionables se activan o desactivan dependiendo de si la caja de grupo es checked.

Puede minimizar el consumo de espacio de un cuadro de grupo activando la propiedad flat. En la mayoría de los casos styles, al habilitar esta propiedad se eliminan los bordes izquierdo, derecho e inferior del cuadro.

QGroupBox no dispone automáticamente los widgets hijos (que suelen ser QCheckBoxes o QRadioButtons pero pueden ser cualquier widget). El siguiente ejemplo muestra como podemos configurar un QGroupBox con un layout:

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);

Ver también QButtonGroup.

Documentación de propiedades

alignment : Qt::Alignment

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

La mayoría de los estilos colocan el título en la parte superior del marco. La alineación horizontal del título puede especificarse utilizando valores individuales de la siguiente lista:

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

La alineación por defecto es Qt::AlignLeft.

Funciones de acceso:

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 verificación en su título.

Si esta propiedad es true, el cuadro de grupo muestra su título utilizando una casilla de verificación en lugar de una etiqueta normal. Si la casilla de verificación está marcada, los hijos del cuadro de grupo están habilitados; en caso contrario, están deshabilitados e inaccesibles.

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

Si se activa esta propiedad para un cuadro de grupo, también se marcará inicialmente para asegurarse de que su contenido está activado.

Funciones de acceso:

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 es seleccionable, se muestra con una casilla de verificación. Si la casilla de verificación está marcada, los hijos del cuadro de grupo están habilitados; en caso contrario, los hijos están deshabilitados y son inaccesibles para el usuario.

Por defecto, los cuadros de grupo que se pueden marcar también están marcados.

Nota: El cuadro de grupo en sí no se desactivará cuando el cuadro esté desmarcado, y puede activar explícitamente hijos individuales en un cuadro de grupo que esté desmarcado. Sin embargo, esto no es recomendable, ya que podría crear una experiencia sorprendente para el usuario final.

Funciones de acceso:

bool isChecked() const
void setChecked(bool checked)

Señal de aviso:

void toggled(bool on)

Véase también checkable.

flat : bool

Esta propiedad indica si el cuadro de grupo está pintado plano o tiene un marco.

Una caja de grupo normalmente consiste en un marco que la rodea con un título en la parte superior. Si esta propiedad está activada, en la mayoría de los estilos sólo se dibuja la parte superior del marco; en caso contrario, se dibuja todo el marco.

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 pueden no ser tan distinguibles como en otros estilos.

Funciones de acceso:

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 ampersand ('&') seguido de una letra.

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

En el ejemplo anterior, Alt+U mueve el foco del teclado al cuadro de grupo. Consulte la documentación de QShortcut para obtener más detalles (para mostrar un ampersand real, utilice '&&').

No hay texto de título por defecto.

Funciones de acceso:

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

Véase también Alineación.

Documentación de las funciones miembro

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

Crea un widget de cuadro de grupo con la dirección parent pero sin título.

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

Crea un cuadro de grupo con las direcciones title y parent.

[virtual noexcept] QGroupBox::~QGroupBox()

Destruye 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, se pulsa y luego se suelta mientras el cursor del ratón está dentro del botón), o cuando se teclea la tecla de acceso directo. En particular, esta señal no se emite si se llama a setChecked().

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

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 este QGroupBox. Este método es útil para subclases cuando necesitan un QStyleOptionGroupBox, pero no quieren rellenar toda la información ellos mismos.

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 es seleccionable, esta señal se emite cuando se activa la casilla de verificación. on es verdadera si la casilla de verificación está seleccionada; en caso contrario, es falsa.

Nota: Señal notificadora de 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.