QQmlListProperty Class

The QQmlListProperty class allows applications to expose list-like properties to QML. More...

Header: #include <QQmlListProperty>
qmake: QT += qml
Since: Qt 5.0

Public Types

typedef AppendFunction
typedef AtFunction
typedef ClearFunction
typedef CountFunction

Public Functions

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

Detailed Description

The QQmlListProperty class allows applications to expose list-like properties to QML.

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.

The Qt Quick 1 version of this class is named QDeclarativeListProperty.

Note: QQmlListProperty can only be used for lists of QObject-derived object pointers.

Member Type Documentation

typedef QQmlListProperty::AppendFunction

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

Append the value to the list property.

typedef QQmlListProperty::AtFunction

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

Return the element at position index in the list property.

typedef QQmlListProperty::ClearFunction

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

Clear the list property.

typedef QQmlListProperty::CountFunction

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

Return the number of elements in the list property.

Member Function Documentation

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.

Generally this constructor should not be used in production code, as a writable QList violates QML's memory management rules. However, this constructor can be very useful while prototyping.

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

Construct a QQmlListProperty from a set of operation functions. 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.

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

Construct a readonly QQmlListProperty from a set of operation functions. An opaque data handle may be passed which can be accessed from within the operation functions. The list property remains valid while object exists.

bool QQmlListProperty::operator==(const QQmlListProperty & other) const

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

Notes provided by the Qt Community
Informative
  • 0

Votes: 0

Coverage: Qt 5

Picture of Andre Andre

Robot Herder
30 notes

Nokia Certified Qt Developer

Don't forget to register the type with the QML engine

If your list property doesn’t work on a type already known to the QML engine, make sure you have registered it explicitly! Otherwise, you’ll get strange errors, including an error about the property being read-only.

This can be relevant in cases where you have a common base class for some concrete element types that you use as the list type. To just create the elements, you’d only need to register the actual element types. But in order to use the QQmlListProperty, you will have to also register the base class (as a non-creatable type). Of course, the base class still needs to derive from QObject.

[Revisions]