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

source code of qtquickcontrols2/src/quicktemplates2/qquickcheckbox.cpp