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"

效果：