Qt Widgets模块功能详细说明，基本控件：QCheckBox（三）

一、基本控件（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"

效果：

---

待补充...

• QComboBox：下拉列表框，支持选择或编辑。

• QLineEdit：单行文本输入框，支持验证和掩码。

• QTextEdit：多行文本编辑器，支持富文本。

• QPlainTextEdit：轻量级纯文本编辑器。

• QSpinBox：整数输入框，带上下箭头。

• QDoubleSpinBox：浮点数输入框。

• QSlider：滑动条，用于选择数值范围。

• QProgressBar：进度条，显示任务进度。

• QDial：旋钮控件，用于调整数值。

• QDateEdit、QTimeEdit、QDateTimeEdit：日期、时间或日期时间输入控件。

• QCalendarWidget：日历控件，用于选择日期。

• QGroupBox：分组框，用于组织控件。

• QFrame：框架控件，支持边框和样式。

• QTabWidget：选项卡控件，支持多页面切换。

• QStackedWidget：堆叠控件，用于切换显示单个页面。

• QToolBox：工具箱控件，类似折叠的选项卡。

二、高级控件（Advanced Widgets）

提供更复杂的功能，适合特定场景。

• QListWidget：列表控件，支持多选和图标。

• QTreeWidget：树形控件，显示分层数据。

• QTableWidget：表格控件，支持单元格编辑。

• QColumnView：列视图，适合分层数据浏览。

• QDockWidget：可停靠窗口，支持浮动和拖动。

• QMdiArea、QMdiSubWindow：多文档界面（MDI）区域和子窗口。

• QTextBrowser：只读富文本浏览器，支持超链接。

• QGraphicsView、QGraphicsScene：图形视图框架，用于2D图形和自定义场景（与Widgets结合使用）。

• QOpenGLWidget：OpenGL渲染窗口，支持3D图形。

三、容器类（Containers）

用于组织和布局其他控件。

• QWidget：所有控件的基类，提供基本窗口功能。

• QMainWindow：主窗口类，提供菜单栏、工具栏和状态栏。

• QDialog：对话框基类，支持模态和非模态。

• QScrollArea：滚动区域，支持大型内容显示。

• QSplitter：分割器，允许用户调整子控件大小。

• QTabBar：选项卡栏，与QTabWidget配合使用。

四、布局管理（Layouts）

用于自动排列控件，适应窗口大小变化。

• QHBoxLayout：水平布局。

• QVBoxLayout：垂直布局。

• QGridLayout：网格布局。

• QFormLayout：表单布局，适合标签-输入对。

• QStackedLayout：堆叠布局，显示单一控件。

• QLayout：布局基类，提供通用布局功能。

五、菜单和工具栏（Menus and Toolbars）

用于创建应用程序的导航和交互功能。

• QMenu：弹出菜单，支持子菜单和动作。

• QMenuBar：菜单栏，位于主窗口顶部。

• QToolBar：工具栏，支持可拖动和浮动。

• QAction：动作抽象，表示菜单项、工具栏按钮等。

六、对话框（Dialogs）

预定义的对话框，用于常见任务。

• QMessageBox：消息框，显示提示、警告或错误。

• QInputDialog：输入对话框，获取用户输入。

• QFileDialog：文件选择对话框。

• QColorDialog：颜色选择对话框。

• QFontDialog：字体选择对话框。

• QProgressDialog：进度对话框，显示任务进度。

• QErrorMessage：错误消息对话框，支持重复消息过滤。

七、事件和交互

支持用户交互和事件处理。

• QEvent：事件基类，用于处理鼠标、键盘等事件。

• QMouseEvent、QKeyEvent：鼠标和键盘事件。

• QDrag、QDropEvent：拖放支持。

• QGestureEvent：手势事件（如触摸设备）。

• QActionEvent：动作触发事件。

八、样式和主题（Styles and Themes）

用于自定义控件外观。

• QStyle：控件绘制基类，支持自定义样式。

• QStyleFactory：创建平台特定样式（如Windows、Fusion）。

• QStyleSheet：通过CSS-like语法自定义控件外观。

• QPalette：颜色配置，用于控件主题。

九、其他功能

• QApplication：应用程序类，管理全局设置和事件循环。

• QClipboard：剪贴板操作，支持文本、图像等。

• QDesktopWidget：访问屏幕信息（如分辨率）。

• QSystemTrayIcon：系统托盘图标支持。

• QStatusBar：状态栏，显示临时信息。

• QWhatsThis：上下文帮助功能。

• QToolTip：工具提示支持。

• QAccessible：辅助功能支持，增强可访问性。

十、模型/视图支持

虽然主要由Qt Model/View模块处理，但Widgets中包含相关控件：

• QListView、QTreeView、QTableView：基于模型的视图控件，与QAbstractItemModel配合使用。

十一、动画和效果

• QPropertyAnimation：属性动画，用于控件动态效果。

• QGraphicsEffect：图形效果，如阴影、模糊（与QGraphicsView结合）。

十二、国际化支持

• QTranslator：支持界面多语言翻译。

• QLocale：本地化支持，处理日期、数字格式等。