一、基本控件（Widgets）

Qt 提供了丰富的基本控件，如按钮、标签、文本框、复选框、单选按钮、列表框、组合框、菜单、工具栏等。

1、QCheckBox

1.1、概述 (用途、状态、继承关系)

QCheckBox 是 Qt 框架中的复选框控件，用于表示二值或三值状态的选择（选中、未选中、部分选中）。

多选场景：如列表中的多项选择（例如文件选择器中的批量操作）。
功能开关：如设置对话框中的选项（例如“启用自动保存”）。
状态指示：表示某些功能的启用/禁用状态。

QCheckBox 支持以下状态：

Qt::Unchecked：未选中（值：0）。
Qt::Checked：选中（值：2）。
Qt::PartiallyChecked：部分选中（值：1，仅在三态模式下有效）。

继承关系

QCheckBox 继承自以下类（基于 Qt 的 C++ 继承链）：

QAbstractButton：提供按钮的通用功能（如点击、按下、释放、复选等）。
QWidget：提供基本窗口部件功能（如大小、位置、事件处理）。
QObject：提供信号与槽机制、事件系统等。

QCheckBox除基础功能外，还扩展了复选框特定的状态管理和三态支持。

1.2、常用属性 (文本、状态、是否三态等)

QCheckBox 提供多种属性，用于控制其外观和行为。

文本（text）：
- 属性：text（类型：QString）
- 描述：设置复选框旁边的标签文本。
- 示例：checkBox->setText("Enable Auto-Save");
状态（checkState）：
- 属性：checkState（类型：Qt::CheckState）
- 描述：设置或获取复选框的状态（Qt::Unchecked, Qt::Checked, Qt::PartiallyChecked）。
- 示例：checkBox->setCheckState(Qt::Checked);
是否三态（tristate）：
- 属性：tristate（类型：bool）
- 描述：启用三态模式，允许 PartiallyChecked 状态，常用于表示部分选中的情况（如树形控件中的父节点）。默认关闭。
- 示例：checkBox->setTristate(true);
启用状态（enabled）：
- 属性：enabled（类型：bool）
- 描述：控制复选框是否可交互，禁用时呈灰色。
- 示例：checkBox->setEnabled(false);
工具提示（toolTip）：
- 属性：toolTip（类型：QString）
- 描述：设置鼠标悬停时的提示文本。
- 示例：checkBox->setToolTip("Toggle auto-save feature");
快捷键（shortcut）：
- 属性：通过 setText 中的 & 设置快捷键。
- 描述：为复选框绑定快捷键，点击 Alt+键触发切换。
- 示例：checkBox->setText("&Auto-Save"); // Alt+A 触发
图标（icon）：
- 属性：icon（类型：QIcon）
- 描述：设置复选框的图标（较少使用，但可自定义）。
- 示例：checkBox->setIcon(QIcon(":/icons/checkbox.png"));

#include <QApplication>
#include <QWidget>
#include <QVBoxLayout>
#include <QCheckBox>
#include <QIcon>
#include <QPixmap>int main(int argc, char *argv[])
{QApplication a(argc, argv);// 创建主窗口QWidget window;window.setWindowTitle("QCheckBox 示例");// 创建垂直布局QVBoxLayout *layout = new QVBoxLayout(&window);//=========================// 1. 文本 (text)//=========================QCheckBox *checkBoxText = new QCheckBox("设置复选框文本");layout->addWidget(checkBoxText);//=========================// 2. 状态 (checkState)//=========================QCheckBox *checkBoxState = new QCheckBox("设置复选框状态");checkBoxState->setCheckState(Qt::Checked); // 设置为选中状态// 也可以使用 setChecked(bool) 对于两态复选框// checkBoxState->setChecked(true);layout->addWidget(checkBoxState);//===============================// 3. 是否三态 (tristate)//===============================QCheckBox *checkBoxTristate = new QCheckBox("三态复选框");checkBoxTristate->setTristate(true); // 启用三态模式checkBoxTristate->setCheckState(Qt::PartiallyChecked); // 设置为部分选中状态layout->addWidget(checkBoxTristate);//===================================// 4. 启用状态 (enabled)//===================================QCheckBox *checkBoxEnabled = new QCheckBox("启用状态");checkBoxEnabled->setEnabled(false); // 设置为禁用状态layout->addWidget(checkBoxEnabled);// 5. 工具提示 (toolTip)QCheckBox *checkBoxToolTip = new QCheckBox("带有工具提示");checkBoxToolTip->setToolTip("鼠标悬停时显示的提示文本"); // 设置工具提示layout->addWidget(checkBoxToolTip);//==================================// 6. 快捷键 (shortcut)//==================================// 通过在文本中放置 '&' 来设置快捷键，紧跟在 '&' 后面的字符成为快捷键QCheckBox *checkBoxShortcut = new QCheckBox("带有快捷键 (Alt+&Q)");layout->addWidget(checkBoxShortcut);//==================================// 7. 图标 (icon)//==================================QCheckBox *checkBoxIcon = new QCheckBox("带有图标");// 为了演示，这里创建一个简单的QIcon。在实际应用中，您会从资源文件或文件中加载图标。QPixmap pixmap(16, 16);pixmap.fill(Qt::blue); // 填充一个颜色作为示例图标QIcon icon(pixmap);checkBoxIcon->setIcon(icon); // 设置图标layout->addWidget(checkBoxIcon);// 显示窗口window.show();return a.exec();
}

效果：

1.3、常用方法 (设置状态、切换状态)

设置状态：
- 方法：setCheckState(Qt::CheckState state)
- 描述：设置复选框的状态（Unchecked, Checked, PartiallyChecked）。
```
checkBox->setCheckState(Qt::Checked);
```
设置选中状态：
- 方法：setChecked(bool checked)
- 描述：设置复选框为选中（true）或未选中（false）。等效于 setCheckState(Qt::Checked) 或 setCheckState(Qt::Unchecked)。
```
checkBox->setChecked(true);
```
切换状态：
- 方法：toggle()
- 描述：切换复选框的选中状态（选中 <=> 未选中）
- 注意：toggle() 会根据当前状态在 Unchecked, PartiallyChecked, Checked 之间切换（如果启用了三态）。
```
checkBox->toggle();
```
设置文本：
- 方法：setText(const QString &text)
- 描述：设置复选框的标签文本。
```
checkBox->setText("Enable Feature");
```
设置三态模式：
- 方法：setTristate(bool y)
- 描述：启用或禁用三态模式。
```
checkBox->setTristate(true);
```
获取状态：
- 方法：checkState() const
- 描述：返回当前状态（Qt::CheckState）。
```
Qt::CheckState state = checkBox->checkState();
```

1.4、常用信号 (状态改变、点击等)

QCheckBox 继承了 QAbstractButton 的信号，并添加了复选框特定的信号。

stateChanged(int state)：
- 描述：当复选框状态改变时发出，参数为新的状态（Qt::CheckState 的整数值：0、1、2）。
- 示例：connect(checkBox, &QCheckBox::stateChanged, this, &MyClass::onCheckBoxStateChanged);
clicked(bool checked)：
- 描述：当复选框被点击时发出，参数表示是否选中。
- 示例：connect(checkBox, &QCheckBox::clicked, this, &MyClass::onCheckBoxClicked);
toggled(bool checked)：
- 描述：当复选框的选中状态改变时发出，参数表示是否选中（仅适用于二态复选框）。
- 示例：connect(checkBox, &QCheckBox::toggled, this, &MyClass::onCheckBoxToggled);

注意：

stateChanged 适用于三态复选框，toggled 更适合二态复选框。
clicked 仅在用户点击时触发，而 stateChanged 和 toggled 会在程序设置状态（如 setChecked）时也触发。

#include <QApplication>
#include <QWidget>
#include <QCheckBox>
#include <QLabel>
#include <QVBoxLayout>
#include <QDebug> // 用于输出状态class MyWidget : public QWidget
{Q_OBJECT // 必须包含这个宏以便使用信号和槽public:MyWidget(QWidget *parent = nullptr);~MyWidget();private slots:// 槽函数，用于接收 stateChanged 信号void onCheckBoxStateChanged(int state);// 槽函数，用于接收 clicked 信号void onCheckBoxClicked(bool checked);// 槽函数，用于接收 toggled 信号void onCheckBoxToggled(bool checked);private:QCheckBox *checkBox;QLabel *stateLabel;QLabel *clickedLabel;QLabel *toggledLabel;
};// 实现 MyWidget 类的构造函数
MyWidget::MyWidget(QWidget *parent): QWidget(parent)
{setWindowTitle("QCheckBox 方法和信号示例");QVBoxLayout *layout = new QVBoxLayout(this);// 创建QCheckBoxcheckBox = new QCheckBox("示例复选框");layout->addWidget(checkBox);// 创建标签用于显示信号信息stateLabel = new QLabel("stateChanged: 未触发");layout->addWidget(stateLabel);clickedLabel = new QLabel("clicked: 未触发");layout->addWidget(clickedLabel);toggledLabel = new QLabel("toggled: 未触发");layout->addWidget(toggledLabel);//=============================================// --- 演示 QCheckBox 的常用方法 ---//=============================================// 设置文本checkBox->setText("点击我来改变状态");// 设置三态模式 (可选，这里启用以便演示三态)checkBox->setTristate(true);// 设置初始状态checkBox->setCheckState(Qt::Unchecked);// 或者使用 setChecked(false);//==========================================// --- 连接常用信号和槽 ---//==========================================// 连接 stateChanged 信号connect(checkBox, &QCheckBox::stateChanged, this, &MyWidget::onCheckBoxStateChanged);// 连接 clicked 信号connect(checkBox, &QCheckBox::clicked, this, &MyWidget::onCheckBoxClicked);// 连接 toggled 信号// 注意：toggled 信号只在选中状态（Checked/Unchecked）之间切换时发出，// 如果启用了三态且状态变为 PartiallyChecked，状态切换需要判断state后再做具体处理connect(checkBox, &QCheckBox::toggled, this, &MyWidget::onCheckBoxToggled);
}// 实现 MyWidget 类的析构函数
MyWidget::~MyWidget()
{// Qt 的父子对象机制会自动删除子对象，所以这里通常不需要手动删除 checkBox, stateLabel 等
}// stateChanged 信号的槽函数实现
void MyWidget::onCheckBoxStateChanged(int state)
{QString stateText;switch (state) {case Qt::Unchecked:stateText = "Qt::Unchecked (0)";break;case Qt::PartiallyChecked:stateText = "Qt::PartiallyChecked (1)";break;case Qt::Checked:stateText = "Qt::Checked (2)";break;default:stateText = "未知状态";break;}stateLabel->setText("stateChanged: 状态改变为 " + stateText);qDebug() << "stateChanged emitted with state:" << state;
}// clicked 信号的槽函数实现
void MyWidget::onCheckBoxClicked(bool checked)
{clickedLabel->setText(QString("clicked: 复选框被点击，checked = %1").arg(checked));qDebug() << "clicked emitted with checked:" << checked;
}// toggled 信号的槽函数实现
void MyWidget::onCheckBoxToggled(bool checked)
{toggledLabel->setText(QString("toggled: 选中状态改变为 %1").arg(checked));qDebug() << "toggled emitted with checked:" << checked;
}// main 函数
int main(int argc, char *argv[])
{QApplication a(argc, argv);MyWidget window;window.show();return a.exec();
}#include "main.moc" // 在包含 Q_OBJECT 的文件末尾需要包含 moc_filename.cpp，或者对于单个文件，通常是 main.moc

1.5、样式表应用

QCheckBox 支持 Qt 样式表（QSS）自定义外观。

自定义复选框样式：

checkBox->setStyleSheet("QCheckBox {""   color: #333;""   font-size: 14px;""   spacing: 5px;" // 图标和文本间距"}""QCheckBox::indicator {""   width: 16px;""   height: 16px;""}""QCheckBox::indicator:checked {""   image: url(:/icons/checked.png);""}""QCheckBox::indicator:unchecked {""   image: url(:/icons/unchecked.png);""}""QCheckBox::indicator:indeterminate {""   image: url(:/icons/partially_checked.png);""}"
);

禁用状态样式：

checkBox->setStyleSheet("QCheckBox:disabled {""   color: #999;""   background-color: #F0F0F0;""}"
);

悬停效果：

checkBox->setStyleSheet("QCheckBox:hover {""   background-color: #E6F3FF;""}"
);

自定义字体和颜色：

checkBox->setStyleSheet("QCheckBox {""   font: bold 12px Arial;""   color: #0066CC;""}"
);

1.6、示例代码

示例 1：多项选择

创建一个对话框，包含多个复选框，用于选择文件处理选项。

#include <QApplication>
#include <QDialog>
#include <QVBoxLayout>
#include <QCheckBox>
#include <QPushButton>
#include <QMessageBox>class OptionsDialog : public QDialog {Q_OBJECT
public:OptionsDialog(QWidget *parent = nullptr) : QDialog(parent) {setWindowTitle("File Processing Options");QVBoxLayout *layout = new QVBoxLayout(this);// 创建复选框compressCheck = new QCheckBox("Compress Files", this);encryptCheck = new QCheckBox("Encrypt Files", this);backupCheck = new QCheckBox("Create Backup", this);// 设置快捷键compressCheck->setText("&Compress Files"); // Alt+CencryptCheck->setText("&Encrypt Files"); // Alt+EbackupCheck->setText("&Backup Files"); // Alt+B// 设置初始状态compressCheck->setChecked(true);backupCheck->setChecked(true);// 添加到布局layout->addWidget(compressCheck);layout->addWidget(encryptCheck);layout->addWidget(backupCheck);// 确认按钮QPushButton *confirmButton = new QPushButton("Confirm", this);layout->addWidget(confirmButton);// 连接信号connect(confirmButton, &QPushButton::clicked, this, &OptionsDialog::onConfirmClicked);}private slots:void onConfirmClicked() {QString options;if (compressCheck->isChecked()) options += "Compress Files\n";if (encryptCheck->isChecked()) options += "Encrypt Files\n";if (backupCheck->isChecked()) options += "Create Backup\n";QMessageBox::information(this, "Selected Options", options.isEmpty() ? "No options selected" : options);}private:QCheckBox *compressCheck;QCheckBox *encryptCheck;QCheckBox *backupCheck;
};int main(int argc, char *argv[]) {QApplication app(argc, argv);OptionsDialog dialog;dialog.exec();return app.exec();
}#include "main.moc"

效果：

示例 2：功能开关（三态复选框）

创建一个设置面板，包含一个三态复选框，用于控制子选项的启用状态。

#include <QApplication>
#include <QMainWindow>
#include <QCheckBox>
#include <QVBoxLayout>
#include <QWidget>
#include <QMessageBox>class MainWindow : public QMainWindow {Q_OBJECT
public:MainWindow(QWidget *parent = nullptr) : QMainWindow(parent) {QWidget *centralWidget = new QWidget(this);setCentralWidget(centralWidget);QVBoxLayout *layout = new QVBoxLayout(centralWidget);// 主复选框（三态）masterCheck = new QCheckBox("Enable Features", this);masterCheck->setTristate(true);masterCheck->setCheckState(Qt::PartiallyChecked);// 子复选框feature1Check = new QCheckBox("Feature 1", this);feature2Check = new QCheckBox("Feature 2", this);// 添加到布局layout->addWidget(masterCheck);layout->addWidget(feature1Check);layout->addWidget(feature2Check);// 连接信号connect(masterCheck, &QCheckBox::stateChanged, this, &MainWindow::onMasterCheckStateChanged);connect(feature1Check, &QCheckBox::toggled, this, &MainWindow::onFeatureCheckToggled);connect(feature2Check, &QCheckBox::toggled, this, &MainWindow::onFeatureCheckToggled);}private slots:void onMasterCheckStateChanged(int state) {if (state == Qt::Checked) {feature1Check->setChecked(true);feature2Check->setChecked(true);} else if (state == Qt::Unchecked) {feature1Check->setChecked(false);feature2Check->setChecked(false);}// PartiallyChecked 不改变子选项}void onFeatureCheckToggled() {bool f1 = feature1Check->isChecked();bool f2 = feature2Check->isChecked();if (f1 && f2) {masterCheck->setCheckState(Qt::Checked);} else if (!f1 && !f2) {masterCheck->setCheckState(Qt::Unchecked);} else {masterCheck->setCheckState(Qt::PartiallyChecked);}}private:QCheckBox *masterCheck;QCheckBox *feature1Check;QCheckBox *feature2Check;
};int main(int argc, char *argv[]) {QApplication app(argc, argv);MainWindow window;window.resize(300, 200);window.show();return app.exec();
}#include "main.moc"

效果：

2、QRadioButton

2.1、概述 (用途、互斥性、继承关系)

QRadioButton 是 Qt 框架中的单选按钮控件，用于表示一组互斥选项中的单一选择。用户只能从一组单选按钮中选择一个选项，常用于：

单项选择场景：如选择性别、文件类型、模式切换（例如“普通模式”或“高级模式”）。
设置面板：在配置对话框中选择独占选项（如主题选择：亮色、暗色）。
表单输入：收集用户单一偏好或设置。

互斥性

QRadioButton 通常与 QButtonGroup 结合使用，以确保一组单选按钮互斥（即只能有一个按钮被选中）。
没有 QButtonGroup 时，单选按钮的互斥性依赖于父控件（同一父窗口下的 QRadioButton 默认互斥）。

继承关系

QRadioButton 继承自以下类（基于 Qt 的 C++ 继承链）：

QAbstractButton：提供按钮的通用功能（如点击、按下、释放、复选等）。
QWidget：提供基本窗口部件功能（如大小、位置、事件处理）。
QObject：提供信号与槽机制、事件系统等。

QRadioButton 继承了 QAbstractButton 的基本功能（如文本、图标、点击信号等），并扩展了单选按钮特定的互斥行为。

2.2、常用属性 (文本、是否选中等)

QRadioButton 提供多种属性，用于控制其外观和行为。

文本（text）：
- 属性：text（类型：QString）
- 描述：设置单选按钮旁边的标签文本。
- 示例：radioButton->setText("Option 1");
是否选中（checked）：
- 属性：checked（类型：bool）
- 描述：设置或获取单选按钮的选中状态（true 表示选中，false 表示未选中）。
- 示例：radioButton->setChecked(true);
启用状态（enabled）：
- 属性：enabled（类型：bool）
- 描述：控制单选按钮是否可交互，禁用时呈灰色。
- 示例：radioButton->setEnabled(false);
工具提示（toolTip）：
- 属性：toolTip（类型：QString）
- 描述：设置鼠标悬停时的提示文本。
- 示例：radioButton->setToolTip("Select this option for basic mode");
快捷键（shortcut）：
- 属性：通过 setText 中的 & 设置快捷键。
- 描述：为单选按钮绑定快捷键，点击 Alt+键触发选中。
- 示例：radioButton->setText("&Basic Mode"); // Alt+B 触发
自动互斥（autoExclusive）：
- 属性：autoExclusive（类型：bool）
- 描述：启用时，同一父控件下的 QRadioButton 自动互斥（默认开启）。禁用后，允许多个单选按钮同时选中。
- 示例：radioButton->setAutoExclusive(false);
图标（icon）：
- 属性：icon（类型：QIcon）
- 描述：设置单选按钮的图标（较少使用，但可自定义）。
- 示例：radioButton->setIcon(QIcon(":/icons/radio.png"));

#include <QApplication>
#include <QWidget>
#include <QVBoxLayout>
#include <QRadioButton>
#include <QButtonGroup>
#include <QIcon>
#include <QLabel>
#include <QPixmap> // 用于创建示例图标int main(int argc, char *argv[])
{QApplication a(argc, argv);// 创建主窗口QWidget window;window.setWindowTitle("QRadioButton 示例");// 创建垂直布局QVBoxLayout *layout = new QVBoxLayout(&window);//======================// 1. 文本 (text)//======================QRadioButton *radioButtonText = new QRadioButton("设置单选按钮文本");layout->addWidget(radioButtonText);//==========================// 2. 是否选中 (checked)//==========================QRadioButton *radioButtonChecked = new QRadioButton("设置选中状态");radioButtonChecked->setChecked(true); // 设置为选中状态layout->addWidget(radioButtonChecked);//=============================// 3. 启用状态 (enabled)//=============================QRadioButton *radioButtonEnabled = new QRadioButton("启用状态false");radioButtonEnabled->setEnabled(false); // 设置为禁用状态layout->addWidget(radioButtonEnabled);//===============================// 4. 工具提示 (toolTip)//===============================QRadioButton *radioButtonToolTip = new QRadioButton("带有工具提示");radioButtonToolTip->setToolTip("鼠标悬停时显示的提示文本"); // 设置工具提示layout->addWidget(radioButtonToolTip);//===================================// 5. 快捷键 (shortcut)//===================================// 通过在文本中放置 '&' 来设置快捷键，紧跟在 '&' 后面的字符成为快捷键QRadioButton *radioButtonShortcut = new QRadioButton("带有快捷键 (Alt+&S)");layout->addWidget(radioButtonShortcut);//=============================// 6. 图标 (icon)//=============================QRadioButton *radioButtonIcon = new QRadioButton("带有图标");QPixmap pixmap(16, 16);pixmap.fill(Qt::red); // 填充一个颜色作为示例图标QIcon icon(pixmap);radioButtonIcon->setIcon(icon); // 设置图标layout->addWidget(radioButtonIcon);//=======================================// 7. 自动互斥 (autoExclusive)//=======================================// 注意：autoExclusive 通常在同一父控件下多个单选按钮一起使用时才明显。// 默认情况下，同一父控件下的 QRadioButton 是自动互斥的。// 这里创建一个禁用了自动互斥的示例（虽然单独一个看不出效果）。QRadioButton *radioButtonAutoExclusive = new QRadioButton("禁用自动互斥 (不常用)");radioButtonAutoExclusive->setAutoExclusive(false); // 禁用自动互斥layout->addWidget(radioButtonAutoExclusive);// 为了更好地演示 autoExclusive，创建一组互斥的单选按钮QButtonGroup  *buttonGroup =new QButtonGroup(&window);QRadioButton *radioButtonGroup1 = new QRadioButton("组1 选项A");QRadioButton *radioButtonGroup2 = new QRadioButton("组1 选项B");QRadioButton *radioButtonGroup3 = new QRadioButton("组1 选项C");radioButtonGroup1->setChecked(true); // 默认选中组1的一个layout->addWidget(new QLabel("===自动互斥组 (默认行为)====")); // 添加一个标签说明layout->addWidget(radioButtonGroup1);layout->addWidget(radioButtonGroup2);layout->addWidget(radioButtonGroup3);buttonGroup->addButton(radioButtonGroup1);buttonGroup->addButton(radioButtonGroup2);buttonGroup->addButton(radioButtonGroup3);// 显示窗口window.show();return a.exec();
}

效果：

2.3、常用方法 (设置选中状态)

设置选中状态：
- 方法：setChecked(bool checked)
- 描述：设置单选按钮为选中（true）或未选中（false）。
```
radioButton->setChecked(true);
```
切换状态：
- 方法：toggle()
- 描述：切换单选按钮的选中状态（选中 <=> 未选中）。
```
radioButton->toggle();
```
设置文本：
- 方法：setText(const QString &text)
- 描述：设置单选按钮的标签文本。
```
radioButton->setText("Option 1");
```
设置自动互斥：
- 方法：setAutoExclusive(bool exclusive)
- 描述：启用或禁用自动互斥行为。
```
radioButton->setAutoExclusive(false);
```
获取选中状态：
- 方法：isChecked() const
- 描述：返回单选按钮是否选中（true 或 false）。
```
bool checked = radioButton->isChecked();
```

2.4、常用信号 (点击、切换状态等)

QRadioButton 继承了 QAbstractButton 的信号，常用信号包括：

toggled(bool checked)：
- 描述：当单选按钮的选中状态改变时发出，参数表示是否选中。
- 示例：connect(radioButton, &QRadioButton::toggled, this, &MyClass::onRadioToggled);
clicked(bool checked)：
- 描述：当单选按钮被点击时发出，参数表示是否选中。
- 示例：connect(radioButton, &QRadioButton::clicked, this, &MyClass::onRadioClicked);

注意：

toggled 在程序设置状态（如 setChecked）或用户交互时都会触发。
clicked 仅在用户点击时触发。
当使用 QButtonGroup 时，推荐连接 QButtonGroup::buttonToggled 或 idToggled 信号以统一处理一组单选按钮。

#include <QApplication>
#include <QWidget>
#include <QRadioButton>
#include <QButtonGroup>
#include <QLabel>
#include <QVBoxLayout>
#include <QDebug>class MyButtonGroupWidget : public QWidget
{Q_OBJECT // 必须包含这个宏以便使用信号和槽public:MyButtonGroupWidget(QWidget *parent = nullptr);~MyButtonGroupWidget(){}private slots:// 槽函数，用于接收 QButtonGroup 的 idToggled 信号 (如果给按钮设置了ID)void onButtonGroupIdToggled(int id, bool checked);private:QButtonGroup *buttonGroup;QRadioButton *radioA;QRadioButton *radioB;QRadioButton *radioC;
};MyButtonGroupWidget::MyButtonGroupWidget(QWidget *parent): QWidget(parent)
{setWindowTitle("QButtonGroup 示例");QVBoxLayout *layout = new QVBoxLayout(this);buttonGroup = new QButtonGroup(this);// 创建 QRadioButton 实例radioA = new QRadioButton("选项 A");radioB = new QRadioButton("选项 B");radioC = new QRadioButton("选项 C");// 将单选按钮添加到布局中 (QButtonGroup 不管理布局)layout->addWidget(new QLabel("选择一个选项:")); // 添加一个标签说明layout->addWidget(radioA);layout->addWidget(radioB);layout->addWidget(radioC);// 将单选按钮添加到 QButtonGroup 添加到组后，它们将自动互斥（因为 QButtonGroup 默认 exclusive）buttonGroup->addButton(radioA, 1); // 同时为按钮设置一个ID (可选)buttonGroup->addButton(radioB, 2);buttonGroup->addButton(radioC, 3);// 设置默认选中的按钮radioA->setChecked(true); // 或者 buttonGroup->button(1)->setChecked(true);// 连接 idToggled 信号 (如果我们为按钮设置了ID)connect(buttonGroup, &QButtonGroup::idToggled, this, &MyButtonGroupWidget::onButtonGroupIdToggled);}// idToggled 信号的槽函数实现
void MyButtonGroupWidget::onButtonGroupIdToggled(int id, bool checked)
{if (checked) {QString buttonText;// 根据ID查找按钮并获取其文本QAbstractButton *button = buttonGroup->button(id);if (button) {buttonText = button->text();} else {buttonText = "未知按钮";}qDebug() << "idToggled emitted: Button with ID" << id << "(" << buttonText << ")" << "is checked.";} else {qDebug() << "idToggled emitted: Button with ID" << id << "is unchecked.";}
}// main 函数
int main(int argc, char *argv[])
{QApplication a(argc, argv);MyButtonGroupWidget window;window.show();return a.exec();
}#include "main.moc"

效果：

2.5、样式表应用

QRadioButton 支持 Qt 样式表（QSS）自定义外观。

自定义单选按钮样式：

radioButton->setStyleSheet("QRadioButton {""   color: #333;""   font-size: 14px;""   spacing: 5px;" // 图标和文本间距"}""QRadioButton::indicator {""   width: 16px;""   height: 16px;""}""QRadioButton::indicator:checked {""   image: url(:/icons/radio_checked.png);""}""QRadioButton::indicator:unchecked {""   image: url(:/icons/radio_unchecked.png);""}"
);

禁用状态样式：

radioButton->setStyleSheet("QRadioButton:disabled {""   color: #999;""   background-color: #F0F0F0;""}"
);

悬停效果：

radioButton->setStyleSheet("QRadioButton:hover {""   background-color: #E6F3FF;""}"
);

自定义字体和颜色：

radioButton->setStyleSheet("QRadioButton {""   font: bold 12px Arial;""   color: #0066CC;""}"
);

2.6、示例代码

示例 1：模式选择对话框

创建一个对话框，允许用户选择应用程序模式（基本、高级、自定义）。

#include <QApplication>
#include <QDialog>
#include <QVBoxLayout>
#include <QRadioButton>
#include <QButtonGroup>
#include <QPushButton>
#include <QMessageBox>class ModeDialog : public QDialog {Q_OBJECT
public:ModeDialog(QWidget *parent = nullptr) : QDialog(parent) {setWindowTitle("Select Mode");QVBoxLayout *layout = new QVBoxLayout(this);// 创建单选按钮basicRadio = new QRadioButton("&Basic Mode", this);advancedRadio = new QRadioButton("&Advanced Mode", this);customRadio = new QRadioButton("&Custom Mode", this);// 设置工具提示basicRadio->setToolTip("Simple mode for beginners");advancedRadio->setToolTip("Advanced mode with more features");customRadio->setToolTip("Customizable mode for experts");// 默认选中basicRadio->setChecked(true);// 使用 QButtonGroup 确保互斥QButtonGroup *modeGroup = new QButtonGroup(this);modeGroup->addButton(basicRadio, 1);modeGroup->addButton(advancedRadio, 2);modeGroup->addButton(customRadio, 3);// 添加到布局layout->addWidget(basicRadio);layout->addWidget(advancedRadio);layout->addWidget(customRadio);// 确认按钮QPushButton *confirmButton = new QPushButton("Confirm", this);layout->addWidget(confirmButton);// 连接信号connect(modeGroup, &QButtonGroup::idToggled, this, &ModeDialog::onModeToggled);connect(confirmButton, &QPushButton::clicked, this, &ModeDialog::onConfirmClicked);}private slots:void onModeToggled(int id, bool checked) {if (checked) {QString mode;switch (id) {case 1: mode = "Basic Mode"; break;case 2: mode = "Advanced Mode"; break;case 3: mode = "Custom Mode"; break;}QMessageBox::information(this, "Mode Selected", "Mode: " + mode);}}void onConfirmClicked() {QString mode = basicRadio->isChecked() ? "Basic Mode" :advancedRadio->isChecked() ? "Advanced Mode" : "Custom Mode";QMessageBox::information(this, "Confirmed", "Selected: " + mode);accept();}private:QRadioButton *basicRadio;QRadioButton *advancedRadio;QRadioButton *customRadio;
};int main(int argc, char *argv[]) {QApplication app(argc, argv);ModeDialog dialog;dialog.exec();return app.exec();
}#include "main.moc"

效果：

示例 2：动态主题切换

创建一个主窗口，包含单选按钮切换界面主题（亮色、暗色）。

#include <QApplication>
#include <QMainWindow>
#include <QVBoxLayout>
#include <QRadioButton>
#include <QButtonGroup>
#include <QWidget>class MainWindow : public QMainWindow {Q_OBJECT
public:MainWindow(QWidget *parent = nullptr) : QMainWindow(parent) {QWidget *centralWidget = new QWidget(this);setCentralWidget(centralWidget);QVBoxLayout *layout = new QVBoxLayout(centralWidget);// 创建单选按钮lightRadio = new QRadioButton("Light Theme", this);darkRadio = new QRadioButton("Dark Theme", this);// 默认选中lightRadio->setChecked(true);// 使用 QButtonGroupQButtonGroup *themeGroup = new QButtonGroup(this);themeGroup->addButton(lightRadio);themeGroup->addButton(darkRadio);// 添加到布局layout->addWidget(lightRadio);layout->addWidget(darkRadio);layout->addStretch();// 连接信号connect(themeGroup, &QButtonGroup::idToggled, this, &MainWindow::onThemeToggled);// 设置初始样式updateTheme();}private slots:void onThemeToggled(int buttonID, bool checked) {if (checked) {updateTheme();}}private:void updateTheme() {if (lightRadio->isChecked()) {qApp->setStyleSheet("QMainWindow { background-color: #FFFFFF; }""QRadioButton { color: #000000; }");} else if (darkRadio->isChecked()) {qApp->setStyleSheet("QMainWindow { background-color: #333333; }""QRadioButton { color: #FFFFFF; }");}}private:QRadioButton *lightRadio;QRadioButton *darkRadio;
};int main(int argc, char *argv[]) {QApplication app(argc, argv);MainWindow window;window.resize(300, 200);window.show();return app.exec();
}#include "main.moc"

效果：