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

You should initialize all lists at least once from Cpp or QML for them to be usable. See List Storage for more information.

A list can store QML components or QML Basic types. It also can store C++ types that inherit Qul::Object.

When integrating with C++, not that any Qul::ListProperty is automatically converted into a QML list property , and vice-versa.

Using the list Type

For example, the Animation type and Timeline has properties of list type. The following example shows how to use such properties in QML:

import QtQuick

Item {
    width: 100; height: 100

    // Object list
    Timeline {
        id: timeline
        animations: [
            TimelineAnimation { running: true; pingPong: true},
            TimelineAnimation { running: false; pingPong: false}
        ]
    }

    // basic list
    NumberAnimation on x {
        easing.bezierCurve: [0.455, 0.030, 0.515, 0.955, 1, 1]
        easing.type: Easing.BezierSpline
    }

    // accessing lists
    Component.onCompleted: {
        for (var i = 0; i < states.length; i++)
            console.log(
            "Animation %1 running : %2 "
            .arg(i)
            .arg(timeline.animations[i].running));
    }
}

Qt Quick Ultralite adds the TimelineAnimation objects to the animations list in the order in which they are defined.

You can also declare custom list properties in QML:

import QtQml

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

Qt Quick Ultralite tools rely on Qt Quick 6.2.x, where it is not possible to use a template type for a list of QML Basic Types, but it is possible to specify a template type for a list of objects. Qt Quick Ultralite infers the type of basic values from the list items as follows:

• Numbers: Stored as Qul::ListProperty<qreal>.
• String: Optimized as internal Qt Quick Ultralite string type.
• Booleans: stored as Qul::ListProperty<bool>.
• Enums: The corresponding enum type of the list items will be used.
• Points: If the list items are defined as points using Qt.point(x,y), they are stored as Qul::PlatformInterface::PointF.
• Rectangles: If the list items are defined as rects using Qt.rect(x,y,w,h), they are stored as Qul::PlatformInterface::RectF.
• Matrix4x4: If the list items are defined as matrix4x4 using Qt.matrix4x4(m00,m01,...m16), they are stored as Qt Quick Ultralite internal type for matrix4x4.
• Colors: If the list items are defined as colors using Qt.rgba(r,g,b,a), they are stored as Qul::PlatformInterface::Rgba32

Example:

property list mylist_custom_double : [1.1, 2.2, 3.3, 4.4]
property list mylist_custom_bool : [true, false, true, false]
property list mylist_custom_enum : [TestObject.Value1, TestObject.Value2, TestObject.Value3, TestObject.Value1]
property list mylist_custom_string : ["a", "b", "c", "d"]
property list mylist_custom_rects: [
    Qt.rect(0, 0, 100, 100),
    Qt.rect(100, 0, 100, 100)
]

In such cases, use lists much like JavaScript arrays, with limited support on what functions can be used on the list. Qt Quick Ultralite supports the following operations on such lists:

• 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.
• you can use removeLast() to remove the last item in the list

However, you cannot automatically extend the list by assigning to an index currently out of range.

struct MyObject : public Qul::Object
{
    // use 'Component*' and not 'Component'
    Qul::ListProperty<MyComponent*> components;
};

import QtQuick
MyObject {
    components: [
        MyComponent { }
    ]
}

If you have a list of objects, and you bind a usual Property 'p0' to a list item's property 'p1', The value of 'p0' will automatically updated when 'p1' changes.

Item {
    property list<MyData> myDataList: [
        MyData { val: 100 },
        MyData { val: 200 }
    ]
    property int value2: myDataList[1].val
    function updateValue2(newValue) {
        // value2 property is updated automatically
        myDataList[1].val = newValue
    }
}

Qt Quick Ultralite does not support currently to bind to a list, or to a value within a list of QML Basic Types.

When a property is initialized with a value of basic type within a list, Qt Quick Ultralite copies the value from the list without binding to it. if you need to update the value again, do that in a function or a signal handler.

ROM usage will be less if you can avoid bindings for basic types. Refer to Split large ListModels for more information about how to do this with ListModels. This approach is specially useful if the ListElement properties do not change.

Similar to QML Basic Types, the length property is also copied and not bound to. To update length property of a model that grows are reduces its size, use another function or signal handler.

Item {
    property list<MyData> myDataList: [
        MyData { val: 100 },
        MyData { val: 200 }
    ]
    property int value2: myDataList[1].val
    function updateValue2(newValue) {
        // value2 property is updated automatically
        myDataList[1].val = newValue
    }
}

A list of value types is different from a JavaScript array in how they handle resizing. Resizing the former by increasing its length property adds default-constructed instances of the value type, whereas a JavaScript array adds undefined entries.

Similarly, resizing a list of object types results in an error if there is no default constructor. This behavior is different in Qt Quick Ultralite compared to Qt, where extended list of objects are filled with null values instead of default constructed objects.

Initializing a list in QML

As described in the List Storage section, there are two ways to store a list in Qt Quick Ultralite depending on whether the list should resize or not. Initialize the list at least once from C++ or QML, otherwise the storage is set to null.

Qt Quick Ultralite uses DynamicList by default to store a list when no special QML keywords are used. The following example demonstrates this usecase:

MyObject {
    //Custom list, will use a dynamic list by default
    property list numbers: [1, 2, 3, 4]
    // defined in c++, it will use a dynamic list as well
    numbers_cpp: [1, 2, 3, 4]
}

In order to avoid heap allocation, you can change the default behavior and rely on StaticList instead by using the readonly keyword as follows:

MyObject {
    //Custom list, will use a static list
    readonly property list points: [Qt.point(1,2), Qt.point(3,4)]
}

You can use the readonly keyword only for custom lists declared in the .qml files. To declare static lists in C++ and use in QML, use the static_list initializer function. The following example demonstrates how to do this:

• static_list(array): Simplest use case is to store an array in a static list.

  MyCppObject {
      // numbers declared as ListProperty<int>
      numbers: static_list([1, 2, 3, 4])
  }

• static_list(array, size): Allocate memory on a static list without explicitly initializing all items, to have a buffer. The default constructor is called for rest of the items.

  Initializing a type without defining a default constructor, results in a build-time error.

  MyCppObject {
      // numbers declared as ListProperty<int>
      numbers: static_list([1, 2, 3, 4], 100)
  }

• static_list(initializer_list [, size]): When you want to have a static list of objects, Duo to syntax limitations, it is impossible to initiate a objects within a list within a function as shown here:

  MyCppObject {
      // objects declared as ListProperty<Data*>
      // !!!! this will not compile
      objects: static_list([MyData { value: 1 }, MyData { value: 2 }])
  }

  A workaround that you can use is to initialize the objects in a separate list and pass it's id to static_list.

  Note: data_init is used to initialize the objects only and is not read or write further in the qml file.

  MyCppObject {
      property list<Data> data_init: [MyData { value: 1 }, MyData { value: 2 }]
      // objects declared as ListProperty<Data*>
      objects: static_list(data_init, 100)
  }

  You need this approach to set the list size explicitly, otherwise consider using the readonly keyword instead.

Use static_list on custom QML lists as well, to allocate a specific storage size as demonstrated in the following example:

Usage:

Item {
    id: root
    property list int_list: [1, 2, 3, 4]
    property list int_list2: [4, 3, 2, 1]
    property int at2: root.int_list[2]
    property int counter: 0
    function test_lists() {
      for (var i=0; i < 4; i ++){
        counter = int_list[i]  // access
        console.log(int_list[i])
      }
      int_list[i] = 0   // assignment
      int_list.length = 20 // truncate (expand)
      int_list.removeLast() // removeLast
      int_list = int_list2 // list to list assignment
    }
}