Back to Qt.io
Contact Us Blog Download Qt

C

Qul::ListProperty Struct

template <typename T> struct Qul::ListProperty

Use the ListProperty class to hold a list of a given type. More...

Header: #include <qul/listproperty.h>
Since: Qt Quick Ultralite 2.9

Public Functions

ListProperty()
void append(T t)
T at(int index)
void clear()
int count() const
bool isDynamic() const
bool isNull() const
bool isStatic() const
Qul::ListProperty<T> &load(const L &otherList)
void removeLast()
void replace(int index, T newValue)
void setList(Qul::DynamicList<T> *l)
void setList(Qul::StaticList<T> *l)
Qul::ListProperty<T> &operator=(const L &otherList)
T operator[](int index) const

Detailed Description

Use this class as a public member of your C++ objects, which are exposed as list of properties for that object in QML. The template parameter of the class defines the C++ type and is mapped to a corresponding QML type.

struct MyObjectWithList : public Qul::Object
{
    Qul::ListProperty<int> list1;
    Qul::ListProperty<MyData *> list2;
    MyObjectWithList()
    {
        static Qul::StaticListFixed<int, 100> buffer;
        buffer.replace(0, 1);
        // ... further initialization
        list1.setList(&buffer);
    }
};

You can use the C++ list properties in QML bindings.

As you can see in the following example, it's possible to assign JavaScript arrays to lists 

MyObjectWithList {
    // list1 is declared and initiated in c++
    property int value: list1[0]
    // list2 is declared in c++ and initiated here
    list2: [
        MyData { val: 100 },
        MyData { val: 200 }
    ]
}

It is also possible to declare the list in Grouped properties

struct MyObject : public Qul::Object
{
    struct Grouped
    {
        Qul::Property<int> val1;
        Qul::Property<int> val2;
        Qul::ListProperty<int> list1;
    };
    Grouped group;
};

List storage

In QUL it is possible to choose between two storage types, depending on whether the list has to grow or not.

You can set the storage explicitly in cpp on a Qul::ListProperty by using the setList function as shown here

DynamicList

A DynamicList is the default storage for QML lists without special keywords. Qt Quick Ultralite stores the items in the heap using a linked list. Use DynamicList only when you know that the list should grow, ohterwise use static_list instead.

Qul::ListProperty<int> list;
list.setList(new Qul::DynamicList<int>());

StaticList

To avoid heap allocation, you can use StaticList storage instead. A StaticList only needs the array pointer and its size to statically allocate memory, reducing memory overhead at runtime.

//... declaration
Qul::ListProperty<int> list;
int data[10];
Qul::StaticList<int> storage;
//... initialization
storage.size = 10;
storage.data = data;
list.setList(storage);

StaticListFixed

As it is a recurring pattern to declare an array along with a StaticList, and initialize both. You can use StaticListFixed (inherits StaticList) to simplify that, so you can use it as a storage for a ListProperty.

Unlike StaticList which depends on an external pointer not managed by it, a StaticListFixed manages the array internally and cleans the array when it is destroyed.

// ... declaration
Qul::ListProperty<int> list;
// T t[N=10] will be added as a member of the StaticListFixed
Qul::StaticListFixed<int, 10> staticList;
// ... initialization and usage
list.setList(&staticList);

Supported operations

ListProperty supports the following operations. Depending on the storage used, some operations may not be possible, so it is necessary to set the correct storage before using these restricted functions.

  • append(): Adds a new item to the end of the list, supported on DynamicList only as StaticList array can't grow.
  • count(): Return the number of items in the list, supported on both storage types.
  • at(index): Returns the item at the specified index, supported on both storage types.
  • operator[]: Returns the item at the specified index, supported on both storage types. Returns a constant item unlike at .
  • replace(index,newValue): Replaces the item at the specified index with a new item, supported on both storage types.
  • clear(): Removes all nodes on the DynamicList's LinkedList, unsupported on StaticList.
  • removeLast(): Removes the last item in the list, supported on DynamicList only.

See also list and QML Basic Types.

Member Function Documentation

ListProperty::ListProperty()

Creates a ListProperty without a specific List Storage type.

void ListProperty::append(T t)

Adds a new item to the end of the list and set it's value to t .

Note: This function is supported only with DynamicList storage.

T ListProperty::at(int index)

Returns the item at the specified index.

Use ListProperty::replace instead if you want to change a basic type.

void ListProperty::clear()

Removes all nodes on the DynamicList's LinkedList.

Note: This function is supported only with DynamicList storage.

int ListProperty::count() const

Returns the number of items in the list.

bool ListProperty::isDynamic() const

Returns true if the list is using a DynamicList storage, otherwise returns false.

bool ListProperty::isNull() const

Returns true if the list is not initialized, otherwise returns false.

bool ListProperty::isStatic() const

Returns true if the list is using a StaticList storage, otherwise returns false.

template <typename L> Qul::ListProperty<T> &ListProperty::load(const L &otherList)

Copies the items from otherList into L list, following same rules that are used with Qul::ListProperty::operator=.

void ListProperty::removeLast()

Removes the last item in the list.

Note: This function is supported only with DynamicList storage.

void ListProperty::replace(int index, T newValue)

Sets the value of the item at the specified index to newValue.

void ListProperty::setList(Qul::DynamicList<T> *l)

Use l DynamicList as the list's storage. Qt Quick Ultralite calls this function implicitly when initializing the list in QML.

void ListProperty::setList(Qul::StaticList<T> *l)

Use l StaticList as the list's storage. Qt Quick Ultralite calls this function implicitly when initializing a list with static_list or readonly keyword in QML.

template <typename L> Qul::ListProperty<T> &ListProperty::operator=(const L &otherList)

Load the items from otherList into L, which should also be a ListProperty.

The assignment operator uses the following rules depending on the size of the two lists, L and otherList, irrespective of their storage type:

  • If the size of L is greater than the size of otherList, items in L are replaced by items in otherList up to the size of otherList.
  • If the size of L is less than the size of otherList, items in L are replaced by items in otherList up to the size of L.
  • If the size of L is equal to the size of otherList, items in L are replaced by items in otherList up to the size of L.
  • The type of the items in otherList should be the same as the type of the items in L list.

The assignment operator is based on Qul::ListProperty::load

T ListProperty::operator[](int index) const

Returns the item at the specified index.

Use ListProperty::replace instead if you want to change a basic type.

Available under certain Qt licenses.
Find out more.