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

cpp 复制代码

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

cpp 复制代码

#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）自定义外观。

自定义复选框样式：

cpp 复制代码

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

禁用状态样式：

cpp 复制代码

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

悬停效果：

cpp 复制代码

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

自定义字体和颜色：

cpp 复制代码

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

1.6、示例代码

示例 1：多项选择

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

cpp 复制代码

#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：功能开关（三态复选框）

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

cpp 复制代码

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

cpp 复制代码

#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）。
  cpp 复制代码
```
radioButton->setChecked(true);
```
切换状态：
- 方法：toggle()
- 描述：切换单选按钮的选中状态（选中 <=> 未选中）。
  cpp 复制代码
```
radioButton->toggle();
```
设置文本：
- 方法：setText(const QString &text)
- 描述：设置单选按钮的标签文本。
  cpp 复制代码
```
radioButton->setText("Option 1");
```
设置自动互斥：
- 方法：setAutoExclusive(bool exclusive)
- 描述：启用或禁用自动互斥行为。
  cpp 复制代码
```
radioButton->setAutoExclusive(false);
```
获取选中状态：
- 方法：isChecked() const
- 描述：返回单选按钮是否选中（true 或 false）。
  cpp 复制代码
```
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 信号以统一处理一组单选按钮。

cpp 复制代码

#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）自定义外观。

自定义单选按钮样式：

cpp 复制代码

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

禁用状态样式：

cpp 复制代码

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

悬停效果：

cpp 复制代码

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

自定义字体和颜色：

cpp 复制代码

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

2.6、示例代码

示例 1：模式选择对话框

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

cpp 复制代码

#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：动态主题切换

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

cpp 复制代码

#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"

效果：

待补充...

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：本地化支持，处理日期、数字格式等。