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 COMPONENTS Qml REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Qml)
qmake: QT += qml
Since: Qt 5.0

Public Types

AppendFunction
AtFunction
ClearFunction
CountFunction
RemoveLastFunction
ReplaceFunction

Public Functions

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

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.

See also Extending QML - Object and List Property Types Example.

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

QQmlListProperty::QQmlListProperty(QObject *object, void *data, QQmlListProperty::CountFunction count, QQmlListProperty::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 object exists.

QQmlListProperty::QQmlListProperty(QObject *object, void *data, QQmlListProperty::AppendFunction append, QQmlListProperty::CountFunction count, QQmlListProperty::AtFunction at, QQmlListProperty::ClearFunction clear, QQmlListProperty::ReplaceFunction replace, QQmlListProperty::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 object 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.

QQmlListProperty::QQmlListProperty(QObject *object, void *data, QQmlListProperty::AppendFunction append, QQmlListProperty::CountFunction count, QQmlListProperty::AtFunction at, QQmlListProperty::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 object 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.

[since 5.15] QQmlListProperty::QQmlListProperty(QObject *object, QList<T *> *list)

Convenience constructor for making a QQmlListProperty value from an existing QList list. The list reference must remain valid for as long as object exists. object must be provided.

This function was introduced in Qt 5.15.

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

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

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

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

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

© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-6.0/qqmllistproperty.html