QObjectCompatProperty Class
template <typename Class, typename T, auto Offset, auto Setter, auto Signal, auto Getter> class QObjectCompatPropertyThe QObjectCompatProperty class is a template class to help port old properties to the bindable property system. \since
6.0 \ingroup
tools \internal
. More...
Header: | #include <QObjectCompatProperty> |
Inherits: | QPropertyData |
Macros
Q_OBJECT_COMPAT_PROPERTY(containingClass, type, name, callback) | |
Q_OBJECT_COMPAT_PROPERTY_WITH_ARGS(containingClass, type, name, callback, value) |
Detailed Description
\inmodule
QtCore
QObjectCompatProperty is a generic container that holds an instance of T
and behaves mostly like QProperty, just like QObjectBindableProperty. It's one of the Qt internal classes implementing Qt Bindable Properties. Like QObjectBindableProperty, QObjectCompatProperty stores its management data structure in the surrounding QObject. The last template parameter specifies a method (of the owning class) to be called when the property is changed through the binding. This is usually a setter.
As explained in Qt Bindable Properties, getters and setters for bindable properties have to be almost trivial to be correct. However, in legacy code, there is often complex logic in the setter. QObjectCompatProperty is a helper to port these properties to the bindable property system.
With QObjectCompatProperty, the same rules as described in Bindable Property Getters and Setters hold for the getter. For the setter, the rules are different. It remains that every possible code path in the setter must write to the underlying QObjectCompatProperty, otherwise calling the setter might not remove a pre-existing binding, as it should. However, as QObjectCompatProperty will call the setter on every change, the setter is allowed to contain code like updating class internals or emitting signals. Every write to the QObjectCompatProperty has to be analyzed carefully to comply with the rules given in Writing to a Bindable Property.
Properties with Virtual Setters
Some of the pre-existing Qt classes (for example, QAbstractProxyModel) have properties with virtual setters. Special care must be taken when making such properties bindable.
For the binding to work properly, the property must be correctly handled in all reimplemented methods of each derived class.
Unless the derived class has access to the underlying property object, the base implementation must be called for the binding to work correctly.
If the derived class can directly access the property instance, there is no need to explicitly call the base implementation, but the property's value must be correctly updated.
Refer to Bindable Properties with Virtual Setters and Getters for more details.
In both cases the expected behavior must be documented in the property's documentation, so that users can correctly override the setter.
Properties for which these conditions cannot be met should not be made bindable.
See also Q_OBJECT_COMPAT_PROPERTY, QObjectBindableProperty, Qt's Property System, and Qt Bindable Properties.
Macro Documentation
Q_OBJECT_COMPAT_PROPERTY(containingClass, type, name, callback)
\since
6.0 \internal
Declares a QObjectCompatProperty inside containingClass of type type with name name. The argument callback specifies a setter function to be called when the property is changed through the binding.
See also QObjectBindableProperty, Qt's Property System, and Qt Bindable Properties.
Q_OBJECT_COMPAT_PROPERTY_WITH_ARGS(containingClass, type, name, callback, value)
\since
6.0 \internal
Declares a QObjectCompatProperty inside of containingClass of type type with name name. The argument callback specifies a setter function to be called when the property is changed through the binding. value specifies an initialization value.