[Qt-components] Proposed CheckBox API change
Mitch Curtis
mitch.curtis at digia.com
Tue Jan 29 09:28:00 CET 2013
On Tuesday, January 29, 2013 09:41:25 AM Alberto Mardegan wrote:
> > 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":
> 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.
We were originally thinking of "allowMixed", but we think that using the
already existing CheckState enum [1] naming would be more consistent (it's
also more explicitly named). Some of us were also of the opinion that "allow"
is closer to function naminig due to it being a verb.
>
> As to the API itself:
> > /*!
> >
> > 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
>
> The last paragraph is confusing; does it mean that once
> "partiallyCheckedEnabled" is set to true, the "checked" property will
> stop working (i.e., its value will never change)?
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. :)
> 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.
[1] http://qt-project.org/doc/qt-5.0/qtcore/qt.html#CheckState-enum
More information about the Qt-components
mailing list