QPropertyAlias Class

template <typename T> class QPropertyAlias

The QPropertyAlias class is a safe alias for a QProperty with same template parameter. More...

Header: #include <QPropertyAlias>
CMake: find_package(Qt6 COMPONENTS Core REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Inherits: QPropertyObserver

Public Functions

QPropertyAlias(QPropertyAlias<T> *alias)
QPropertyAlias(QProperty<T> *property)
QPropertyAlias<T> &operator=(const QPropertyBinding<T> &newBinding)
QPropertyAlias<T> &operator=(T &&newValue)
QPropertyAlias<T> &operator=(const T &newValue)
QPropertyBinding<T> binding() const
bool hasBinding() const
bool isValid() 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(const T &newValue)
QPropertyChangeHandler<Functor> subscribe(Functor f)
QPropertyBinding<T> takeBinding()
T value() const
T operator T() const

Detailed Description

QPropertyAlias<T> wraps a pointer to a QProperty<T> and automatically invalidates itself when the QProperty<T> is destroyed. It forwards all method invocations to the wrapped property. For example:

QProperty<QString> *name = new QProperty<QString>("John");
QProperty<int> age(41);

QPropertyAlias<QString> nameAlias(name);
QPropertyAlias<int> ageAlias(&age);

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

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

*name = "Emma"; // Marks binding expression as dirty

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

// Birthday is coming up
ageAlias.setValue(age.value() + 1); // Writes the age property through the alias

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

delete name; // Leaves the alias in an invalid, but accessible state
nameAlias.setValue("Eve"); // Ignored: nameAlias carries a default-constructed QString now

ageAlias.setValue(92);
qDebug() << fullname.value(); // Re-evaluates the binding expression and prints " age: 92"

Member Function Documentation

QPropertyAlias::QPropertyAlias(QPropertyAlias<T> *alias)

Constructs a property alias for the property aliased by alias.

QPropertyAlias::QPropertyAlias(QProperty<T> *property)

Constructs a property alias for the given property.

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

This is an overloaded function.

Associates the value of the aliased property with the provided newBinding expression and returns a reference to this alias. The first time the property value is read, either from the property itself or from any alias, 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.

[default] QPropertyAlias<T> &QPropertyAlias::operator=(T &&newValue)

This is an overloaded function.

Assigns newValue to the aliased property and returns a reference to this QPropertyAlias.

QPropertyAlias<T> &QPropertyAlias::operator=(const T &newValue)

Assigns newValue to the aliased property and returns a reference to this QPropertyAlias.

QPropertyBinding<T> QPropertyAlias::binding() const

Returns the binding expression that is associated with the aliased property. A default constructed QPropertyBinding<T> will be returned if no such association exists.

See also setBinding().

bool QPropertyAlias::hasBinding() const

Returns true if the aliased property is associated with a binding; false otherwise.

bool QPropertyAlias::isValid() const

Returns true if the aliased property still exists; false otherwise.

If the aliased property doesn't exist, all other method calls are ignored.

template <typename Functor> QPropertyChangeHandler<Functor> QPropertyAlias::onValueChanged(Functor f)

Registers the given functor f as a callback that shall be called whenever the value of the aliased 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> QPropertyAlias::setBinding(const QPropertyBinding<T> &newBinding)

Associates the value of the aliased property with the provided newBinding expression and returns any previous binding the associated with the aliased property. The first time the property value is read, either from the property itself or from any alias, 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 any previous binding associated with the property, or a default-constructed QPropertyBinding<T>.

See also binding().

bool QPropertyAlias::setBinding(const QUntypedPropertyBinding &newBinding)

This is an overloaded function.

Associates the value of the aliased property with the provided newBinding expression. The first time the property value is read, either from the property itself or from any alias, 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> QPropertyAlias::setBinding(Functor f)

This is an overloaded function.

Associates the value of the aliased property with the provided functor f expression. The first time the property value is read, either from the property itself or from any alias, 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 any previous binding associated with the property, or a default-constructed QPropertyBinding<T>.

void QPropertyAlias::setValue(const T &newValue)

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

See also value().

template <typename Functor> QPropertyChangeHandler<Functor> QPropertyAlias::subscribe(Functor f)

Subscribes the given functor f as a callback that is called immediately and whenever the value of the aliased 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> QPropertyAlias::takeBinding()

Disassociates the binding expression from the aliased 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.

T QPropertyAlias::value() const

Returns the value of the aliased property. This may evaluate a binding expression that is tied to the property, before returning the value.

See also setValue().

T QPropertyAlias::operator T() const

Returns the value of the aliased property. This may evaluate a binding expression that is tied to the property, before returning the value.

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