diff options
| -rw-r--r-- | src/corelib/doc/src/objectmodel/bindableproperties.qdoc | 30 | ||||
| -rw-r--r-- | src/corelib/kernel/qproperty.cpp | 14 |
2 files changed, 38 insertions, 6 deletions
diff --git a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc index f0f16aeafe..75cc6f67d5 100644 --- a/src/corelib/doc/src/objectmodel/bindableproperties.qdoc +++ b/src/corelib/doc/src/objectmodel/bindableproperties.qdoc @@ -86,6 +86,36 @@ is an integer and folded into the string value using conversion to integer, but the dependency is fully tracked. + \section1 Bindable Property Getters and Setters + + When a class has a bindable property, either using QProperty + or QObjectBindableProperty, special care has to be taken when formulating + getters and setters for that property. + + \section2 Bindable Property Getters + + To ensure proper operation of the automatic dependency-tracking system, + every possible code path in a getter needs to read from the underlying + property object. + In addition, the property must not be written inside the getter. + Design patterns which recompute or refresh anything in the getter + are not compatible with bindable properties. + + It is therefore recommended to only use trivial getters with bindable properties. + + \section2 Bindable Property Setters + + To ensure proper operation of the automatic dependency-tracking system, + every possible code path in a setter needs to write to the underlying + property object, even if the value did not change. + + Any other code in a setter has a high propability of being incorrect. + Any code doing updates based on the new value is most likely a bug, + as this code won't be executed when the property is changed + through a binding. + + It is therefore recommended to only use trivial setters with bindable properties. + \section1 Tracking Bindable Properties Sometimes the relationships between properties cannot be expressed using diff --git a/src/corelib/kernel/qproperty.cpp b/src/corelib/kernel/qproperty.cpp index 8742ff2af8..009ce09e56 100644 --- a/src/corelib/kernel/qproperty.cpp +++ b/src/corelib/kernel/qproperty.cpp @@ -1114,14 +1114,16 @@ QString QPropertyBindingError::description() const QObjectBindableProperty is a generic container that holds an instance of T and behaves mostly like \l QProperty. It is one of the classes implementing \l {Qt Bindable Properties}. - The extra template - parameters are used to identify the surrounding class and a member function of - that class. The member function will be called whenever the value held by the - property changes. + Unlike QProperty, it stores its management data structure in + the sourrounding QObject. + The extra template parameters are used to identify the surrounding + class and a member function of that class acting as a change handler. You can use QObjectBindableProperty to add binding support to code that uses Q_PROPERTY. - The getter and setter methods are easy to adapt for accessing a \l QObjectBindableProperty - rather than the plain value. In order to invoke the change signal on property changes, use + The getter and setter methods must be adapted carefully according to the + rules described in \l {Bindable Property Getters and Setters}. + + In order to invoke the change signal on property changes, use QObjectBindableProperty and pass the change signal as a callback. QObjectBindableProperty is usually not used directly, instead an instance of it is created by |