list QML Value Type

a list of QML objects. More...

Detailed Description

The list type refers to a list of QML objects or values.

Properties of type list are empty by default.

A list can store QML objects or value type values.

When integrating with C++, note that any QQmlListProperty value passed into QML from C++ is automatically converted into a list value, and vice-versa.

Similarly any QList<T> of a registered value type T is automatically converted into a list value, and vice-versa.

Using the list Type

For example, the Item type has a states list-type property that can be assigned to and used as follows:

 import QtQuick

 Item {
     width: 100; height: 100

     states: [
         State { name: "activated" },
         State { name: "deactivated" }
     ]

     Component.onCompleted: {
         console.log("Name of first state:", states[0].name)
         for (var i = 0; i < states.length; i++)
             console.log("state", i, states[i].name)
     }
 }

The defined State objects will be added to the states list in the order in which they are defined.

If the list only contains one object, the square brackets may be omitted:

 import QtQuick

 Item {
     width: 100; height: 100
     states: State { name: "activated" }
 }

You can also declare your own list properties in QML:

 import QtQml

 QtObject {
     property list<int> intList: [1, 2, 3, 4]
     property list<QtObject> objectList
 }

Lists can be used much like JavaScript arrays. For example:

• Values are assigned using the [] square bracket syntax with comma-separated values
• The length property provides the number of items in the list
• Values in the list are accessed using the [index] syntax
• You can use push() to append entries
• You can set the length property of the list to truncate or extend it.

However, you can not automatically extend the list by assigning to an index currently out of range. Furthermore, if you insert null values into a list of objects, those are converted to nullptr entries in the underlying QQmlListProperty.

A list of value types is different from a JavaScript array in one further important aspect: Growing it by setting its length does not produce undefined entries, but rather default-constructed instances of the value type.

Similarly, growing a list of object types this way produces null entries, rather than undefined entries.

This value type is provided by the QML language.

See also QML Value Types.