- Qt 6.9
- Qt Qml
- C++ Classes
- QQmlListProperty
- Qt 6.9.3 Reference Documentation

# QQmlListProperty Class

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
- Deprecated members

## Public Types

| AppendFunction
| AtFunction
| ClearFunction
| RemoveLastFunction
| ReplaceFunction

## Public Functions

| QQmlListProperty(QObject *object, QList<T *> *list)
| QQmlListProperty(QObject *object, void *data, int count, QQmlListProperty<T>::AtFunction at)
| QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::AppendFunction append, int count, QQmlListProperty<T>::AtFunction at, QQmlListProperty<T>::ClearFunction clear)
| QQmlListProperty(QObject *object, void *data, QQmlListProperty<T>::AppendFunction append, int count, QQmlListProperty<T>::AtFunction at, QQmlListProperty<T>::ClearFunction clear, QQmlListProperty<T>::ReplaceFunction replace, QQmlListProperty<T>::RemoveLastFunction removeLast)
bool | operator==(const QQmlListProperty<T> &other) const

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

See also Chapter 5: Using List Property Types and QQmlListReference.

## 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::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 Function Documentation

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

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:

     QQmlListProperty<PieSlice> PieChart::slices()
     {
         return QQmlListProperty<PieSlice>(this, &m_slices);
     }

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

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.

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

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.

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

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

- 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

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.

### bool QQmlListProperty::operator==(const QQmlListProperty<T> &other) const

Returns true if this QQmlListProperty is equal to other, otherwise false.

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

See also QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE_IF_NOT_DEFAULT, QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE, and Defining Object Types through QML Documents.

### 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, and Defining Object Types through QML Documents.

### 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, and Defining Object Types through QML Documents.