QGroupBox Class
QGroupBox 控件提供了一个带有标题的组框框架。更多内容...
| 标题： | #include <QGroupBox> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake： | QT += widgets |
| 继承自： | QWidget |
属性
公共函数
| 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 |
重新实现的公共函数
| virtual QSize | minimumSizeHint() const override |
公共插槽
| void | setChecked(bool checked) |
信号
受保护函数
| virtual void | initStyleOption(QStyleOptionGroupBox *option) const |
重新实现的受保护函数
| 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 |
详细说明
组框提供了一个框架、顶部的标题、一个键盘快捷键，并在其内部显示各种其他控件。键盘快捷键可将键盘焦点移至组框的某个子控件上。
QGroupBox 还允许您设置title （通常在构造函数中设置）以及标题的alignment 。组框可以checkable 。可选中组框中的子控件是否启用，取决于组框是否checked 。
您可以通过启用flat 属性来减少组框的占用空间。在大多数styles 中，启用此属性会去除框架的左、右和下边缘。
QGroupBox 不会自动布局子控件（这些控件通常是QCheckBox或QRadioButton，但也可能是任何控件）。以下示例演示了如何为 QGroupBox 设置布局：
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);另请参阅 QButtonGroup 。
属性文档
alignment : Qt::Alignment
此属性控制组框标题的对齐方式。
大多数样式会将标题放置在框的顶部。可以使用以下列表中的单个值来指定标题的水平对齐方式：
- Qt::AlignLeft 将标题文本与组框的左侧对齐。
- Qt::AlignRight 将标题文本与组框的右侧对齐。
- Qt::AlignHCenter 将标题文本对齐到组框的水平中心。
默认对齐方式为Qt::AlignLeft 。
Access 函数：
| Qt::Alignment | alignment() const |
| void | setAlignment(int alignment) |
另请参阅 Qt::Alignment 。
checkable : bool
该属性用于指定组框的标题中是否包含复选框
如果此属性的值为true ，则组框将使用复选框代替普通标签来显示其标题。如果复选框被选中，则组框的子控件处于启用状态；否则，这些子控件处于禁用状态且不可访问。
默认情况下，组框不可选中。
如果为某个组框启用了此属性，该复选框初始状态将处于选中状态，以确保其内容处于启用状态。
Access 函数：
| bool | isCheckable() const |
| void | setCheckable(bool checkable) |
另请参阅 checked 。
checked : bool
该属性用于表示组框是否被选中
如果组框可选中，则会显示一个复选框。如果复选框被选中，则组框的子控件处于启用状态；否则，子控件处于禁用状态，用户无法对其进行操作。
默认情况下，可选中的组框本身也是选中的。
注意： 当组框未被选中时，组框 本身不会被禁用，您可以显式地启用未被选中组框中的单个子控件。但不建议这样做，因为这可能会给最终用户带来出乎意料的体验。
访问函数：
| bool | isChecked() const |
| void | setChecked(bool checked) |
通知信号：
| void | toggled(bool on) |
另请参阅 checkable 。
flat : bool
该属性决定了组框是平绘制还是带有边框
组框通常由一个带顶部标题的包围边框组成。如果启用此属性，在大多数样式下仅绘制边框的顶部；否则，将绘制整个边框。
默认情况下，此属性处于禁用状态，即除非明确指定，否则组框不会以扁平样式显示。
注意：在某些样式中，扁平化和非扁平化的组框外观相似，可能不像在其他样式中那样容易区分。
Access 函数：
| bool | isFlat() const |
| void | setFlat(bool flat) |
另请参阅 title 。
title : QString
此属性存储组框的标题文本
如果组框标题中包含“&”符号后跟一个字母，则该组框标题文本将具有键盘快捷键。
g->setTitle("&User information");在上例中，Alt+U 将键盘焦点移至该组框。详情请参阅QShortcut 文档（要显示实际的“&”符号，请使用 '&&'）。
没有默认标题文本。
Access 函数：
| QString | title() const |
| void | setTitle(const QString &title) |
另请参阅 “对齐方式”。
成员函数文档
[explicit] QGroupBox::QGroupBox(QWidget *parent = nullptr)
创建一个组框控件，使用给定的parent ，但不显示标题。
[explicit] QGroupBox::QGroupBox(const QString &title, QWidget *parent = nullptr)
根据给定的title 和parent 创建一个组框。
[virtual noexcept] QGroupBox::~QGroupBox()
删除该组框。
[override virtual protected] void QGroupBox::changeEvent(QEvent *ev)
重写了：QWidget::changeEvent(QEvent *event)。
[override virtual protected] void QGroupBox::childEvent(QChildEvent *c)
重写了：QObject::childEvent(QChildEvent *event)。
[signal] void QGroupBox::clicked(bool checked = false)
当复选框被激活（即鼠标光标位于按钮内时按下并松开复选框）或按下快捷键时，会发出此信号。需要注意的是，如果调用setChecked()，则不会发出此信号。
如果复选框被选中，checked 返回 true；如果复选框未被选中，则返回 false。
另请参阅 checkable 、toggled() 以及checked 。
[override virtual protected] bool QGroupBox::event(QEvent *e)
重写了：QWidget::event(QEvent *event)。
[override virtual protected] void QGroupBox::focusInEvent(QFocusEvent *fe)
重写了：QWidget::focusInEvent(QFocusEvent *event)。
[virtual protected] void QGroupBox::initStyleOption(QStyleOptionGroupBox *option) const
使用QGroupBox 中的值初始化option 。当子类需要QStyleOptionGroupBox 时，但又不想自己填写所有信息，此方法非常有用。
另请参阅 QStyleOption::initFrom()。
[override virtual] QSize QGroupBox::minimumSizeHint() const
重新实现了属性QWidget::minimumSizeHint 的访问函数。
[override virtual protected] void QGroupBox::mouseMoveEvent(QMouseEvent *event)
重写了：QWidget::mouseMoveEvent(QMouseEvent *event)。
[override virtual protected] void QGroupBox::mousePressEvent(QMouseEvent *event)
重写了：QWidget::mousePressEvent(QMouseEvent *event)。
[override virtual protected] void QGroupBox::mouseReleaseEvent(QMouseEvent *event)
重写：QWidget::mouseReleaseEvent(QMouseEvent *event)。
[override virtual protected] void QGroupBox::paintEvent(QPaintEvent *event)
重写了：QWidget::paintEvent(QPaintEvent *event)。
[override virtual protected] void QGroupBox::resizeEvent(QResizeEvent *e)
重写了：QWidget::resizeEvent(QResizeEvent *event)。
[signal] void QGroupBox::toggled(bool on)
如果组框支持勾选，则当复选框状态切换时会发出此信号。若复选框被勾选，on 为真；否则为假。
注意： 属性checked的通知 信号。
另请参阅 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.
