QProperty Class
template <typename T> class QPropertyThe QProperty class is a template class that enables automatic property bindings. More...
| Header: | #include <QProperty> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| Since: | Qt 6.0 |
| Inherits: | QPropertyData |
Public Functions
| QProperty() | |
| QProperty(Functor &&f) | |
| QProperty(T &&initialValue) | |
| QProperty(const QPropertyBinding<T> &binding) | |
| QProperty(const T &initialValue) | |
| ~QProperty() | |
| QPropertyNotifier | addNotifier(Functor f) |
| QPropertyBinding<T> | binding() const |
| QPropertyChangeHandler<Functor> | onValueChanged(Functor f) |
| QPropertyBinding<T> | setBinding(const QPropertyBinding<T> &newBinding) |
| QPropertyBinding<T> | setBinding(Functor f) |
| bool | setBinding(const QUntypedPropertyBinding &newBinding) |
| void | setValue(QProperty<T>::parameter_type newValue) |
| void | setValue(QProperty<T>::rvalue_ref newValue) |
| QPropertyChangeHandler<Functor> | subscribe(Functor f) |
| QPropertyBinding<T> | takeBinding() |
| QProperty<T>::parameter_type | value() const |
| QProperty<T> & | operator=(QProperty<T>::parameter_type newValue) |
| QProperty<T> & | operator=(QProperty<T>::rvalue_ref newValue) |
Related Non-Members
(since 6.2) void | beginPropertyUpdateGroup() |
(since 6.2) void | endPropertyUpdateGroup() |
Detailed Description
QProperty<T> is one of the classes implementing Qt Bindable Properties. It is a container that holds an instance of T. You can assign a value to it and you can read it via the value() function or the T conversion operator. You can also tie the property to an expression that computes the value dynamically, the binding expression. It is represented as a C++ lambda and can be used to express relationships between different properties in your application.
Note: For QML, it's important to expose the QProperty in Q_PROPERTY with the BINDABLE keyword. As a result, the QML engine uses it as the bindable interface to set up the property binding. In turn, the binding can then be interacted with C++ via the normal API: QProperty<T>::onValueChanged, QProperty::takeBinding and QBindable::hasBinding If the property is BINDABLE, the engine will use the change-tracking inherent to the C++ property system for getting notified about changes, and it won't rely on signals being emitted.
Member Function Documentation
void QProperty::setValue(QProperty<T>::parameter_type newValue)
void QProperty::setValue(QProperty<T>::rvalue_ref newValue)
Assigns newValue to this property and removes the property's associated binding, if present.
QProperty<T> &QProperty::operator=(QProperty<T>::parameter_type newValue)
QProperty<T> &QProperty::operator=(QProperty<T>::rvalue_ref newValue)
Assigns newValue to this property and returns a reference to this QProperty.
QProperty::QProperty()
Constructs a property with a default constructed instance of T.
[explicit] template <typename Functor> QProperty::QProperty(Functor &&f)
Constructs a property that is tied to the provided binding expression f. The property's value is set to the result of evaluating the new binding. Whenever a dependency of the binding changes, the binding will be re-evaluated, and the property's value gets updated accordingly.
[explicit default] QProperty::QProperty(T &&initialValue)
Move-Constructs a property with the provided initialValue.
[explicit] QProperty::QProperty(const QPropertyBinding<T> &binding)
Constructs a property that is tied to the provided binding expression. The property's value is set to the result of evaluating the new binding. Whenever a dependency of the binding changes, the binding will be re-evaluated, and the property's value gets updated accordingly.
[explicit default] QProperty::QProperty(const T &initialValue)
Constructs a property with the provided initialValue.
QProperty::~QProperty()
Destroys the property.
template <typename Functor> QPropertyNotifier QProperty::addNotifier(Functor f)
Subscribes the given functor f as a callback that is called whenever the value of the property changes.
The callback f is expected to be a type that has a plain call operator () without any parameters. This means that you can provide a C++ lambda expression, a std::function or even a custom struct with a call operator.
The returned property change handler object keeps track of the subscription. When it goes out of scope, the callback is unsubscribed.
This method is in some cases easier to use than onValueChanged(), as the returned object is not a template. It can therefore more easily be stored, e.g. as a member in a class.
See also onValueChanged() and subscribe().
QPropertyBinding<T> QProperty::binding() const
Returns the binding expression that is associated with this property. A default constructed QPropertyBinding<T> will be returned if no such association exists.
See also setBinding().
template <typename Functor> QPropertyChangeHandler<Functor> QProperty::onValueChanged(Functor f)
Registers the given functor f as a callback that shall be called whenever the value of the property changes. On each value change, the handler is either called immediately, or deferred, depending on the context.
The callback f is expected to be a type that has a plain call operator () without any parameters. This means that you can provide a C++ lambda expression, a std::function or even a custom struct with a call operator.
The returned property change handler object keeps track of the registration. When it goes out of scope, the callback is de-registered.
QPropertyBinding<T> QProperty::setBinding(const QPropertyBinding<T> &newBinding)
Associates the value of this property with the provided newBinding expression and returns the previously associated binding. The property's value is set to the result of evaluating the new binding. Whenever a dependency of the binding changes, the binding will be re-evaluated, and the property's value gets updated accordingly.
See also binding().
template <typename Functor> QPropertyBinding<T> QProperty::setBinding(Functor f)
This is an overloaded function.
Associates the value of this property with the provided functor f and returns the previously associated binding. The property's value is set to the result of evaluating the new binding. Whenever a dependency of the binding changes, the binding will be re-evaluated, and the property's value gets updated accordingly.
See also Formulating a Property Binding.
bool QProperty::setBinding(const QUntypedPropertyBinding &newBinding)
This is an overloaded function.
Associates the value of this property with the provided newBinding expression. The property's value is set to the result of evaluating the new binding. Whenever a dependency of the binding changes, the binding will be re-evaluated, and the property's value gets updated accordingly.
Returns true if the type of this property is the same as the type the binding function returns; false otherwise.
template <typename Functor> QPropertyChangeHandler<Functor> QProperty::subscribe(Functor f)
Subscribes the given functor f as a callback that is called immediately and whenever the value of the property changes in the future. On each value change, the handler is either called immediately, or deferred, depending on the context.
The callback f is expected to be a type that can be copied and has a plain call operator() without any parameters. This means that you can provide a C++ lambda expression, a std::function or even a custom struct with a call operator.
The returned property change handler object keeps track of the subscription. When it goes out of scope, the callback is unsubscribed.
QPropertyBinding<T> QProperty::takeBinding()
Disassociates the binding expression from this property and returns it. After calling this function, the value of the property will only change if you assign a new value to it, or when a new binding is set.
QProperty<T>::parameter_type QProperty::value() const
Returns the value of the property. This may evaluate a binding expression that is tied to this property, before returning the value.
See also setValue().
Related Non-Members
[since 6.2] void beginPropertyUpdateGroup()
Marks the beginning of a property update group. Inside this group, changing a property does neither immediately update any dependent properties nor does it trigger change notifications. Those are instead deferred until the group is ended by a call to endPropertyUpdateGroup.
Groups can be nested. In that case, the deferral ends only after the outermost group has been ended.
Note: Change notifications are only send after all property values affected by the group have been updated to their new values. This allows re-establishing a class invariant if multiple properties need to be updated, preventing any external observer from noticing an inconsistent state.
This function was introduced in Qt 6.2.
See also Qt::endPropertyUpdateGroup and QScopedPropertyUpdateGroup.
[since 6.2] void endPropertyUpdateGroup()
Ends a property update group. If the outermost group has been ended, and deferred binding evaluations and notifications happen now.
Warning: Calling endPropertyUpdateGroup without a preceding call to beginPropertyUpdateGroup results in undefined behavior.
This function was introduced in Qt 6.2.
See also Qt::beginPropertyUpdateGroup and QScopedPropertyUpdateGroup.
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
