Qt 之 QCheckBox Class

详细描述

QCheckBox小部件提供一个带有文本标签的小部件。

QCheckBox是一个选项按钮，可以打开（选中）或关闭（未选中）。复选框通常用于表示可以启用或者禁用而又不会影响其他功能的应用程序特性（功能）。可以实现不同的行为。比如，QButtonGroup可以用于在逻辑上对复选框进行分组，允许排外的复选框。然而，QButtonGroup没有提供任何可视化的表示。

以下截图进一步说明排他的（exclusive）和非排他的（non-exclusive）复选框的区别。

当复选框勾选或者清除时，它都会发出stateChange()信号。如果你想在每次复选框改变状态时触发相关动作就关联这个信号。你可以使用isChecked()去查询复选框被选中与否。

除了常规的勾选和未勾选状态外，QCheckBox还可以提供第三个状态来表示“没有更改”。当你需要用户既不勾选也不清楚复选框控件时，这将会很有用。如果你需要这第三种状态，使用setTristate()使能它，使用checkState()检索当前的开关状态。

和QPushButton一样，一个复选框显示一个文本，也可以选择一个小图标。小图标通过setIcon()设置。文本可以在构造器中设置或者通过setText()设置。快捷键可以通过在字符前添加一个‘&’符号来指定。例如：

  QCheckBox *checkbox = new QCheckBox("C&ase sensitive", this);

在这个例子，快捷键是Alt+A。使用‘&&’来显示一个实际的‘&’符号。

相关属性

tristate:bool

这个属性保存复选框是否是一个三态复选框。

该属性默认是false，也就是说，该复选框只有两种状态。

可访问的函数：

bool  isTristate() const

void setTristate(bool y = true)

相关API

QCheckBox::QCheckBox(QWidget *parent = Q_NULLPTR)

构造一个给定父对象为parent但没有文本的复选框。
参数parent传递到QAbstractButton的构造器。

QCheckBox::QCheckBox(const QString &text, QWidget *parent = Q_NULLPTR)

构造一个给定父对象为parent文本为text的复选框。
参数parent传递到QAbstractButton的构造器。

QCheckBox::~QCheckBox()

析构器。

Qt::CheckState QCheckBox::checkState() const

返回复选框的勾选状态。如果不需要支持三态，你也可以使用QAbstractButton::isChecked(),这个方法返回一个布尔值（boolean）。

[virtual protected] bool QCheckBox::hitButton(const QPoint &pos) const

重新实现QAbstractButton::hitButton()。

如果pos是在可点击按钮矩形内则返回true；否则返回false。

默认地，可点击区域是整个部件。子类可以重新实现这个函数，以支持不同形状和大小的可点击区域。

void QCheckBox::setCheckState(Qt::CheckState state)

设置复选框的勾选状态为state。如果不需要支持三态，你也可以使用QAbstractButton::setChecked(),它接受一个布尔值。

[signal] void QCheckBox::stateChanged(int state)

当复选框的状态改变就会发出这个信号，也就是说，当用户勾选或者清除它。

state包含在复选框的Qt::CheckState（这个枚举值）中。

示例程序

运行结果截屏：

排他的（exclusive）QButtonGroup 一次只会勾选一个复选框，当你勾选其它复选框时会自动把之前勾选的那个复选框的状态给清除掉；非排他的（Non-Exclusive）QButtonGroup里的复选框不会受其他复选框的状态所影响；排他的复选框且里面的复选框都是三态的，则只有未选中态会排他，且当前复选框的状态为未选中状态时，无论你怎么再勾选它都不会有状态改变；非排他的QButtonGroup且里面的复选框都是三态的，则和非排他的QButtonGroup一样，每个复选框互不影响，只是多了一个状态（未选中状态）。

代码解析：

widget.h

#ifndef WIDGET_H
#define WIDGET_H

#include <QWidget>
#include <QVBoxLayout>
#include <QHBoxLayout>

class Widget : public QWidget
{
    Q_OBJECT

public:
    Widget(QWidget *parent = 0);
    ~Widget();

private:
    QVBoxLayout* createExclusiveGroup();
    QVBoxLayout* createNonExclusiveGroup();
    QVBoxLayout* createExclusiveTristateGroup();
    QVBoxLayout* createNonExclusiveTristateGroup();
};

#endif // WIDGET_H

头文件声明四个创建复选框组的接口。

widget.cpp

#include "widget.h"
#include <QLabel>
#include <QCheckBox>
#include <QButtonGroup>


Widget::Widget(QWidget *parent)
    : QWidget(parent)
{
    setFixedSize(400,250);

    QVBoxLayout* vLayout = createExclusiveGroup();
    QVBoxLayout* vLayout1 = createNonExclusiveGroup();
    QVBoxLayout* vLayout2 = createExclusiveTristateGroup();
    QVBoxLayout* vLayout3 = createNonExclusiveTristateGroup();
    QHBoxLayout* hLayout = new QHBoxLayout(this);

    hLayout->addLayout(vLayout);
    hLayout->addLayout(vLayout1);
    hLayout->addLayout(vLayout2);
    hLayout->addLayout(vLayout3);
}

Widget::~Widget()
{

}

/**
 * @brief Widget::createExclusiveGroup
 * 创建排他的QButtonGroup
 * @return
 */
QVBoxLayout* Widget::createExclusiveGroup()
{
    QButtonGroup* buttonGroup = new QButtonGroup(this);
    QVBoxLayout* vLayout = new QVBoxLayout();
    QLabel* label = new QLabel("Exclusive\n    ");
    QCheckBox* baiduCheckBox = new QCheckBox("&Baidu",this);
    QCheckBox* alibabaCheckBox = new QCheckBox("&AliBaBa",this);
    QCheckBox* tencentCheckBox = new QCheckBox("&Tencent",this);

    baiduCheckBox->setTristate(false);
    alibabaCheckBox->setTristate(false);
    tencentCheckBox->setTristate(false);

    vLayout->addWidget(label);
    vLayout->addWidget(baiduCheckBox);
    vLayout->addWidget(alibabaCheckBox);
    vLayout->addWidget(tencentCheckBox);
    vLayout->addSpacerItem(new QSpacerItem(width()/2,height()*3/4));
    //vLayout->setContentsMargins(0,0,0,0);
    vLayout->setSpacing(0);

    buttonGroup->addButton(baiduCheckBox,1);
    buttonGroup->addButton(alibabaCheckBox,2);
    buttonGroup->addButton(tencentCheckBox,3);
    buttonGroup->setExclusive(true);

    return vLayout;
}

/**
 * @brief Widget::createNonExclusiveGroup
 * 创建非排他的QButtonGroup
 * @return
 */
QVBoxLayout* Widget::createNonExclusiveGroup()
{
    QButtonGroup* buttonGroup = new QButtonGroup(this);
    QVBoxLayout* vLayout = new QVBoxLayout();
    QLabel* label = new QLabel("Non-Exclusive\n     ");
    QCheckBox* jayCheckBox = new QCheckBox("周杰伦",this);
    QCheckBox* jjCheckBox = new QCheckBox("林俊杰",this);
    QCheckBox* lrhCheckBox = new QCheckBox("李荣浩",this);

    jayCheckBox->setTristate(false);
    jjCheckBox->setTristate(false);
    lrhCheckBox->setTristate(false);

    vLayout->addWidget(label);
    vLayout->addWidget(jayCheckBox);
    vLayout->addWidget(jjCheckBox);
    vLayout->addWidget(lrhCheckBox);
    vLayout->addSpacerItem(new QSpacerItem(width()/2,height()*3/4));
    //vLayout->setContentsMargins(0,0,0,0);
    vLayout->setSpacing(0);

    buttonGroup->addButton(jayCheckBox,1);
    buttonGroup->addButton(jjCheckBox,2);
    buttonGroup->addButton(lrhCheckBox,3);
    buttonGroup->setExclusive(false);

    return vLayout;
}

/**
 * @brief Widget::createExclusiveTristateGroup
 * 创建排他的QButtonGroup，复选框为三态
 * @return
 */
QVBoxLayout* Widget::createExclusiveTristateGroup()
{
    QButtonGroup* buttonGroup = new QButtonGroup(this);
    QVBoxLayout* vLayout = new QVBoxLayout();
    QLabel* label = new QLabel("Exclusive-\nTristate");
    QCheckBox* cppCheckBox = new QCheckBox("&C++",this);
    QCheckBox* javaCheckBox = new QCheckBox("&Java",this);
    QCheckBox* pythonCheckBox = new QCheckBox("&Python",this);

    cppCheckBox->setTristate(true);
    javaCheckBox->setTristate(true);
    pythonCheckBox->setTristate(true);

    vLayout->addWidget(label);
    vLayout->addWidget(cppCheckBox);
    vLayout->addWidget(javaCheckBox);
    vLayout->addWidget(pythonCheckBox);
    vLayout->addSpacerItem(new QSpacerItem(width()/2,height()*3/4));
    //vLayout->setContentsMargins(0,0,0,0);
    vLayout->setSpacing(0);

    buttonGroup->addButton(cppCheckBox,1);
    buttonGroup->addButton(javaCheckBox,2);
    buttonGroup->addButton(pythonCheckBox,3);
    buttonGroup->setExclusive(true);

    return vLayout;
}

/**
 * @brief Widget::createNonExclusiveTristateGroup
 * 创建非排他的QButtonGroup，复选框为三态
 * @return
 */
QVBoxLayout* Widget::createNonExclusiveTristateGroup()
{
    QButtonGroup* buttonGroup = new QButtonGroup(this);
    QVBoxLayout* vLayout = new QVBoxLayout();
    QLabel* label = new QLabel("Non-Exclusive\nTristate");
    QCheckBox* qqCheckBox = new QCheckBox("QQ",this);
    QCheckBox* weChatCheckBox = new QCheckBox("微信",this);
    QCheckBox* aliPayCheckBox = new QCheckBox("支付宝",this);

    qqCheckBox->setTristate(true);
    weChatCheckBox->setTristate(true);
    aliPayCheckBox->setTristate(true);

    vLayout->addWidget(label);
    vLayout->addWidget(qqCheckBox);
    vLayout->addWidget(weChatCheckBox);
    vLayout->addWidget(aliPayCheckBox);
    vLayout->addSpacerItem(new QSpacerItem(width()/2,height()*3/4));
    //vLayout->setContentsMargins(0,0,0,0);
    vLayout->setSpacing(0);

    buttonGroup->addButton(qqCheckBox,1);
    buttonGroup->addButton(weChatCheckBox,2);
    buttonGroup->addButton(aliPayCheckBox,3);
    buttonGroup->setExclusive(false);

    return vLayout;
}

源文件主要实现这四个接口，每个接口的都是添加三个复选框和一个标签，唯一不同的是对QButtonGroup的exclusive（排他属性）和QCheckBox的tristate(三态)属性设置的不同。

代码下载地址： QCheckBox使用例子