本页内容

QCheckBox Class

QCheckBox 控件提供了一个带有文本标签的复选框。更多内容...

标题: #include <QCheckBox>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
继承自: QAbstractButton

属性

公共函数

QCheckBox(QWidget *parent = nullptr)
QCheckBox(const QString &text, QWidget *parent = nullptr)
virtual ~QCheckBox()
Qt::CheckState checkState() const
bool isTristate() const
void setCheckState(Qt::CheckState state)
void setTristate(bool y = true)

重新实现的公共函数

virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

信号

(since 6.7) void checkStateChanged(Qt::CheckState state)

受保护函数

virtual void initStyleOption(QStyleOptionButton *option) const

重新实现的受保护函数

virtual void checkStateSet() override
virtual bool event(QEvent *e) override
virtual bool hitButton(const QPoint &pos) const override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void nextCheckState() override
virtual void paintEvent(QPaintEvent *) override

详细说明

“保存”选项的复选框

QCheckBox 是一个选项按钮,可以被启用(选中)或禁用(未选中)。 复选框通常用于表示应用程序中那些可以启用或禁用且不会影响其他功能的功能。可以实现不同类型的行为。例如,可以使用QButtonGroup 将复选框进行逻辑分组,从而支持互斥复选框。但是,QButtonGroup 并不提供任何视觉呈现。

下图进一步说明了互斥复选框与非互斥复选框之间的区别。

仅允许选中一个选项的复选框组允许同时选中多个选项的复选框组

每当复选框被选中或取消选中时,它都会发出checkStateChanged() 信号。若希望在复选框状态每次发生变化时触发某个操作,请连接此信号。您可以使用isChecked() 来查询复选框是否已被选中。

除了常见的“已选中”和“未选中”状态外,QCheckBox 还提供了一个可选的第三种状态,用于表示“无变化”。当您需要让用户既不选中也不取消选中复选框时,此功能非常有用。 若需要此第三种状态,请使用setTristate() 启用它,并使用checkState() 查询当前的切换状态。

与QPushButton 一样,复选框会显示文本,并可选地显示一个小图标。图标通过setIcon()设置。文本可在构造函数中设置,也可通过setText()设置。若要在首选字符前添加“&”符号,即可指定快捷键。例如:

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

在此示例中,快捷键为Alt+A。详情请参阅QShortcut 文档。若要显示实际的“&”符号,请使用 '&&'。

另请参阅 QAbstractButton 和QRadioButton 。

属性文档

tristate : bool

该属性用于指定复选框是否为三态复选框

默认值为 false,即该复选框只有两种状态。

访问函数:

bool isTristate() const
void setTristate(bool y = true)

成员函数文档

[explicit] QCheckBox::QCheckBox(QWidget *parent = nullptr)

根据给定的parent 创建一个复选框,但不显示文本。

parent 将该参数传递给QAbstractButton 的构造函数。

[explicit] QCheckBox::QCheckBox(const QString &text, QWidget *parent = nullptr)

根据给定的parent 和text 创建一个复选框。

parent 将传递给QAbstractButton 构造函数。

[virtual noexcept] QCheckBox::~QCheckBox()

析构函数。

Qt::CheckState QCheckBox::checkState() const

返回复选框的选中状态。如果不需要三态支持,也可以使用QAbstractButton::isChecked(),该函数返回一个布尔值。

另请参阅 setCheckState() 和Qt::CheckState 。

[signal, since 6.7] void QCheckBox::checkStateChanged(Qt::CheckState state)

每当复选框的状态发生变化时(即用户勾选或取消勾选时),都会触发此信号。

state 包含复选框的新Qt::CheckState 。

该函数在 Qt 6.7 中引入。

[override virtual protected] void QCheckBox::checkStateSet()

重写了:QAbstractButton::checkStateSet()。

[override virtual protected] bool QCheckBox::event(QEvent *e)

重写了:QAbstractButton::event(QEvent *e)。

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

重写了:QAbstractButton::hitButton(const QPoint &pos) const。

[virtual protected] void QCheckBox::initStyleOption(QStyleOptionButton *option) const

使用此QCheckBox 中的值初始化option 。此方法对于需要QStyleOptionButton 但又不希望自行填写所有信息的子类非常有用。

另请参阅 QStyleOption::initFrom()。

[override virtual] QSize QCheckBox::minimumSizeHint() const

重新实现了属性QWidget::minimumSizeHint 的访问函数。

[override virtual protected] void QCheckBox::mouseMoveEvent(QMouseEvent *e)

重写了:QAbstractButton::mouseMoveEvent(QMouseEvent *e)。

[override virtual protected] void QCheckBox::nextCheckState()

重写了:QAbstractButton::nextCheckState()。

[override virtual protected] void QCheckBox::paintEvent(QPaintEvent *)

重写了:QAbstractButton::paintEvent(QPaintEvent *e)。

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

将复选框的选中状态设置为state 。如果您不需要三态支持,也可以使用QAbstractButton::setChecked(),该函数接受一个布尔值。

另请参阅 checkState() 和Qt::CheckState 。

[override virtual] QSize QCheckBox::sizeHint() const

重新实现了属性QWidget::sizeHint 的访问函数。

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.