[Qt-components] Proposed CheckBox API change

Bache-Wiig Jens Jens.Bache-Wiig at digia.com
Tue Jan 29 11:09:28 CET 2013


I'd vote for something like "allowPartialCheck" or any name which
doesn't contain a sequence of two past principles ("checked" -
"enabled") next to each other, as that results somehow confusing.

I was actually suggesting "partiallyCheckedStateAllowed", but enabled is ok with me. As Mitch said, allowedPartialCheck() would be a good name of a function call but not a good name of a property. A property should describe a state and not an action. I personally don't mind if it is a bit verbose as the functionality is rather uncommon.

No, just that it's possible to retain the original checked state while in a
partially checked state. The checked property and checkedState "mirror" each
other for the regular states; change one and the other changes too. Though the
more I think about it, the more useless this is, as unchecked will always be
the next state after partially checked. You can ignore that paragraph.. I'll
take it out like Jens suggested. :)

Told you so. ;)

This is actually an example where too much documentation makes the meaning less clear. I had to read both sections twice to grasp something that should be obvious. I personally think it would be sufficient to document the checkedState property like this:

/*!
   This property indicates the current checked state of the checkbox.

    Possible values:
    Qt.UnChecked - The checkbox is not checked (default)
    Qt.Checked - The checkbox is checked
    Qt.PartiallyChecked - The checkbox is in a partially checked (or mixed) state
*/

While I'm usually a fan of enums, in this particular case I think it
might be simpler to introduce a new boolean, "partiallyChecked"; then:

1) "checked == false" means that the checkbox is clear
2) "checked == true" means that the checkbox is at least partially checked;
  2a) "checked == true && partiallyChecked == false": fully checked
  2b) "checked == true && partiallyChecked == true": partially checked

I'll let Jens respond to this, as he can better describe the motivation.

Sure. It comes down to use cases. For the simple use cases bool properties tend to be convenient and readable. I.e

    frameVisible : checkBox.checked

But if you introduce an additional state the elegance disappears:

    frameVisible : checkBox.partiallyChecked ? defaultFrameSetting ? checkBox.checked : false

(you had to read that twice didn't you?)

In the few case where you actually make use of the partiallyCheckedState, I would prefer to see all the valid states listed explicitly like this:

onCheckedStateChanged: {
    switch (checkedState) :
       case Qt.Unchecked:
       case Qt.PartiallyChecked:
       case Qt.Checked:
     ...
}

It might be more a bit more verbose but it looks more readable to me. I would also argue that the checked property is effectively undefined while in the partiallyCheckedState as the user can not even tell if the checkBox is checked or unChecked and the state literally means that the checked state is invalid.

Regards,
Jens







-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.qt-project.org/pipermail/qt-components/attachments/20130129/69cdde6e/attachment.html 


More information about the Qt-components mailing list