Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
QObjectBindableProperty< Class, T, Offset, Signal > Class Template Reference

\inmodule QtCore More...

#include <qproperty.h>

+ Inheritance diagram for QObjectBindableProperty< Class, T, Offset, Signal >:
+ Collaboration diagram for QObjectBindableProperty< Class, T, Offset, Signal >:

Public Types

using value_type = typename QPropertyData<T>::value_type
 
using parameter_type = typename QPropertyData<T>::parameter_type
 
using rvalue_ref = typename QPropertyData<T>::rvalue_ref
 
using arrow_operator_result = typename QPropertyData<T>::arrow_operator_result
 
- Public Types inherited from QPropertyData< T >
using value_type = T
 
using parameter_type = std::conditional_t<UseReferences, const T &, T>
 
using rvalue_ref = typename std::conditional_t<UseReferences, T &&, DisableRValueRefs>
 
using arrow_operator_result
 

Public Member Functions

 QObjectBindableProperty ()=default
 
 QObjectBindableProperty (const T &initialValue)
 Constructs a property with the provided initialValue.
 
 QObjectBindableProperty (T &&initialValue)
 Move-Constructs a property with the provided initialValue.
 
 QObjectBindableProperty (const QPropertyBinding< T > &binding)
 
template<typename Functor >
 QObjectBindableProperty (Functor &&f, const QPropertyBindingSourceLocation &location=QT_PROPERTY_DEFAULT_BINDING_LOCATION, typename std::enable_if_t< std::is_invocable_r_v< T, Functor & > > *=nullptr)
 
parameter_type value () const
 Returns the value of the property.
 
arrow_operator_result operator-> () const
 
parameter_type operator* () const
 
 operator parameter_type () const
 
void setValue (parameter_type t)
 
void notify ()
 Programmatically signals a change of the property.
 
void setValue (rvalue_ref t)
 Assigns newValue to this property and removes the property's associated binding, if present.
 
QObjectBindablePropertyoperator= (rvalue_ref newValue)
 
QObjectBindablePropertyoperator= (parameter_type newValue)
 
QPropertyBinding< T > setBinding (const QPropertyBinding< T > &newBinding)
 Associates the value of this property with the provided newBinding expression and returns the previously associated binding.
 
bool setBinding (const QUntypedPropertyBinding &newBinding)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Associates the value of this property with the provided newBinding expression.
 
template<typename Functor >
QPropertyBinding< T > setBinding (Functor &&f, const QPropertyBindingSourceLocation &location=QT_PROPERTY_DEFAULT_BINDING_LOCATION, std::enable_if_t< std::is_invocable_v< Functor > > *=nullptr)
 
bool hasBinding () const
 Returns true if the property is associated with a binding; false otherwise.
 
QPropertyBinding< T > binding () const
 Returns the binding expression that is associated with this property.
 
QPropertyBinding< T > takeBinding ()
 Disassociates the binding expression from this property and returns it.
 
template<typename Functor >
QPropertyChangeHandler< FunctoronValueChanged (Functor f)
 Registers the given functor f as a callback that shall be called whenever the value of the property changes.
 
template<typename Functor >
QPropertyChangeHandler< Functorsubscribe (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.
 
template<typename Functor >
QPropertyNotifier addNotifier (Functor f)
 Subscribes the given functor f as a callback that is called whenever the value of the property changes.
 
const QtPrivate::QPropertyBindingDatabindingData () const
 
- Public Member Functions inherited from QPropertyData< T >
 QPropertyData ()=default
 
 QPropertyData (parameter_type t)
 
 QPropertyData (rvalue_ref t)
 
 ~QPropertyData ()=default
 
parameter_type valueBypassingBindings () const
 Returns the data stored in this property.
 
void setValueBypassingBindings (parameter_type v)
 Sets the data value stored in this property to v.
 
void setValueBypassingBindings (rvalue_ref v)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Sets the data value stored in this property to v.
 

Additional Inherited Members

- Protected Attributes inherited from QPropertyData< T >
val = T()
 
- Static Protected Attributes inherited from QPropertyData< T >
static constexpr bool UseReferences = !(std::is_arithmetic_v<T> || std::is_enum_v<T> || std::is_pointer_v<T>)
 

Detailed Description

template<typename Class, typename T, auto Offset, auto Signal = nullptr>
class QObjectBindableProperty< Class, T, Offset, Signal >

\inmodule QtCore

The QObjectBindableProperty class is a template class that enables automatic property bindings for property data stored in QObject derived classes.

Since
6.0

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}. Unlike QProperty, it stores its management data structure in the surrounding 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 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.

A simple example is given in the following.

#include <QObject>
#include <QProperty>
#include <QDebug>
class Foo : public QObject
{
Q_PROPERTY(int myVal READ myVal WRITE setMyVal BINDABLE bindableMyVal)
public:
int myVal() { return myValMember.value(); }
void setMyVal(int newvalue) { myValMember = newvalue; }
QBindable<int> bindableMyVal() { return &myValMember; }
void myValChanged();
private:
Q_OBJECT_BINDABLE_PROPERTY(Foo, int, myValMember, &Foo::myValChanged);
};
int main()
{
bool debugout(true); // enable debug log
Foo myfoo;
QProperty<int> prop(42);
QObject::connect(&myfoo, &Foo::myValChanged, [&]() {
if (debugout)
qDebug() << myfoo.myVal();
});
myfoo.bindableMyVal().setBinding([&]() { return prop.value(); }); // prints "42"
prop = 5; // prints "5"
debugout = false;
prop = 6; // prints nothing
debugout = true;
prop = 7; // prints "7"
}
#include "main.moc"

QObjectBindableProperty is usually not used directly, instead an instance of it is created by using the Q_OBJECT_BINDABLE_PROPERTY macro.

Use the Q_OBJECT_BINDABLE_PROPERTY macro in the class declaration to declare the property as bindable.

class MyClass : public QObject
{
Q_PROPERTY(int x READ x WRITE setX NOTIFY xChanged BINDABLE bindableX)
public:
int x() const { return xProp; }
void setX(int x) { xProp = x; }
QBindable<int> bindableX() { return QBindable<int>(&xProp); }
void xChanged();
private:
// Declare the instance of the bindable property data.
Q_OBJECT_BINDABLE_PROPERTY(MyClass, int, xProp, &MyClass::xChanged)
};

If you need to directly initialize the property with some non-default value, you can use the Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS macro. It accepts a value for the initialization as one of its parameters.

class MyClass : public QObject
{
Q_PROPERTY(int x READ x WRITE setX NOTIFY xChanged BINDABLE bindableX)
public:
int x() const { return xProp; }
void setX(int x) { xProp = x; }
QBindable<int> bindableX() { return QBindable<int>(&xProp); }
void xChanged();
private:
// Declare the instance of int bindable property data and
// initialize it with the value 5.
// This is similar to declaring
// int xProp = 5;
// without using the new QObjectBindableProperty class.
Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS(MyClass, int, xProp, 5, &MyClass::xChanged)
};

Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS does not support multiple arguments directly. If your property requires multiple arguments for initialization, please explicitly call the specific constructor.

{
public:
CustomType(int val, int otherVal) : value(val), anotherValue(otherVal) { }
private:
int value = 0;
int anotherValue = 0;
};
// later when using CustomType as a property
&MyClass::xChanged)

The change handler can optionally accept one argument, of the same type as the property, in which case it is passed the new value of the property. Otherwise, it should take no arguments.

If the property does not need a changed notification, you can leave out the "NOTIFY xChanged" in the Q_PROPERTY macro as well as the last argument of the Q_OBJECT_BINDABLE_PROPERTY and Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS macros.

See also
Q_OBJECT_BINDABLE_PROPERTY, Q_OBJECT_BINDABLE_PROPERTY_WITH_ARGS, QProperty, QObjectComputedProperty, {Qt's Property System}, {Qt Bindable Properties}

Definition at line 1022 of file qproperty.h.

Member Typedef Documentation

◆ arrow_operator_result

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
using QObjectBindableProperty< Class, T, Offset, Signal >::arrow_operator_result = typename QPropertyData<T>::arrow_operator_result

Definition at line 1051 of file qproperty.h.

◆ parameter_type

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
using QObjectBindableProperty< Class, T, Offset, Signal >::parameter_type = typename QPropertyData<T>::parameter_type

Definition at line 1049 of file qproperty.h.

◆ rvalue_ref

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
using QObjectBindableProperty< Class, T, Offset, Signal >::rvalue_ref = typename QPropertyData<T>::rvalue_ref

Definition at line 1050 of file qproperty.h.

◆ value_type

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
using QObjectBindableProperty< Class, T, Offset, Signal >::value_type = typename QPropertyData<T>::value_type

Definition at line 1048 of file qproperty.h.

Constructor & Destructor Documentation

◆ QObjectBindableProperty() [1/5]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
QObjectBindableProperty< Class, T, Offset, Signal >::QObjectBindableProperty ( )
default

◆ QObjectBindableProperty() [2/5]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template< typename Class, typename T, auto offset, auto Callback > explicit QObjectBindableProperty< Class, T, Offset, Signal >::QObjectBindableProperty ( const T & initialValue)
inlineexplicit

Constructs a property with the provided initialValue.

Definition at line 1054 of file qproperty.h.

◆ QObjectBindableProperty() [3/5]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template< typename Class, typename T, auto offset, auto Callback > explicit QObjectBindableProperty< Class, T, Offset, Signal >::QObjectBindableProperty ( T && initialValue)
inlineexplicit

Move-Constructs a property with the provided initialValue.

Definition at line 1055 of file qproperty.h.

◆ QObjectBindableProperty() [4/5]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
QObjectBindableProperty< Class, T, Offset, Signal >::QObjectBindableProperty ( const QPropertyBinding< T > & binding)
inlineexplicit

Definition at line 1056 of file qproperty.h.

References QObjectBindableProperty< Class, T, Offset, Signal >::binding(), and QObjectBindableProperty< Class, T, Offset, Signal >::setBinding().

+ Here is the call graph for this function:

◆ QObjectBindableProperty() [5/5]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template<typename Functor >
QObjectBindableProperty< Class, T, Offset, Signal >::QObjectBindableProperty ( Functor && f,
const QPropertyBindingSourceLocation & location = QT_PROPERTY_DEFAULT_BINDING_LOCATION,
typename std::enable_if_t< std::is_invocable_r_v< T, Functor & > > * = nullptr )
inlineexplicit

Definition at line 1061 of file qproperty.h.

Member Function Documentation

◆ addNotifier()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template<typename Functor >
template< typename Class, typename T, auto offset, auto Callback > template< typename Functor > QPropertyNotifier QObjectBindableProperty< Class, T, Offset, Signal >::addNotifier ( Functor f)
inline

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(), subscribe()

Definition at line 1198 of file qproperty.h.

◆ binding()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template< typename Class, typename T, auto offset, auto Callback > QPropertyBinding< T > QObjectBindableProperty< Class, T, Offset, Signal >::binding ( ) const
inline

Returns the binding expression that is associated with this property.

A default constructed QPropertyBinding<T> will be returned if no such association exists.

Definition at line 1171 of file qproperty.h.

References QBindingStorage::bindingData(), and qGetBindingStorage().

Referenced by QObjectBindableProperty< Class, T, Offset, Signal >::QObjectBindableProperty().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ bindingData()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
const QtPrivate::QPropertyBindingData & QObjectBindableProperty< Class, T, Offset, Signal >::bindingData ( ) const
inline

Definition at line 1204 of file qproperty.h.

References qGetBindingStorage(), and storage.

+ Here is the call graph for this function:

◆ hasBinding()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template< typename Class, typename T, auto offset, auto Callback > bool QObjectBindableProperty< Class, T, Offset, Signal >::hasBinding ( ) const
inline

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

Definition at line 1165 of file qproperty.h.

References QtPrivate::QPropertyBindingData::binding(), QBindingStorage::bindingData(), and qGetBindingStorage().

+ Here is the call graph for this function:

◆ notify()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template< typename Class, typename T, auto offset, auto Callback > void QObjectBindableProperty< Class, T, Offset, Signal >::notify ( )
inline

Programmatically signals a change of the property.

Any binding which depend on it will be notified, and if the property has a signal, it will be emitted.

This can be useful in combination with setValueBypassingBindings to defer signalling the change until a class invariant has been restored.

Note
If this property has a binding (i.e. hasBinding() returns true), that binding is not reevaluated when notify() is called. Any binding depending on this property is still reevaluated as usual.
See also
Qt::beginPropertyUpdateGroup(), setValueBypassingBindings()

Definition at line 1109 of file qproperty.h.

References QBindingStorage::bindingData(), QObjectBindableProperty< Class, T, Offset, Signal >::notify(), and qGetBindingStorage().

Referenced by QObjectBindableProperty< Class, T, Offset, Signal >::notify(), QObjectBindableProperty< Class, T, Offset, Signal >::setValue(), and QObjectBindableProperty< Class, T, Offset, Signal >::setValue().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ onValueChanged()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template<typename Functor >
template< typename Class, typename T, auto offset, auto Callback > template< typename Functor > QPropertyChangeHandler< T, Functor > QObjectBindableProperty< Class, T, Offset, Signal >::onValueChanged ( Functor f)
inline

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.

Definition at line 1183 of file qproperty.h.

Referenced by QObjectBindableProperty< Class, T, Offset, Signal >::subscribe().

+ Here is the caller graph for this function:

◆ operator parameter_type()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
QObjectBindableProperty< Class, T, Offset, Signal >::operator parameter_type ( ) const
inline

Definition at line 1093 of file qproperty.h.

References QObjectBindableProperty< Class, T, Offset, Signal >::value().

+ Here is the call graph for this function:

◆ operator*()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
parameter_type QObjectBindableProperty< Class, T, Offset, Signal >::operator* ( ) const
inline

Definition at line 1088 of file qproperty.h.

References QObjectBindableProperty< Class, T, Offset, Signal >::value().

+ Here is the call graph for this function:

◆ operator->()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
arrow_operator_result QObjectBindableProperty< Class, T, Offset, Signal >::operator-> ( ) const
inline

Definition at line 1076 of file qproperty.h.

References QPropertyData< T >::val, and QObjectBindableProperty< Class, T, Offset, Signal >::value().

+ Here is the call graph for this function:

◆ operator=() [1/2]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
QObjectBindableProperty & QObjectBindableProperty< Class, T, Offset, Signal >::operator= ( parameter_type newValue)
inline

Definition at line 1131 of file qproperty.h.

References QObjectBindableProperty< Class, T, Offset, Signal >::setValue().

+ Here is the call graph for this function:

◆ operator=() [2/2]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
QObjectBindableProperty & QObjectBindableProperty< Class, T, Offset, Signal >::operator= ( rvalue_ref newValue)
inline

Definition at line 1125 of file qproperty.h.

References QObjectBindableProperty< Class, T, Offset, Signal >::setValue().

+ Here is the call graph for this function:

◆ setBinding() [1/3]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template< typename Class, typename T, auto offset, auto Callback > QPropertyBinding< T > QObjectBindableProperty< Class, T, Offset, Signal >::setBinding ( const QPropertyBinding< T > & newBinding)
inline

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. When the property value changes, the owner is notified via the Callback function.

Definition at line 1137 of file qproperty.h.

References QBindingStorage::bindingData(), and qGetBindingStorage().

Referenced by QObjectBindableProperty< Class, T, Offset, Signal >::QObjectBindableProperty(), QObjectBindableProperty< Class, T, Offset, Signal >::setBinding(), QObjectBindableProperty< Class, T, Offset, Signal >::setBinding(), and QObjectBindableProperty< Class, T, Offset, Signal >::takeBinding().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ setBinding() [2/3]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template< typename Class, typename T, auto offset, auto Callback > QPropertyBinding< T > bool QObjectBindableProperty< Class, T, Offset, Signal >::setBinding ( const QUntypedPropertyBinding & newBinding)
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.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.

Definition at line 1144 of file qproperty.h.

References QMetaType::id(), QUntypedPropertyBinding::isNull(), QObjectBindableProperty< Class, T, Offset, Signal >::setBinding(), and QUntypedPropertyBinding::valueMetaType().

+ Here is the call graph for this function:

◆ setBinding() [3/3]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template<typename Functor >
QPropertyBinding< T > QObjectBindableProperty< Class, T, Offset, Signal >::setBinding ( Functor && f,
const QPropertyBindingSourceLocation & location = QT_PROPERTY_DEFAULT_BINDING_LOCATION,
std::enable_if_t< std::is_invocable_v< Functor > > * = nullptr )
inline

Definition at line 1154 of file qproperty.h.

References Qt::makePropertyBinding(), and QObjectBindableProperty< Class, T, Offset, Signal >::setBinding().

+ Here is the call graph for this function:

◆ setValue() [1/2]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template< typename Class, typename T, auto offset, auto Callback > void QObjectBindableProperty< Class, T, Offset, Signal >::setValue ( parameter_type t)
inline

Definition at line 1098 of file qproperty.h.

References QBindingStorage::bindingData(), QObjectBindableProperty< Class, T, Offset, Signal >::notify(), qGetBindingStorage(), and QtPrivate::QPropertyBindingData::removeBinding().

Referenced by QObjectBindableProperty< Class, T, Offset, Signal >::operator=(), and QObjectBindableProperty< Class, T, Offset, Signal >::operator=().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ setValue() [2/2]

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template< typename Class, typename T, auto offset, auto Callback > void QObjectBindableProperty< Class, T, Offset, Signal >::setValue ( rvalue_ref newValue)
inline

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

If the property value changes as a result, calls the Callback function on owner.

Definition at line 1114 of file qproperty.h.

References QBindingStorage::bindingData(), QObjectBindableProperty< Class, T, Offset, Signal >::notify(), qGetBindingStorage(), and QtPrivate::QPropertyBindingData::removeBinding().

+ Here is the call graph for this function:

◆ subscribe()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template<typename Functor >
template< typename Class, typename T, auto offset, auto Callback > template< typename Functor > QPropertyChangeHandler< T, Functor > QObjectBindableProperty< Class, T, Offset, Signal >::subscribe ( Functor f)
inline

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

Definition at line 1190 of file qproperty.h.

References QObjectBindableProperty< Class, T, Offset, Signal >::onValueChanged().

+ Here is the call graph for this function:

◆ takeBinding()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template< typename Class, typename T, auto offset, auto Callback > QPropertyBinding< T > QObjectBindableProperty< Class, T, Offset, Signal >::takeBinding ( )
inline

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.

Definition at line 1177 of file qproperty.h.

References QObjectBindableProperty< Class, T, Offset, Signal >::setBinding().

+ Here is the call graph for this function:

◆ value()

template<typename Class , typename T , auto Offset, auto Signal = nullptr>
template< typename Class, typename T, auto offset, auto Callback > T QObjectBindableProperty< Class, T, Offset, Signal >::value ( ) const
inline

Returns the value of the property.

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

Definition at line 1070 of file qproperty.h.

References qGetBindingStorage(), QBindingStorage::registerDependency(), and QPropertyData< T >::val.

Referenced by QObjectBindableProperty< Class, T, Offset, Signal >::operator parameter_type(), QObjectBindableProperty< Class, T, Offset, Signal >::operator*(), and QObjectBindableProperty< Class, T, Offset, Signal >::operator->().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

The documentation for this class was generated from the following files: