diff options
author | Andreas Buhr <andreas.buhr@qt.io> | 2021-01-27 12:01:29 +0100 |
---|---|---|
committer | Andreas Buhr <andreas.buhr@qt.io> | 2021-03-18 11:53:18 +0100 |
commit | 48a77e0961294f24ab68a523dcbef37561abbc92 (patch) | |
tree | d480916f4816a3e5edefccc0c753e52898dfe88a /src/corelib/doc | |
parent | f49c6a5672d5c4370c8fb594fbcd4ac6d3d49eea (diff) |
Add documentation on how to write a value to a bindable property
Writing a value to a bindable property is a surprisingly dangerous
operation. This patch adds a section to the documentation
describing the pitfalls which exist when writing bindable properties.
Task-number: QTBUG-90511
Change-Id: I73fea40756a1495d272bc46a7a51776ebcb07ea7
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Diffstat (limited to 'src/corelib/doc')
-rw-r--r-- | src/corelib/doc/src/objectmodel/bindableproperties.qdoc | 52 |
1 files changed, 52 insertions, 0 deletions
diff --git a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc index 75cc6f67d5..c84928d67a 100644 --- a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc +++ b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc @@ -116,6 +116,58 @@ It is therefore recommended to only use trivial setters with bindable properties. + \section1 Writing to a Bindable Property + + Bindable properties inform their dependent properties about each change. + This might trigger change handlers, which in turn might call arbitrary code. + Thus, every write to a bindable property has to be inspected carefully. + The following problems might occur. + + \section2 Writing Intermediate Values to Bindable Properties + + Bindable properties must not be used as variables in algorithms. Each value written + would be communicated to dependent properties. + For example, in the following code, other properties dependent on myProperty would be + first informed about the change to 42, then about the change to maxvalue. + + \badcode + myProperty = somecomputation(); // returning, say, 42 + if (myProperty.value() > maxvalue) + myProperty = maxvalue; + \endcode + + Instead, perform the computation in a separate variable. Correct usage is shown in the + following example. + + \code + int newvalue = somecomputation(); + if (newvalue > maxvalue) + newvalue = maxvalue; + myProperty = newvalue; // only write to the property once + \endcode + + \section2 Writing Bindable Properties in Transitional States + + When a bindable property is a member of a class, each write to that property + might expose the current state to the outside. So bindable properties must + not be written in transient states, when class invariants are not met. + + For example, in a class representing a circle which holds two members + "radius" and "area" consistent, a setter might look like this (where radius + is a bindable property): + + \badcode + void setRadius(double newvalue) + { + radius = newvalue; // this might trigger change handlers + area = M_PI*radius*radius; + emit radiusChanged(); + } + \endcode + + Here, code triggered in change handlers might use the circle, while it has + the new radius, but still the old area. + \section1 Tracking Bindable Properties Sometimes the relationships between properties cannot be expressed using |