ListModel QML Element

TheListModel element defines a free-form list data source.More...

• List of all members, including inherited members

Properties

• count : int

Methods

• append(jsobject dict)
• clear()
• objectget(int index)
• insert(int index, jsobject dict)
• move(int from, int to, int n)
• remove(int index)
• set(int index, jsobject dict)
• setProperty(int index, string property, variant value)
• sync()

Detailed Description

TheListModel is a simple container ofListElement definitions, each containing data roles. The contents can be defined dynamically, or explicitly in QML.

The number of elements in the model can be obtained from itscount property. A number of familiar methods are also provided to manipulate the contents of the model, includingappend(),insert(),move(),remove() andset(). These methods accept dictionaries as their arguments; these are translated toListElement objects by the model.

Elements can be manipulated via the model using thesetProperty() method, which allows the roles of the specified element to be set and changed.

Example Usage

The following example shows aListModel containing three elements, with the roles "name" and "cost".

import QtQuick 1.0ListModel {id:fruitModelListElement {name:"Apple"cost:2.45    }ListElement {name:"Orange"cost:3.25    }ListElement {name:"Banana"cost:1.95    }}

Roles (properties) in each element must begin with a lower-case letter and should be common to all elements in a model. TheListElement documentation provides more guidelines for how elements should be defined.

Since the example model contains anid property, it can be referenced by views, such as theListView in this example:

import QtQuick 1.0Rectangle {width:200;height:200ListModel {id:fruitModel        ...    }Component {id:fruitDelegateRow {spacing:10Text {text:name }Text {text:'$'+cost }        }    }ListView {anchors.fill:parentmodel:fruitModeldelegate:fruitDelegate    }}

It is possible for roles to contain list data. In the following example we create a list of fruit attributes:

ListModel {id:fruitModelListElement {name:"Apple"cost:2.45attributes: [ListElement {description:"Core" },ListElement {description:"Deciduous" }        ]    }ListElement {name:"Orange"cost:3.25attributes: [ListElement {description:"Citrus" }        ]    }ListElement {name:"Banana"cost:1.95attributes: [ListElement {description:"Tropical" },ListElement {description:"Seedless" }        ]    }}

The delegate displays all the fruit attributes:

Component {id:fruitDelegateItem {width:200;height:50Text {id:nameField;text:name }Text {text:'$'+cost;anchors.left:nameField.right }Row {anchors.top:nameField.bottomspacing:5Text {text:"Attributes:" }Repeater {model:attributesText {text:description }            }        }    }}

Modifying List Models

The content of aListModel may be created and modified using theclear(),append(),set(),insert() andsetProperty() methods. For example:

Component {id:fruitDelegateItem {width:200;height:50Text {text:name }Text {text:'$'+cost;anchors.right:parent.right }// Double the price when clicked.MouseArea {anchors.fill:parentonClicked:fruitModel.setProperty(index,"cost",cost*2)            }        }    }

Note that when creating content dynamically the set of available properties cannot be changed once set. Whatever properties are first added to the model are the only permitted properties in the model.

Using Threaded List Models with WorkerScript

ListModel can be used together withWorkerScript access a list model from multiple threads. This is useful if list modifications are synchronous and take some time: the list operations can be moved to a different thread to avoid blocking of the main GUI thread.

Here is an example that usesWorkerScript to periodically append the current time to a list model:

The included file,dataloader.js, looks like this:

The timer in the main example sends messages to the worker script by callingWorkerScript::sendMessage(). When this message is received,WorkerScript.onMessage() is invoked indataloader.js, which appends the current time to the list model.

Note the call tosync() from theWorkerScript.onMessage() handler. You must callsync() or else the changes made to the list from the external thread will not be reflected in the list model in the main thread.

Restrictions

If a list model is to be accessed from aWorkerScript, it cannot contain list-type data. So, the following model cannot be used from aWorkerScript because of the list contained in the "attributes" property:

ListModel {    id: fruitModel    ListElement {        name:"Apple"        cost:2.45        attributes:[            ListElement { description:"Core" },            ListElement { description:"Deciduous" }]    }}

In addition, theWorkerScript cannot add list-type data to the model.

See alsoData Models,Threaded ListModel example, andQtDeclarative.

Property Documentation

Method Documentation

fruitModel.append({"cost":5.95,"name":"Pizza"})

    fruitModel.append(...,"attributes":[{"name":"spikes","value":"7mm"},         {"name":"color","value":"green"}]);    fruitModel.get(0).attributes.get(1).value;// == "green"