\inmodule QtCore More...

#include <qproperty.h>

Inheritance diagram for QProperty< T >:

Collaboration diagram for QProperty< T >:

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
	QProperty ()=default
	Constructs a property with a default constructed instance of T.

	QProperty (parameter_type initialValue)

	QProperty (rvalue_ref initialValue)

	QProperty (const QPropertyBinding< T > &binding)
	Constructs a property that is tied to the provided binding expression.

template<typename Functor>
	QProperty (Functor &&f, const QPropertyBindingSourceLocation &location=QT_PROPERTY_DEFAULT_BINDING_LOCATION, typename std::enable_if_t< std::is_invocable_r_v< T, Functor & > > *=nullptr)

	~QProperty ()=default
	Destroys the property.

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 (rvalue_ref newValue)

void	setValue (parameter_type newValue)
	Assigns newValue to this property and removes the property's associated binding, if present.

QProperty< T > &	operator= (rvalue_ref newValue)

QProperty< T > &	operator= (parameter_type newValue)
	Assigns newValue to this property and returns a reference to this QProperty.

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

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< Functor >	onValueChanged (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< Functor >	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.

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::QPropertyBindingData &	bindingData () 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.

Related Symbols
(Note that these are not member symbols.)
void	beginPropertyUpdateGroup ()

void	endPropertyUpdateGroup ()

Additional Inherited Members
Protected Attributes inherited from QPropertyData< T >
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 T>
class QProperty< T >

\inmodule QtCore

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

Since: 6.0

QProperty<T> is one of the classes implementing \l {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 \l QProperty in \l 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.

Definition at line 351 of file qproperty.h.

Member Typedef Documentation

◆ arrow_operator_result

template<typename T>

using QProperty< T >::arrow_operator_result = typename QPropertyData<T>::arrow_operator_result

Definition at line 367 of file qproperty.h.

◆ parameter_type

template<typename T>

using QProperty< T >::parameter_type = typename QPropertyData<T>::parameter_type

Definition at line 365 of file qproperty.h.

◆ rvalue_ref

template<typename T>

using QProperty< T >::rvalue_ref = typename QPropertyData<T>::rvalue_ref

Definition at line 366 of file qproperty.h.

◆ value_type

template<typename T>

using QProperty< T >::value_type = typename QPropertyData<T>::value_type

Definition at line 364 of file qproperty.h.

Constructor & Destructor Documentation

◆ QProperty() [1/5]

template<typename T>

QProperty< T >::QProperty ( )

default

Constructs a property with a default constructed instance of T.

◆ QProperty() [2/5]

template<typename T>

QProperty< T >::QProperty ( parameter_type initialValue )

inlineexplicit

Definition at line 370 of file qproperty.h.

◆ QProperty() [3/5]

template<typename T>

QProperty< T >::QProperty ( rvalue_ref initialValue )

inlineexplicit

Definition at line 371 of file qproperty.h.

◆ QProperty() [4/5]

template<typename T>

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

inlineexplicit

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.

Definition at line 372 of file qproperty.h.

References setBinding().

Here is the call graph for this function:

◆ QProperty() [5/5]

template<typename T>

template<typename Functor>

QProperty< T >::QProperty	(	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 377 of file qproperty.h.

◆ ~QProperty()

template<typename T>

QProperty< T >::~QProperty ( )

default

Destroys the property.

Member Function Documentation

◆ addNotifier()

template<typename T>

template<typename Functor>

QPropertyNotifier QProperty< T >::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 499 of file qproperty.h.

◆ binding()

template<typename T>

QPropertyBinding< T > QProperty< T >::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 473 of file qproperty.h.

◆ bindingData()

template<typename T>

const QtPrivate::QPropertyBindingData & QProperty< T >::bindingData ( ) const

inline

Definition at line 505 of file qproperty.h.

◆ hasBinding()

template<typename T>

bool QProperty< T >::hasBinding ( ) const

inline

Definition at line 471 of file qproperty.h.

◆ onValueChanged()

template<typename T>

template<typename Functor>

QPropertyChangeHandler< Functor > QProperty< T >::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 484 of file qproperty.h.

References QPropertyChangeHandler< Functor >::QPropertyChangeHandler().

Here is the call graph for this function:

◆ operator parameter_type()

template<typename T>

QProperty< T >::operator parameter_type ( ) const

inline

Definition at line 410 of file qproperty.h.

References value().

Here is the call graph for this function:

◆ operator*()

template<typename T>

parameter_type QProperty< T >::operator* ( ) const

inline

Definition at line 405 of file qproperty.h.

References value().

Here is the call graph for this function:

◆ operator->()

template<typename T>

arrow_operator_result QProperty< T >::operator-> ( ) const

inline

Definition at line 393 of file qproperty.h.

References value().

Here is the call graph for this function:

◆ operator=() [1/2]

template<typename T>

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

inline

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

Definition at line 439 of file qproperty.h.

◆ operator=() [2/2]

template<typename T>

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

inline

Definition at line 433 of file qproperty.h.

◆ setBinding() [1/3]

template<typename T>

QPropertyBinding< T > QProperty< T >::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.

Definition at line 445 of file qproperty.h.

Referenced by QProperty(), setBinding(), and setBinding().

Here is the caller graph for this function:

◆ setBinding() [2/3]

template<typename T>

bool QProperty< T >::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 450 of file qproperty.h.

References setBinding().

Here is the call graph for this function:

◆ setBinding() [3/3]

template<typename T>

template<typename Functor>

QPropertyBinding< T > QProperty< T >::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 460 of file qproperty.h.

References setBinding().

Here is the call graph for this function:

◆ setValue() [1/2]

template<typename T>

void QProperty< T >::setValue ( parameter_type newValue )

inline

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

Definition at line 424 of file qproperty.h.

◆ setValue() [2/2]

template<typename T>

void QProperty< T >::setValue ( rvalue_ref newValue )

inline

Definition at line 415 of file qproperty.h.

◆ subscribe()

template<typename T>

template<typename Functor>

QPropertyChangeHandler< Functor > QProperty< T >::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 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.

Definition at line 491 of file qproperty.h.

◆ takeBinding()

template<typename T>

QPropertyBinding< T > QProperty< T >::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 478 of file qproperty.h.

◆ value()

template<typename T>

parameter_type QProperty< T >::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 387 of file qproperty.h.

Referenced by operator parameter_type(), operator*(), and operator->().

Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ beginPropertyUpdateGroup()

template<typename T>

void beginPropertyUpdateGroup ( )

Since: 6.2

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.

See also: Qt::endPropertyUpdateGroup, QScopedPropertyUpdateGroup

Definition at line 190 of file qproperty.cpp.

◆ endPropertyUpdateGroup()

template<typename T>

void endPropertyUpdateGroup ( )

Since: 6.2

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.

See also: Qt::beginPropertyUpdateGroup, QScopedPropertyUpdateGroup

Definition at line 210 of file qproperty.cpp.

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

qtbase/src/corelib/kernel/qproperty.h (b2eb422699118f4ae8370519b4c7bb3fe121beb2)
qtbase/src/corelib/kernel/qproperty.cpp (2ef55de1029281d997a99c67764c239daadf6e08)

Public Types

Public Member Functions

Related Symbols

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ arrow_operator_result

◆ parameter_type

◆ rvalue_ref

◆ value_type

Constructor & Destructor Documentation

◆ QProperty() [1/5]

◆ QProperty() [2/5]

◆ QProperty() [3/5]

◆ QProperty() [4/5]

◆ QProperty() [5/5]

◆ ~QProperty()

Member Function Documentation

◆ addNotifier()

◆ binding()

◆ bindingData()

◆ hasBinding()

◆ onValueChanged()

◆ operator parameter_type()

◆ operator*()

◆ operator->()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ setBinding() [1/3]

◆ setBinding() [2/3]

◆ setBinding() [3/3]

◆ setValue() [1/2]

◆ setValue() [2/2]

◆ subscribe()

◆ takeBinding()

◆ value()

Friends And Related Symbol Documentation

◆ beginPropertyUpdateGroup()

◆ endPropertyUpdateGroup()