QButtonGroup Class
QButtonGroup 类提供了一个容器，用于组织按钮控件组。更多内容...
| 头文件： | #include <QButtonGroup> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake： | QT += widgets |
| 继承自： | QObject |
属性
- exclusive : bool
公共函数
| QButtonGroup(QObject *parent = nullptr) | |
| virtual | ~QButtonGroup() |
| void | addButton(QAbstractButton *button, int id = -1) |
| QAbstractButton * | button(int id) const |
| QList<QAbstractButton *> | buttons() const |
| QAbstractButton * | checkedButton() const |
| int | checkedId() const |
| bool | exclusive() const |
| int | id(QAbstractButton *button) const |
| void | removeButton(QAbstractButton *button) |
| void | setExclusive(bool) |
| void | setId(QAbstractButton *button, int id) |
信号
| void | buttonClicked(QAbstractButton *button) |
| void | buttonPressed(QAbstractButton *button) |
| void | buttonReleased(QAbstractButton *button) |
| void | buttonToggled(QAbstractButton *button, bool checked) |
| void | idClicked(int id) |
| void | idPressed(int id) |
| void | idReleased(int id) |
| void | idToggled(int id, bool checked) |
详细说明
QButtonGroup 提供了一个抽象容器，用于放置按钮控件。它不提供该容器的视觉呈现（有关容器控件，请参见QGroupBox ），而是负责管理组内每个按钮的状态。
exclusive 按钮组会关闭除被点击的按钮之外的所有可选中（切换）按钮。默认情况下，按钮组具有排他性。 按钮组中的按钮通常是可选中按钮（QPushButton）、非排他性按钮（QCheckBox，通常用于非排他性按钮组）或单选按钮（QRadioButton）。若创建排他性按钮组，应确保组内有一个按钮初始被选中；否则，该组初始状态将处于所有按钮均未被选中的状态。
可通过addButton()将按钮添加到组中，并通过removeButton()将其移除。如果该组为排他组，则可通过checkedButton()获取当前被选中的按钮。当点击某个按钮时，会发出buttonClicked()信号；对于排他组中的可选中按钮，这表示该按钮已被选中。 该组中的按钮列表可通过buttons() 获取。
此外，QButtonGroup 可以在整数和按钮之间建立映射关系。您可以使用setId() 为按钮分配一个整数 ID，并通过id() 获取该 ID。当前选中按钮的 ID 可通过checkedId() 获取，并且有一个名为idClicked() 的信号会发出该按钮的 ID。 ID-1 被 QButtonGroup 保留，表示“无此按钮”。映射机制的目的是简化枚举值在用户界面中的表示。
另请参阅 QGroupBox 、QPushButton 、QCheckBox 以及QRadioButton 。
属性文档
exclusive : bool
该属性用于指定按钮组是否为互斥的
如果此属性为true ，则在任何给定时刻，该组中只能有一个按钮被选中。用户可以点击任意按钮将其选中，该按钮将取代现有选中按钮，成为该组中当前选中的按钮。
在互斥组中，用户无法通过单击当前已选中的按钮来取消其选中状态；相反，必须单击该组中的另一个按钮，才能为该组设置新的选中按钮。
默认情况下，此属性为true 。
Access 函数：
| bool | exclusive() const |
| void | setExclusive(bool) |
成员函数文档
[explicit] QButtonGroup::QButtonGroup(QObject *parent = nullptr)
根据给定的parent ，创建一个新的、空的按钮组。
另请参阅 addButton() 和setExclusive()。
[virtual noexcept] QButtonGroup::~QButtonGroup()
删除该按钮组。
void QButtonGroup::addButton(QAbstractButton *button, int id = -1)
将指定的button 添加到按钮组中。如果id 的值为 -1，则会为该按钮分配一个 ID。自动分配的 ID 保证为负数，从 -2 开始。如果您要自行分配 ID，请使用正数以避免冲突。
另请参阅 removeButton() 和buttons()。
QAbstractButton *QButtonGroup::button(int id) const
返回具有指定id 的按钮；如果不存在该按钮，则返回nullptr 。
[signal] void QButtonGroup::buttonClicked(QAbstractButton *button)
当点击指定的button 时，会触发此信号。按钮的点击操作包括：首次按下并松开按钮、输入其快捷键，或者通过编程方式调用QAbstractButton::click()或QAbstractButton::animateClick()方法。
另请参阅 checkedButton() 和QAbstractButton::clicked()。
[signal] void QButtonGroup::buttonPressed(QAbstractButton *button)
当按下指定的button 时，会发出此信号。
另请参阅 QAbstractButton::pressed()。
[signal] void QButtonGroup::buttonReleased(QAbstractButton *button)
当释放指定的button 时，会发出此信号。
另请参阅 QAbstractButton::released()。
[signal] void QButtonGroup::buttonToggled(QAbstractButton *button, bool checked)
当指定的button 发生状态切换时，会触发此信号。若按钮被选中，checked 为true；若按钮未被选中，则为false。
另请参阅 QAbstractButton::toggled()。
QList<QAbstractButton *> QButtonGroup::buttons() const
返回按钮组的按钮列表。该列表可能为空。
另请参阅 addButton() 和removeButton()。
QAbstractButton *QButtonGroup::checkedButton() const
返回按钮组中被选中的按钮；如果没有按钮被选中，则返回nullptr 。
另请参阅 buttonClicked()。
int QButtonGroup::checkedId() const
返回checkedButton()的ID，如果未选中任何按钮，则返回-1。
另请参阅 setId()。
int QButtonGroup::id(QAbstractButton *button) const
返回指定button 的ID，如果不存在该按钮，则返回-1。
另请参阅 setId()。
[signal] void QButtonGroup::idClicked(int id)
当点击具有指定id 的按钮时，会触发此信号。
另请参阅 checkedButton() 和QAbstractButton::clicked()。
[signal] void QButtonGroup::idPressed(int id)
当按下具有指定id 的按钮时，会发出此信号。
另请参阅 QAbstractButton::pressed()。
[signal] void QButtonGroup::idReleased(int id)
当具有指定id 的按钮被释放时，会触发此信号。
另请参阅 QAbstractButton::released()。
[signal] void QButtonGroup::idToggled(int id, bool checked)
当具有指定id 的按钮被切换时，会触发此信号。若按钮被选中，checked 返回true；若未被选中，则返回false。
另请参阅 QAbstractButton::toggled()。
void QButtonGroup::removeButton(QAbstractButton *button)
将指定的button 从按钮组中移除。
void QButtonGroup::setId(QAbstractButton *button, int id)
设置指定button 的id 。请注意，id 不能为-1。
另请参阅 id()。
© 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.
