[Qt-components] Proposed CheckBox API change
Mitch Curtis
mitch.curtis at digia.com
Mon Jan 28 18:31:19 CET 2013
Hello.
The components team in Oslo are currently discussing the addition of a third
state to CheckBox: "partially checked". The purpose of this state can be seen
in the Qt installer [1] and the Windows file permissions dialog [2][3], for
example. This state generally indicates that there are multiple related
checkboxes whose state affects whether or not it is checked.
We have proposed the name "checkedState" for the property, which is an enum
property, as seen below. A boolean property will also need to be added to
determine whether the third state is available. We propose that this is named
"partiallyCheckedEnabled":
/*!
This property indicates the current checked state of the checkbox.
When \l partiallyCheckedEnabled is \c false, this state will be equivalent
to \l checked; that is, when this property is \c Qt.Checked, \l checked
will be \c true, and when it is \c Qt.Unchecked, \l checked will be
\c false.
When \l partiallyCheckedEnabled is \c true, \c Qt.PartiallyChecked will
be available, and \l checked will be the same value that it was when
\c Qt.PartiallyChecked was set.
*/
property enum checkedState
/*!
This property determines whether the \c Qt.PartiallyChecked state is
available.
Setting \l checkedState to \c Qt.PartiallyChecked programmatically will
result in \l partiallyCheckedEnabled being set to \c true.
A checkbox may be in a partially checked state when the regular checked
state can not be determined because it is dependant on other checkboxes or
external states.
*/
property bool partiallyCheckedEnabled
You can see the behaviour upon successive mouse clicks here:
http://paste.kde.org/658568/
Some GUI APIs have the "partially checked" checkbox feature:
- GTK calls this state "inconsistent" [4], and does not appear to allow
cycling through the third state - that is, clicking the checkbox multiple
times will only switch between being checked and unchecked, not mixed.
- Windows calls it "indeterminate" [5], and allows cycling through the states
by setting the "IsThreeState" [6] property to true. The "indeterminate" state
can be set programmatically by setting the "IsChecked" property to null.
- wxWidgets is slightly more complicated, providing separate functions for 2
state and 3 state values [7]. They call the third state "wxCHK_UNDETERMINED".
They also give control over whether the third state can be set through the UI
or only programmatically [8].
Others do not:
- iOS does not have a checkbox; instead it has UISwitch [9].
- Android's CheckBox only has two states [10].
We would like to hear feedback on the naming, functionality and usefulness of
this state within Qt.
Cheers.
[1] Qt 5.0 installer in KDE: http://i.imgur.com/7CgGqHF.png
[2] Windows 7 checked: http://i.imgur.com/0dwtas2.png
[3] Windows 7 mixed: http://i.imgur.com/L5mGGsJ.png
[4]
http://developer.gnome.org/gtkmm/unstable/classGtk_1_1ToggleButton.html#a4ee24bcd23c08ed5b01b3260e5eb320a
[5] http://msdn.microsoft.com/en-
us/library/system.windows.controls.primitives.togglebutton.ischecked.aspx
[6] http://msdn.microsoft.com/en-
us/library/system.windows.controls.primitives.togglebutton.isthreestate.aspx
[7]
http://docs.wxwidgets.org/stable/wx_wxcheckbox.html#wxcheckboxgetthreestatevalue
[8]
http://docs.wxwidgets.org/stable/wx_wxcheckbox.html#wxcheckboxis3rdstateallowedforuser
[9]
http://developer.apple.com/library/ios/#documentation/uikit/reference/UISwitch_Class/Reference/Reference.html
[10] http://developer.android.com/reference/android/widget/CheckBox.html
More information about the Qt-components
mailing list