1// Copyright (C) 2017 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qquickcheckbox_p.h"
5#include "qquickabstractbutton_p_p.h"
6
7#include <QtGui/qpa/qplatformtheme.h>
8#include <QtQml/qjsvalue.h>
9
10QT_BEGIN_NAMESPACE
11
12/*!
13 \qmltype CheckBox
14 \inherits AbstractButton
15//! \nativetype QQuickCheckBox
16 \inqmlmodule QtQuick.Controls
17 \since 5.7
18 \ingroup qtquickcontrols-buttons
19 \brief Check button that can be toggled on or off.
20
21 \image qtquickcontrols-checkbox.gif
22
23 CheckBox presents an option button that can be toggled on (checked) or
24 off (unchecked). Check boxes are typically used to select one or more
25 options from a set of options. For larger sets of options, such as those
26 in a list, consider using \l CheckDelegate instead.
27
28 CheckBox inherits its API from \l AbstractButton. For instance, the
29 state of the checkbox can be set with the \l {AbstractButton::}{checked} property.
30
31 In addition to the checked and unchecked states, there is a third state:
32 partially checked. The partially checked state can be enabled using the
33 \l tristate property. This state indicates that the regular checked/unchecked
34 state can not be determined; generally because of other states that affect
35 the checkbox. This state is useful when several child nodes are selected
36 in a treeview, for example.
37
38 \code
39 ColumnLayout {
40 CheckBox {
41 checked: true
42 text: qsTr("First")
43 }
44 CheckBox {
45 text: qsTr("Second")
46 }
47 CheckBox {
48 checked: true
49 text: qsTr("Third")
50 }
51 }
52 \endcode
53
54 Hierarchical checkbox groups can be managed with a non-exclusive
55 \l ButtonGroup.
56
57 \image qtquickcontrols-checkbox-group.png
58
59 The following example illustrates how the combined check state of
60 children can be bound to the check state of the parent checkbox:
61
62 \snippet qtquickcontrols-checkbox-group.qml 1
63
64 \sa {Customizing CheckBox}, ButtonGroup, {Button Controls}
65*/
66
67class QQuickCheckBoxPrivate : public QQuickAbstractButtonPrivate
68{
69 Q_DECLARE_PUBLIC(QQuickCheckBox)
70
71public:
72 QPalette defaultPalette() const override { return QQuickTheme::palette(scope: QQuickTheme::CheckBox); }
73
74 bool tristate = false;
75 Qt::CheckState checkState = Qt::Unchecked;
76 QJSValue nextCheckState;
77};
78
79QQuickCheckBox::QQuickCheckBox(QQuickItem *parent)
80 : QQuickAbstractButton(*(new QQuickCheckBoxPrivate), parent)
81{
82 setCheckable(true);
83}
84
85/*!
86 \qmlproperty bool QtQuick.Controls::CheckBox::tristate
87
88 This property holds whether the checkbox is a tri-state checkbox.
89
90 In the animation below, the first checkbox is tri-state:
91
92 \image qtquickcontrols-checkbox-tristate.gif
93
94 The default is \c false, i.e., the checkbox has only two states.
95*/
96bool QQuickCheckBox::isTristate() const
97{
98 Q_D(const QQuickCheckBox);
99 return d->tristate;
100}
101
102void QQuickCheckBox::setTristate(bool tristate)
103{
104 Q_D(QQuickCheckBox);
105 if (d->tristate == tristate)
106 return;
107
108 d->tristate = tristate;
109 emit tristateChanged();
110}
111
112/*!
113 \qmlproperty enumeration QtQuick.Controls::CheckBox::checkState
114
115 This property holds the check state of the checkbox.
116
117 Available states:
118 \value Qt.Unchecked The checkbox is unchecked.
119 \value Qt.PartiallyChecked The checkbox is partially checked. This state is only used when \l tristate is enabled.
120 \value Qt.Checked The checkbox is checked.
121
122 \sa tristate, {AbstractButton::checked}{checked}
123*/
124Qt::CheckState QQuickCheckBox::checkState() const
125{
126 Q_D(const QQuickCheckBox);
127 return d->checkState;
128}
129
130void QQuickCheckBox::setCheckState(Qt::CheckState state)
131{
132 Q_D(QQuickCheckBox);
133 if (d->checkState == state)
134 return;
135
136 bool wasChecked = isChecked();
137 d->checked = state == Qt::Checked;
138 d->checkState = state;
139 emit checkStateChanged();
140 if (d->checked != wasChecked)
141 emit checkedChanged();
142}
143
144QJSValue QQuickCheckBox::getNextCheckState() const
145{
146 Q_D(const QQuickCheckBox);
147 return d->nextCheckState;
148}
149
150void QQuickCheckBox::setNextCheckState(const QJSValue &callback)
151{
152 Q_D(QQuickCheckBox);
153 d->nextCheckState = callback;
154 emit nextCheckStateChanged();
155}
156
157QFont QQuickCheckBox::defaultFont() const
158{
159 return QQuickTheme::font(scope: QQuickTheme::CheckBox);
160}
161
162void QQuickCheckBox::buttonChange(ButtonChange change)
163{
164 if (change == ButtonCheckedChange)
165 setCheckState(isChecked() ? Qt::Checked : Qt::Unchecked);
166 else
167 QQuickAbstractButton::buttonChange(change);
168}
169
170/*!
171 \since QtQuick.Controls 2.4 (Qt 5.11)
172 \qmlproperty function QtQuick.Controls::CheckBox::nextCheckState
173
174 This property holds a callback function that is called to determine
175 the next check state whenever the checkbox is interactively toggled
176 by the user via touch, mouse, or keyboard.
177
178 By default, a normal checkbox cycles between \c Qt.Unchecked and
179 \c Qt.Checked states, and a tri-state checkbox cycles between
180 \c Qt.Unchecked, \c Qt.PartiallyChecked, and \c Qt.Checked states.
181
182 The \c nextCheckState callback function can override the default behavior.
183 The following example implements a tri-state checkbox that can present
184 a partially checked state depending on external conditions, but never
185 cycles to the partially checked state when interactively toggled by
186 the user.
187
188 \code
189 CheckBox {
190 tristate: true
191 checkState: allChildrenChecked ? Qt.Checked :
192 anyChildChecked ? Qt.PartiallyChecked : Qt.Unchecked
193
194 nextCheckState: function() {
195 if (checkState === Qt.Checked)
196 return Qt.Unchecked
197 else
198 return Qt.Checked
199 }
200 }
201 \endcode
202*/
203void QQuickCheckBox::nextCheckState()
204{
205 Q_D(QQuickCheckBox);
206 if (d->nextCheckState.isCallable())
207 setCheckState(static_cast<Qt::CheckState>(d->nextCheckState.call().toInt()));
208 else if (d->tristate)
209 setCheckState(static_cast<Qt::CheckState>((d->checkState + 1) % 3));
210 else
211 QQuickAbstractButton::nextCheckState();
212}
213
214QT_END_NAMESPACE
215
216#include "moc_qquickcheckbox_p.cpp"
217

source code of qtdeclarative/src/quicktemplates/qquickcheckbox.cpp