【Qt笔记】QCheckBox控件详解

冷眼看人间恩怨

已于 2025-06-26 09:31:36 修改

阅读量4.8k

点赞数 27

CC 4.0 BY-SA版权

分类专栏： Qt 文章标签： qt 笔记开发语言 QCheckBox

于 2024-08-26 16:59:52 首次发布

本文链接：https://blog.csdn.net/qq_52924376/article/details/141566618

Qt 专栏收录该内容

34 篇文章

订阅专栏

4.1 stateChanged(int state)

4.2 toggled(bool checked)

4.3 clicked(bool checked = false)

一、概述

QCheckBox控件是Qt框架中的一个常用控件，用于提供一个可以勾选或取消勾选的复选框，以支持用户从多个选项中选择一个或多个。

二、基本属性

checked：bool型属性，表示复选框的选中状态。当复选框被选中时，该属性为true；否则为false。
text：QString型属性，表示复选框旁边显示的文本。这有助于用户理解复选框所代表的含义。
tristate：bool型属性，表示复选框是否允许有第三种状态（部分选中或未更改状态）。这在某些特定场景下非常有用，比如用户既不想选中也不想取消选中某个选项时。

三、常用方法

3.1 检查选中状态

isChecked()：返回复选框的选中状态。如果复选框被选中，则返回true；否则返回false。

if (checkBox->isChecked()) 
{  
    qDebug() << "Checked";  
}
else 
{  
    qDebug() << "Unchecked";  
}

3.2 设置文本

setText(const QString &text)：设置复选框旁边显示的文本。这有助于用户了解复选框的功能或选项内容。

checkBox->setText("Check Box");

3.3 设置选中状态

setChecked(bool checked)：设置复选框的选中状态。如果参数为true，则复选框被选中；如果为false，则复选框被取消选中。

// 设置复选框的初始状态  
checkBox->setChecked(false); // 初始为未选中

3.4 设置三态

setTristate(bool tristate)：设置复选框是否允许有第三种状态。如果参数为true，则启用三态模式；如果为false，则复选框只有两种状态（选中或未选中）。

//设置三态
checkBox->setTristate(true);

3.5 检查三态返回值

checkState()：在启用了三态模式后，该方法用于查询复选框的当前切换状态。可能的返回值包括Qt::Unchecked（未选中）、Qt::PartiallyChecked（部分选中）和Qt::Checked（选中）。

int state;
// 根据复选框的状态
if (state == Qt::Checked) {
    qDebug() << "Checked";
}
else if(state == Qt::PartiallyChecked){
    qDebug() << "PartiallyChecked";
}
else {
    qDebug() << "Unchecked";
}

四、信号与槽机制

对于QCheckBox控件，最常用的信号是：

4.1 stateChanged(int state)

stateChanged(int state)：

当复选框的选中状态改变时，这个信号会被发射。state参数是一个Qt::CheckState枚举值，它可以是Qt::Unchecked（未选中）、Qt::Checked（选中）或Qt::PartiallyChecked（部分选中，仅当复选框设置为三态时可用）。

4.2 toggled(bool checked)

toggled(bool checked)：

这也是一个当复选框的选中状态改变时发射的信号，但它只提供一个布尔值checked，表示复选框是否处于选中状态（true为选中，false为未选中）。这个信号对于不需要区分三态复选框的场景来说更为直观。

4.3 clicked(bool checked = false)

clicked(bool checked = false)（注意：这个信号实际上是QAbstractButton类的，但QCheckBox继承自QAbstractButton，因此也拥有这个信号）：

当用户点击复选框时，这个信号会被发射。与toggled信号不同，clicked信号在每次点击时都会发射，不论复选框的选中状态是否实际改变（例如，如果复选框已经是选中状态，并且用户再次点击它，它可能会变成未选中状态，但clicked信号仍然会发射）。checked参数是一个默认值，实际上在QCheckBox的上下文中，这个参数通常不会被直接使用，因为你可以通过检查复选框的当前状态来获取这个信息。

五、代码示例

在这个例子中，MainWindow类有一个QCheckBox成员变量checkBox和一个QLabel成员变量label。在构造函数中，我们创建了这两个控件，并使用QVBoxLayout将它们垂直排列。然后，我们使用connect函数将checkBox的stateChanged信号连接到MainWindow类的onCheckBoxStateChanged槽函数。当用户勾选或取消勾选复选框时，stateChanged信号将被发射，并调用onCheckBoxStateChanged槽函数，该函数根据复选框的当前状态更新标签的文本。

5.1 头文件(.h文件)

// MainWindow.h  
#ifndef MAINWINDOW_H  
#define MAINWINDOW_H  
  
#include <QMainWindow>  
#include <QCheckBox>  
#include <QLabel>  
#include <QVBoxLayout>  
#include <QWidget>  
  
class MainWindow : public QMainWindow  
{  
    Q_OBJECT  
  
public:  
    MainWindow(QWidget *parent = nullptr);  
    ~MainWindow();  
  
private slots:  
    void onCheckBoxStateChanged(int state);  
  
private:  
    QCheckBox *checkBox;  
    QLabel *label;  
    QWidget *centralWidget; // 用于布局的小部件，因为QMainWindow默认使用QCentralWidget作为子窗口部件  
    QVBoxLayout *layout; // 垂直布局管理器  
};  
  
#endif // MAINWINDOW_H

5.2 源文件(.cpp文件)

// MainWindow.cpp  
#include "MainWindow.h"  
  
MainWindow::MainWindow(QWidget *parent)  
    : QMainWindow(parent)  
{  
    // 设置中央小部件  
    centralWidget = new QWidget(this);  
    setCentralWidget(centralWidget);  
  
    // 创建布局管理器  
    layout = new QVBoxLayout(centralWidget);  
  
    // 创建复选框  
    checkBox = new QCheckBox("Check me!", centralWidget);  
    // 将复选框的stateChanged信号连接到槽函数  
    connect(checkBox, &QCheckBox::stateChanged, this, &MainWindow::onCheckBoxStateChanged);  

    //设置三态
    checkBox->setTristate(true);
  
    // 创建标签  
    label = new QLabel("Unchecked", centralWidget);  
  
    // 将控件添加到布局中  
    layout->addWidget(checkBox);  
    layout->addWidget(label);  
  
    // 设置窗口的初始大小和标题  
    resize(200, 100);  
    setWindowTitle("QCheckBox Example");  
}  
  
MainWindow::~MainWindow()  
{  
}  
  
void MainWindow::onCheckBoxStateChanged(int state)  
{  
    // 根据复选框的状态更新标签文本
    if (state == Qt::Checked) {
        label->setText("Checked");
    }
    else if(state == Qt::PartiallyChecked){
        label->setText("PartiallyChecked");
    }
    else {
        label->setText("Unchecked");
    }
}

5.3 main函数所在文件

// main.cpp  
#include "MainWindow.h"  
#include <QApplication>  
  
int main(int argc, char *argv[])  
{  
    QApplication a(argc, argv);  
    MainWindow w;  
    w.show();  
    return a.exec();  
}