C
ListProperty Struct
template <typename T> struct Qul::ListPropertyUse 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 |
ListProperty<T> & | load(const L &otherList) |
void | removeLast() |
void | replace(int index, T newValue) |
void | setList(StaticList<T> *l) |
void | setList(DynamicList<T> *l) |
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 onDynamicList
only asStaticList
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 unlikeat
.replace(index,newValue)
: Replaces the item at the specified index with a new item, supported on both storage types.clear()
: Removes all nodes on theDynamicList
's LinkedList, unsupported onStaticList
.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> 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(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
.
void ListProperty::setList(DynamicList<T> *l)
Use l DynamicList as the list's storage. Qt Quick Ultralite calls this function implicitly when initializing the list in QML
.
template <typename L> 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 ofotherList
, items inL
are replaced by items inotherList
up to the size ofotherList
. - If the size of
L
is less than the size ofotherList
, items inL
are replaced by items inotherList
up to the size ofL
. - If the size of
L
is equal to the size ofotherList
, items inL
are replaced by items inotherList
up to the size ofL
. - The type of the items in
otherList
should be the same as the type of the items inL
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.