当前位置：首页 > news >正文

【Qt笔记】QCheckBox控件详解

news 2025/7/23 22:19:26

一、概述

二、基本属性

三、常用方法

3.1 检查选中状态

3.2 设置文本

3.3 设置选中状态

3.4 设置三态

3.5 检查三态返回值

四、信号与槽机制

4.1 stateChanged(int state)

4.2 toggled(bool checked)

4.3 clicked(bool checked = false)

五、代码示例

5.1 头文件(.h文件)

5.2 源文件(.cpp文件)

5.3 main函数所在文件

5.4 实现效果

六、结语

一、概述

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