The QQmlListProperty class allows applications to expose list-like properties of QObject-derived classes to QML. More...

#include <qqmllist.h>

Collaboration diagram for QQmlListProperty< T >:

Public Types
using	value_type = T*

using	AppendFunction = void ()(QQmlListProperty<T> , T *)
	Synonym for `{void` ()(QQmlListProperty<T> property, T *value)}.

using	CountFunction = qsizetype ()(QQmlListProperty<T> )
	Synonym for `{qsizetype` ()(QQmlListProperty<T> property)}.

using	AtFunction = T ()(QQmlListProperty<T> *, qsizetype)
	Synonym for `{T` ()(QQmlListProperty<T> *property, qsizetype index)}.

using	ClearFunction = void ()(QQmlListProperty<T> )
	Synonym for `{void` ()(QQmlListProperty<T> property)}.

using	ReplaceFunction = void ()(QQmlListProperty<T> , qsizetype, T *)
	Synonym for `{void` ()(QQmlListProperty<T> property, qsizetype index, T *value)}.

using	RemoveLastFunction = void ()(QQmlListProperty<T> )
	Synonym for `{void` ()(QQmlListProperty<T> property)}.

Public Member Functions
	QQmlListProperty ()=default
	\macro QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND

	QQmlListProperty (QObject o, QList< T > *list)

	QQmlListProperty (QObject o, void d, AppendFunction a, CountFunction c, AtFunction t, ClearFunction r)
	Construct a QQmlListProperty from a set of operation functions append, count, at, and clear.

	QQmlListProperty (QObject o, void d, AppendFunction a, CountFunction c, AtFunction t, ClearFunction r, ReplaceFunction s, RemoveLastFunction p)
	Construct a QQmlListProperty from a set of operation functions append, count, at, clear, replace, and \removeLast.

	QQmlListProperty (QObject o, void d, CountFunction c, AtFunction a)
	Construct a readonly QQmlListProperty from a set of operation functions count and at.

bool	operator== (const QQmlListProperty &o) const
	Returns true if this QQmlListProperty is equal to other, otherwise false.

template<typename List>
List	toList ()

Public Attributes
QObject *	object = nullptr

void *	data = nullptr

AppendFunction	append = nullptr

CountFunction	count = nullptr

AtFunction	at = nullptr

ClearFunction	clear = nullptr

ReplaceFunction	replace = nullptr

RemoveLastFunction	removeLast = nullptr

Detailed Description

template<typename T>
class QQmlListProperty< T >

The QQmlListProperty class allows applications to expose list-like properties of QObject-derived classes to QML.

Since: 5.0 \inmodule QtQml

QML has many list properties, where more than one object value can be assigned. The use of a list property from QML looks like this:

FruitBasket {
    fruit: [
        Apple {},
        Orange{},
        Banana{}
    ]
}

The QQmlListProperty encapsulates a group of function pointers that represent the set of actions QML can perform on the list - adding items, retrieving items and clearing the list. In the future, additional operations may be supported. All list properties must implement the append operation, but the rest are optional.

To provide a list property, a C++ class must implement the operation callbacks, and then return an appropriate QQmlListProperty value from the property getter. List properties should have no setter. In the example above, the Q_PROPERTY() declarative will look like this:

Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)

QQmlListProperty::QQmlListProperty

QQmlListProperty()=default

\macro QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND

Q_PROPERTY

#define Q_PROPERTY(...)

Definition qtmetamacros.h:58

QML list properties are type-safe - in this case {Fruit} is a QObject type that {Apple}, {Orange} and {Banana} all derive from.

You can use \l{QQmlListReference} to manipulate a QQmlListProperty from C++ using a slightly more ergonomic API, at the cost of some overhead.

See also: {Chapter 5: Using List Property Types}, QQmlListReference

Definition at line 24 of file qqmllist.h.

Member Typedef Documentation

◆ AppendFunction

template<typename T>

using QQmlListProperty< T >::AppendFunction = void (*)(QQmlListProperty<T> *, T *)

Synonym for {void (*)(QQmlListProperty<T> *property, T *value)}.

Append the value to the list property.

Definition at line 28 of file qqmllist.h.

◆ AtFunction

template<typename T>

using QQmlListProperty< T >::AtFunction = T *(*)(QQmlListProperty<T> *, qsizetype)

Synonym for {T *(*)(QQmlListProperty<T> *property, qsizetype index)}.

Return the element at position index in the list property.

Definition at line 30 of file qqmllist.h.

◆ ClearFunction

template<typename T>

using QQmlListProperty< T >::ClearFunction = void (*)(QQmlListProperty<T> *)

Synonym for {void (*)(QQmlListProperty<T> *property)}.

Clear the list property.

Definition at line 31 of file qqmllist.h.

◆ CountFunction

template<typename T>

using QQmlListProperty< T >::CountFunction = qsizetype (*)(QQmlListProperty<T> *)

Synonym for {qsizetype (*)(QQmlListProperty<T> *property)}.

Return the number of elements in the list property.

Definition at line 29 of file qqmllist.h.

◆ RemoveLastFunction

template<typename T>

using QQmlListProperty< T >::RemoveLastFunction = void (*)(QQmlListProperty<T> *)

Synonym for {void (*)(QQmlListProperty<T> *property)}.

Remove the last element from the list property.

Definition at line 33 of file qqmllist.h.

◆ ReplaceFunction

template<typename T>

using QQmlListProperty< T >::ReplaceFunction = void (*)(QQmlListProperty<T> *, qsizetype, T *)

Synonym for {void (*)(QQmlListProperty<T> *property, qsizetype index, T *value)}.

Replace the element at position index in the list property with value.

Definition at line 32 of file qqmllist.h.

◆ value_type

template<typename T>

using QQmlListProperty< T >::value_type = T*

Definition at line 26 of file qqmllist.h.

Constructor & Destructor Documentation

◆ QQmlListProperty() [1/5]

template<typename T>

QQmlListProperty< T >::QQmlListProperty ( )

default

\macro QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND

This macro defines the behavior of the list properties of this class to Append. When assigning the property in a derived type, the values are appended to those of the base class. This is the default behavior.

class FruitBasket : QObject {
    Q_OBJECT
    QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND
    Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)
 
    public:
    // ...
    QQmlListProperty<Fruit> fruit();
    // ...
};

See also: QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT; QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE; {Defining Object Types through QML Documents}

\macro QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT

This macro defines the behavior of the list properties of this class to ReplaceIfNotDefault. When assigning the property in a derived type, the values replace those of the base class unless it's the default property. In the case of the default property, values are appended to those of the base class.

class FruitBasket : QObject {
    Q_OBJECT
    QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT
    Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)
 
    public:
    // ...
    QQmlListProperty<Fruit> fruit();
    // ...
};

See also: QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND; QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE; {Defining Object Types through QML Documents}

\macro QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE

This macro defines the behavior of the list properties of this class to Replace. When assigning the property in a derived type, the values replace those of the base class.

class FruitBasket : QObject {
    Q_OBJECT
    QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
    Q_PROPERTY(QQmlListProperty<Fruit> fruit READ fruit)
 
    public:
    // ...
    QQmlListProperty<Fruit> fruit();
    // ...
};

See also: QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND; QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT; {Defining Object Types through QML Documents}

◆ QQmlListProperty() [2/5]

template<typename T>

QQmlListProperty< T >::QQmlListProperty	(	QObject *	object,
		QList< T * > *	list )

inline

Since: 5.15

Convenience constructor for making a QQmlListProperty value from an existing QList list. The object owning the list and the list itself must be provided and kept alive as long as you are holding a QQmlListProperty referring to them.

This is the easiest and safest way to provide a QQmlListProperty backed by a QList and should be used in most cases. A typical invocation looks like this:

Definition at line 37 of file qqmllist.h.

Referenced by QQmlListProperty< QDeclarativePluginParameter >::QQmlListProperty().

Here is the caller graph for this function:

◆ QQmlListProperty() [3/5]

template<typename T>

QQmlListProperty< T >::QQmlListProperty	(	QObject *	object,
		void *	data,
		AppendFunction	append,
		CountFunction	count,
		AtFunction	at,
		ClearFunction	clear )

inline

Construct a QQmlListProperty from a set of operation functions append, count, at, and clear.

An opaque data handle may be passed which can be accessed from within the operation functions. The list property remains valid while the object owning the list property exists.

Null pointers can be passed for any function. If any null pointers are passed in, the list will be neither designable nor alterable by the debugger. It is recommended to provide valid pointers for all functions.

Note: The resulting QQmlListProperty will synthesize the removeLast() and replace() methods using count, at, clear, and append if all of those are given. This is slow. If you intend to manipulate the list beyond clearing it, you should explicitly provide these methods.

Definition at line 42 of file qqmllist.h.

Referenced by QQmlListProperty< QDeclarativePluginParameter >::QQmlListProperty().

Here is the caller graph for this function:

◆ QQmlListProperty() [4/5]

template<typename T>

QQmlListProperty< T >::QQmlListProperty	(	QObject *	object,
		void *	data,
		AppendFunction	append,
		CountFunction	count,
		AtFunction	at,
		ClearFunction	clear,
		ReplaceFunction	replace,
		RemoveLastFunction	removeLast )

inline

Construct a QQmlListProperty from a set of operation functions append, count, at, clear, replace, and \removeLast.

An opaque data handle may be passed which can be accessed from within the operation functions. The list property remains valid while the object owning the list property exists.

Null pointers can be passed for any function, causing the respective function to be synthesized using the others, if possible. QQmlListProperty can synthesize \list

clear using count and removeLast
replace using count, at, clear, and append
replace using count, at, removeLast, and append
removeLast using count, at, clear, and append \endlist if those are given. This is slow, but if your list does not natively provide faster options for these primitives, you may want to use the synthesized ones.

Furthermore, if either of count, at, append, and clear are neither given explicitly nor synthesized, the list will be neither designable nor alterable by the debugger. It is recommended to provide enough valid pointers to avoid this situation.

Definition at line 54 of file qqmllist.h.

Referenced by QQmlListProperty< QDeclarativePluginParameter >::QQmlListProperty().

Here is the caller graph for this function:

◆ QQmlListProperty() [5/5]

template<typename T>

QQmlListProperty< T >::QQmlListProperty	(	QObject *	object,
		void *	data,
		CountFunction	count,
		AtFunction	at )

inline

Construct a readonly QQmlListProperty from a set of operation functions count and at.

An opaque data handle may be passed which can be accessed from within the operation functions. The list property remains valid while the object owning the list property exists.

Definition at line 66 of file qqmllist.h.

Referenced by QQmlListProperty< QDeclarativePluginParameter >::QQmlListProperty().

Here is the caller graph for this function: