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

    // 创建QCheckBox
    checkBox = 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+C
        encryptCheck->setText("&Encrypt Files"); // Alt+E
        backupCheck->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);

        // 使用 QButtonGroup
        QButtonGroup *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"

效果：