QQmlListProperty Class

template <typename T> class QQmlListProperty

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

Header:	`#include <QQmlListProperty>`
CMake:	`find_package(Qt6 REQUIRED COMPONENTS Qml)` `target_link_libraries(mytarget PRIVATE Qt6::Qml)`
qmake:	`QT += qml`

List of all members, including inherited members

Public Types

	AppendFunction
	AtFunction
	ClearFunction
	CountFunction
	RemoveLastFunction
	ReplaceFunction

Public Variables

void *	data
QObject *	object

Macros

	QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_APPEND
	QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
	QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT

Detailed Description

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)

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 QQmlListReference to manipulate a QQmlListProperty from C++ using a slightly more ergonomic API, at the cost of some overhead.

Member Type Documentation

`[alias]` QQmlListProperty::AppendFunction

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

Append the value to the list property.

`[alias]` QQmlListProperty::AtFunction

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

Return the element at position index in the list property.

`[alias]` QQmlListProperty::ClearFunction

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

Clear the list property.

`[alias]` QQmlListProperty::CountFunction

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

Return the number of elements in the list property.

`[alias]` QQmlListProperty::RemoveLastFunction

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

Remove the last element from the list property.

`[alias]` QQmlListProperty::ReplaceFunction

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

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

Member Variable Documentation

void *QQmlListProperty::data

This field can hold an arbitrary data pointer

If you manually implement the accessor methods and need to store custom data, you can pass an arbitrary pointer to the QQmlListProperty constructor and retrieve it from the data field when accessing the same QQmlListProperty later.

A QQmlListProperty constructed from a QList pointer uses this field to store the pointer to the list itself, as it cannot directly access the list contents from the owner.

QObject *QQmlListProperty::object

This field holds the owner of the QQmlListProperty

When manually implementing the accessor methods, you may need to use this field for retrieving the content of the manipulated list.

Macro Documentation

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();
     // ...
 };

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();
     // ...
 };

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();
     // ...
 };

Contents