[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