Qt Documentation

Contents

QProperty Class

template <typename T> class QProperty

The QProperty class is a template class that enables automatic property bindings. More...

Header: #include <QProperty>
CMake: find_package(Qt6 COMPONENTS Core REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Since: Qt 6.0
Inherits: QPropertyData

Public Functions

QProperty(T &&initialValue)
QProperty(const T &initialValue)
QProperty(Functor &&f)
QProperty(const QPropertyBinding<T> &binding)
QProperty()
QProperty<T> &operator=(const QPropertyBinding<T> &newBinding)
~QProperty()
QPropertyBinding<T> binding() const
QPropertyChangeHandler<Functor> onValueChanged(Functor f)
QPropertyBinding<T> setBinding(const QPropertyBinding<T> &newBinding)
bool setBinding(const QUntypedPropertyBinding &newBinding)
QPropertyBinding<T> setBinding(Functor f)
void setValue(QProperty::rvalue_ref newValue)
void setValue(QProperty::parameter_type newValue)
QPropertyChangeHandler<Functor> subscribe(Functor f)
QPropertyBinding<T> takeBinding()
QProperty::parameter_type value() const
QProperty<T> &operator=(QProperty::rvalue_ref newValue)
QProperty<T> &operator=(QProperty::parameter_type newValue)

Detailed Description

QProperty<T> is a generic 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.

The binding expression computes the value by reading other QProperty values. Behind the scenes this dependency is tracked. Whenever a change in any property's dependency is detected, the binding expression is re-evaluated and the new result is applied to the property. This happens lazily, by marking the binding as dirty and evaluating it only when the property's value is requested. For example:

QProperty<QString> firstname("John");
QProperty<QString> lastname("Smith");
QProperty<int> age(41);

QProperty<QString> fullname;
fullname.setBinding([&]() { return firstname.value() + " " + lastname.value() + " age: " + QString::number(age.value()); });

qDebug() << fullname.value(); // Prints "John Smith age: 41"

firstname = "Emma"; // Marks binding expression as dirty

qDebug() << fullname.value(); // Re-evaluates the binding expression and prints "Emma Smith age: 41"

// Birthday is coming up
age.setValue(age.value() + 1);

qDebug() << fullname.value(); // Re-evaluates the binding expression and prints "Emma Smith age: 42"

When a new value is assigned to the firstname property, the binding expression for fullname is marked as dirty. So when the last qDebug() statement tries to read the name value of the fullname property, the expression is evaluated again, firstname() will be called again and return the new value.

Since bindings are C++ lambda expressions, they may do anything that's possible in C++. This includes calling other functions. If those functions access values held by QProperty, they automatically become dependencies to the binding.

Binding expressions may use properties of any type, so in the above example the age is an integer and folded into the string value using conversion to integer, but the dependency is fully tracked.

Tracking properties

Sometimes the relationships between properties cannot be expressed using bindings. Instead you may need to run custom code whenever the value of a property changes and instead of assigning the value to another property, pass it to other parts of your application. For example writing data into a network socket or printing debug output. QProperty provides two mechanisms for tracking.

You can register for a callback function to be called whenever the value of a property changes, by using onValueChanged(). If you want the callback to also be called for the current value of the property, register your callback using subscribe() instead.

Member Function Documentation

QProperty<T> &QProperty::operator=(QProperty::parameter_type newValue)

QProperty<T> &QProperty::operator=(QProperty::rvalue_ref newValue)

Assigns newValue to this property and returns a reference to this QProperty.

void QProperty::setValue(QProperty::parameter_type newValue)

void QProperty::setValue(QProperty::rvalue_ref newValue)

Assigns newValue to this property and removes the property's associated binding, if present.

[default] QProperty::QProperty(T &&initialValue)

Move-Constructs a property with the provided initialValue.

[default] QProperty::QProperty(const T &initialValue)

Constructs a property with the provided initialValue.

template <typename Functor> QProperty::QProperty(Functor &&f)

Constructs a property that is tied to the provided binding expression f. The first time the property value is read, the binding is evaluated. Whenever a dependency of the binding changes, the binding will be re-evaluated the next time the value of this property is read.

QProperty::QProperty(const QPropertyBinding<T> &binding)

Constructs a property that is tied to the provided binding expression. The first time the property value is read, the binding is evaluated. Whenever a dependency of the binding changes, the binding will be re-evaluated the next time the value of this property is read.

QProperty::QProperty()

Constructs a property with a default constructed instance of T.

[default] QProperty<T> &QProperty::operator=(const QPropertyBinding<T> &newBinding)

Associates the value of this property with the provided newBinding expression and returns a reference to this property. The first time the property value is read, the binding is evaluated. Whenever a dependency of the binding changes, the binding will be re-evaluated the next time the value of this property is read.

QProperty::~QProperty()

Destroys the property.

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.

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, an 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 first time the property value is read, the binding is evaluated. Whenever a dependency of the binding changes, the binding will be re-evaluated the next time the value of this property is read.

See also binding().

bool QProperty::setBinding(const QUntypedPropertyBinding &newBinding)

This is an overloaded function.

Associates the value of this property with the provided newBinding expression. The first time the property value is read, the binding is evaluated. Whenever a dependency of the binding changes, the binding will be re-evaluated the next time the value of this property is read.

Returns true if the type of this property is the same as the type the binding function returns; false otherwise.

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 first time the property value is read, the binding is evaluated by invoking the call operator () of f. Whenever a dependency of the binding changes, the binding will be re-evaluated the next time the value of this property is read.

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.

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, an 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::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().

© 2021 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.