<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qqmllistmodel.cpp -->
<title>ListModel QML Type | Qt QML 5.12.6</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.12</td><td ><a href="qtqml-index.html">Qt QML</a></td><td ><a href="qtqml-qmlmodule.html">QML Types</a></td><td >ListModel QML Type</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="qtqml-index.html">Qt 5.12.6 Reference Documentation</a></td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#properties">Properties</a></li>
<li class="level1"><a href="#methods">Methods</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#example-usage">Example Usage</a></li>
<li class="level2"><a href="#modifying-list-models">Modifying List Models</a></li>
<li class="level2"><a href="#using-threaded-list-models-with-workerscript">Using Threaded List Models with WorkerScript</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">ListModel QML Type</h1>
<span class="subtitle"></span>
<!-- $$$ListModel-brief -->
<p>Defines a free-form list data source. <a href="#details">More...</a></p>
<!-- @@@ListModel -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Import Statement:</td><td class="memItemRight bottomAlign"> import QtQml.Models 2.12</td></tr></table></div><ul>
<li><a href="qml-qtqml-models-listmodel-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="properties"></a>
<h2 id="properties">Properties</h2>
<ul>
<li class="fn"><b><b><a href="qml-qtqml-models-listmodel.html#count-prop">count</a></b></b> : int</li>
<li class="fn"><b><b><a href="qml-qtqml-models-listmodel.html#dynamicRoles-prop">dynamicRoles</a></b></b> : bool</li>
</ul>
<a name="methods"></a>
<h2 id="methods">Methods</h2>
<ul>
<li class="fn"><b><b><a href="qml-qtqml-models-listmodel.html#append-method">append</a></b></b>(jsobject <i>dict</i>)</li>
<li class="fn"><b><b><a href="qml-qtqml-models-listmodel.html#clear-method">clear</a></b></b>()</li>
<li class="fn">object <b><b><a href="qml-qtqml-models-listmodel.html#get-method">get</a></b></b>(int <i>index</i>)</li>
<li class="fn"><b><b><a href="qml-qtqml-models-listmodel.html#insert-method">insert</a></b></b>(int <i>index</i>, jsobject <i>dict</i>)</li>
<li class="fn"><b><b><a href="qml-qtqml-models-listmodel.html#move-method">move</a></b></b>(int <i>from</i>, int <i>to</i>, int <i>n</i>)</li>
<li class="fn"><b><b><a href="qml-qtqml-models-listmodel.html#remove-method">remove</a></b></b>(int <i>index</i>, <i> int count = 1</i>)</li>
<li class="fn"><b><b><a href="qml-qtqml-models-listmodel.html#set-method">set</a></b></b>(int <i>index</i>, jsobject <i>dict</i>)</li>
<li class="fn"><b><b><a href="qml-qtqml-models-listmodel.html#setProperty-method">setProperty</a></b></b>(int <i>index</i>, string <i>property</i>, variant <i>value</i>)</li>
<li class="fn"><b><b><a href="qml-qtqml-models-listmodel.html#sync-method">sync</a></b></b>()</li>
</ul>
<!-- $$$ListModel-description -->
<a name="details"></a>
<h2 id="details">Detailed Description</h2>
<p>The <a href="qml-qtqml-models-listmodel.html">ListModel</a> is a simple container of <a href="qml-qtqml-models-listelement.html">ListElement</a> definitions, each containing data roles. The contents can be defined dynamically, or explicitly in QML.</p>
<p>The number of elements in the model can be obtained from its <a href="qml-qtqml-models-listmodel.html#count-prop">count</a> property. A number of familiar methods are also provided to manipulate the contents of the model, including <a href="qml-qtqml-models-listmodel.html#append-method">append()</a>, <a href="qml-qtqml-models-listmodel.html#insert-method">insert()</a>, <a href="qml-qtqml-models-listmodel.html#move-method">move()</a>, <a href="qml-qtqml-models-listmodel.html#remove-method">remove()</a> and <a href="qml-qtqml-models-listmodel.html#set-method">set()</a>. These methods accept dictionaries as their arguments; these are translated to <a href="qml-qtqml-models-listelement.html">ListElement</a> objects by the model.</p>
<p>Elements can be manipulated via the model using the <a href="qml-qtqml-models-listmodel.html#setProperty-method">setProperty()</a> method, which allows the roles of the specified element to be set and changed.</p>
<a name="example-usage"></a>
<h2 id="example-usage">Example Usage</h2>
<p>The following example shows a <a href="qml-qtqml-models-listmodel.html">ListModel</a> containing three elements, with the roles "name" and "cost".</p>
<div class="float-right"><p><img src="images/listmodel.png" alt="" /></p>
</div><pre class="qml">
import QtQuick 2.0
ListModel {
id: fruitModel
ListElement {
name: "Apple"
cost: 2.45
}
ListElement {
name: "Orange"
cost: 3.25
}
ListElement {
name: "Banana"
cost: 1.95
}
}
</pre>
<p>Roles (properties) in each element must begin with a lower-case letter and should be common to all elements in a model. The <a href="qml-qtqml-models-listelement.html">ListElement</a> documentation provides more guidelines for how elements should be defined.</p>
<p>Since the example model contains an <code>id</code> property, it can be referenced by views, such as the ListView in this example:</p>
<pre class="qml">
import QtQuick 2.0
Rectangle {
width: 200; height: 200
ListModel {
id: fruitModel
...
}
Component {
id: fruitDelegate
Row {
spacing: 10
Text { text: name }
Text { text: '$' + cost }
}
}
ListView {
anchors.fill: parent
model: fruitModel
delegate: fruitDelegate
}
}
</pre>
<p>It is possible for roles to contain list data. In the following example we create a list of fruit attributes:</p>
<pre class="qml">
ListModel {
id: fruitModel
ListElement {
name: "Apple"
cost: 2.45
attributes: [
ListElement { description: "Core" },
ListElement { description: "Deciduous" }
]
}
ListElement {
name: "Orange"
cost: 3.25
attributes: [
ListElement { description: "Citrus" }
]
}
ListElement {
name: "Banana"
cost: 1.95
attributes: [
ListElement { description: "Tropical" },
ListElement { description: "Seedless" }
]
}
}
</pre>
<p>The delegate displays all the fruit attributes:</p>
<div class="float-right"><p><img src="images/listmodel-nested.png" alt="" /></p>
</div><pre class="qml">
Component {
id: fruitDelegate
Item {
width: 200; height: 50
Text { id: nameField; text: name }
Text { text: '$' + cost; anchors.left: nameField.right }
Row {
anchors.top: nameField.bottom
spacing: 5
Text { text: "Attributes:" }
Repeater {
model: attributes
Text { text: description }
}
}
}
}
</pre>
<a name="modifying-list-models"></a>
<h2 id="modifying-list-models">Modifying List Models</h2>
<p>The content of a <a href="qml-qtqml-models-listmodel.html">ListModel</a> may be created and modified using the <a href="qml-qtqml-models-listmodel.html#clear-method">clear()</a>, <a href="qml-qtqml-models-listmodel.html#append-method">append()</a>, <a href="qml-qtqml-models-listmodel.html#set-method">set()</a>, <a href="qml-qtqml-models-listmodel.html#insert-method">insert()</a> and <a href="qml-qtqml-models-listmodel.html#setProperty-method">setProperty()</a> methods. For example:</p>
<pre class="qml">
Component {
id: fruitDelegate
Item {
width: 200; height: 50
Text { text: name }
Text { text: '$' + cost; anchors.right: parent.right }
// Double the price when clicked.
MouseArea {
anchors.fill: parent
onClicked: fruitModel.setProperty(index, "cost", cost * 2)
}
}
}
</pre>
<p>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.</p>
<a name="using-threaded-list-models-with-workerscript"></a>
<h2 id="using-threaded-list-models-with-workerscript">Using Threaded List Models with WorkerScript</h2>
<p><a href="qml-qtqml-models-listmodel.html">ListModel</a> can be used together with <a href="qml-workerscript.html">WorkerScript</a> 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.</p>
<p>Here is an example that uses <a href="qml-workerscript.html">WorkerScript</a> to periodically append the current time to a list model:</p>
<pre class="qml">
Timer {
id: timer
interval: 2000; repeat: true
running: true
triggeredOnStart: true
onTriggered: {
var msg = {'action': 'appendCurrentTime', 'model': listModel};
worker.sendMessage(msg);
}
}
</pre>
<p>The included file, <code>dataloader.mjs</code>, looks like this:</p>
<pre class="cpp">
WorkerScript.onMessage = function(msg) {
if (msg.action == 'appendCurrentTime') {
var data = {'time': new Date().toTimeString()};
msg.model.append(data);
msg.model.sync(); // updates the changes to the list
}
}
</pre>
<p>The timer in the main example sends messages to the worker script by calling <a href="qml-workerscript.html#sendMessage-method">WorkerScript::sendMessage()</a>. When this message is received, <code>WorkerScript.onMessage()</code> is invoked in <code>dataloader.mjs</code>, which appends the current time to the list model.</p>
<p>Note the call to <a href="qml-qtqml-models-listmodel.html#sync-method">sync()</a> from the external thread. You must call <a href="qml-qtqml-models-listmodel.html#sync-method">sync()</a> or else the changes made to the list from that thread will not be reflected in the list model in the main thread.</p>
<p><b>See also </b>Data Models, Qt Quick Examples - Threading, and <a href="qtqml-index.html">Qt QML</a>.</p>
<!-- @@@ListModel -->
<h2>Property Documentation</h2>
<!-- $$$count -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="count-prop">
<td class="tblQmlPropNode"><p>
<a name="count-prop"></a><span class="name">count</span> : <span class="type"><a href="qml-int.html">int</a></span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>The number of data entries in the model.</p>
</div></div><!-- @@@count -->
<br/>
<!-- $$$dynamicRoles -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="dynamicRoles-prop">
<td class="tblQmlPropNode"><p>
<a name="dynamicRoles-prop"></a><span class="name">dynamicRoles</span> : <span class="type"><a href="qml-bool.html">bool</a></span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>By default, the type of a role is fixed the first time the role is used. For example, if you create a role called "data" and assign a number to it, you can no longer assign a string to the "data" role. However, when the dynamicRoles property is enabled, the type of a given role is not fixed and can be different between elements.</p>
<p>The dynamicRoles property must be set before any data is added to the <a href="qml-qtqml-models-listmodel.html">ListModel</a>, and must be set from the main thread.</p>
<p>A <a href="qml-qtqml-models-listmodel.html">ListModel</a> that has data statically defined (via the <a href="qml-qtqml-models-listelement.html">ListElement</a> QML syntax) cannot have the dynamicRoles property enabled.</p>
<p>There is a significant performance cost to using a <a href="qml-qtqml-models-listmodel.html">ListModel</a> with dynamic roles enabled. The cost varies from platform to platform but is typically somewhere between 4-6x slower than using static role types.</p>
<p>Due to the performance cost of using dynamic roles, they are disabled by default.</p>
</div></div><!-- @@@dynamicRoles -->
<br/>
<h2>Method Documentation</h2>
<!-- $$$append -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="append-method">
<td class="tblQmlFuncNode"><p>
<a name="append-method"></a><span class="name">append</span>(<span class="type">jsobject</span> <i>dict</i>)</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Adds a new item to the end of the list model, with the values in <i>dict</i>.</p>
<pre class="cpp">
fruitModel<span class="operator">.</span>append({<span class="string">"cost"</span>: <span class="number">5.95</span><span class="operator">,</span> <span class="string">"name"</span>:<span class="string">"Pizza"</span>})
</pre>
<p><b>See also </b><a href="qml-qtqml-models-listmodel.html#set-method">set()</a> and <a href="qml-qtqml-models-listmodel.html#remove-method">remove()</a>.</p>
</div></div><!-- @@@append -->
<br/>
<!-- $$$clear -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="clear-method">
<td class="tblQmlFuncNode"><p>
<a name="clear-method"></a><span class="name">clear</span>()</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Deletes all content from the model.</p>
<p><b>See also </b><a href="qml-qtqml-models-listmodel.html#append-method">append()</a> and <a href="qml-qtqml-models-listmodel.html#remove-method">remove()</a>.</p>
</div></div><!-- @@@clear -->
<br/>
<!-- $$$get -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="get-method">
<td class="tblQmlFuncNode"><p>
<a name="get-method"></a><span class="type">object</span> <span class="name">get</span>(<span class="type"><a href="qml-int.html">int</a></span> <i>index</i>)</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Returns the item at <i>index</i> in the list model. This allows the item data to be accessed or modified from JavaScript:</p>
<pre class="cpp">
Component<span class="operator">.</span>onCompleted: {
fruitModel<span class="operator">.</span>append({<span class="string">"cost"</span>: <span class="number">5.95</span><span class="operator">,</span> <span class="string">"name"</span>:<span class="string">"Jackfruit"</span>});
console<span class="operator">.</span>log(fruitModel<span class="operator">.</span>get(<span class="number">0</span>)<span class="operator">.</span>cost);
fruitModel<span class="operator">.</span>get(<span class="number">0</span>)<span class="operator">.</span>cost <span class="operator">=</span> <span class="number">10.95</span>;
}
</pre>
<p>The <i>index</i> must be an element in the list.</p>
<p>Note that properties of the returned object that are themselves objects will also be models, and this get() method is used to access elements:</p>
<pre class="cpp">
fruitModel<span class="operator">.</span>append(<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span><span class="operator">,</span> <span class="string">"attributes"</span>:
<span class="operator">[</span>{<span class="string">"name"</span>:<span class="string">"spikes"</span><span class="operator">,</span><span class="string">"value"</span>:<span class="string">"7mm"</span>}<span class="operator">,</span>
{<span class="string">"name"</span>:<span class="string">"color"</span><span class="operator">,</span><span class="string">"value"</span>:<span class="string">"green"</span>}<span class="operator">]</span>);
fruitModel<span class="operator">.</span>get(<span class="number">0</span>)<span class="operator">.</span>attributes<span class="operator">.</span>get(<span class="number">1</span>)<span class="operator">.</span>value; <span class="comment">// == "green"</span>
</pre>
<p><b>Warning:</b> The returned object is not guaranteed to remain valid. It should not be used in <a href="qtqml-syntax-propertybinding.html">property bindings</a>.</p>
<p><b>See also </b><a href="qml-qtqml-models-listmodel.html#append-method">append()</a>.</p>
</div></div><!-- @@@get -->
<br/>
<!-- $$$insert -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="insert-method">
<td class="tblQmlFuncNode"><p>
<a name="insert-method"></a><span class="name">insert</span>(<span class="type"><a href="qml-int.html">int</a></span> <i>index</i>, <span class="type">jsobject</span> <i>dict</i>)</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Adds a new item to the list model at position <i>index</i>, with the values in <i>dict</i>.</p>
<pre class="cpp">
fruitModel<span class="operator">.</span>insert(<span class="number">2</span><span class="operator">,</span> {<span class="string">"cost"</span>: <span class="number">5.95</span><span class="operator">,</span> <span class="string">"name"</span>:<span class="string">"Pizza"</span>})
</pre>
<p>The <i>index</i> must be to an existing item in the list, or one past the end of the list (equivalent to append).</p>
<p><b>See also </b><a href="qml-qtqml-models-listmodel.html#set-method">set()</a> and <a href="qml-qtqml-models-listmodel.html#append-method">append()</a>.</p>
</div></div><!-- @@@insert -->
<br/>
<!-- $$$move -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="move-method">
<td class="tblQmlFuncNode"><p>
<a name="move-method"></a><span class="name">move</span>(<span class="type"><a href="qml-int.html">int</a></span> <i>from</i>, <span class="type"><a href="qml-int.html">int</a></span> <i>to</i>, <span class="type"><a href="qml-int.html">int</a></span> <i>n</i>)</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Moves <i>n</i> items <i>from</i> one position <i>to</i> another.</p>
<p>The from and to ranges must exist; for example, to move the first 3 items to the end of the list:</p>
<pre class="cpp">
fruitModel<span class="operator">.</span>move(<span class="number">0</span><span class="operator">,</span> fruitModel<span class="operator">.</span>count <span class="operator">-</span> <span class="number">3</span><span class="operator">,</span> <span class="number">3</span>)
</pre>
<p><b>See also </b><a href="qml-qtqml-models-listmodel.html#append-method">append()</a>.</p>
</div></div><!-- @@@move -->
<br/>
<!-- $$$remove -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="remove-method">
<td class="tblQmlFuncNode"><p>
<a name="remove-method"></a><span class="name">remove</span>(<span class="type"><a href="qml-int.html">int</a></span> <i>index</i>, <i> int count = 1</i>)</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Deletes the content at <i>index</i> from the model.</p>
<p><b>See also </b><a href="qml-qtqml-models-listmodel.html#clear-method">clear()</a>.</p>
</div></div><!-- @@@remove -->
<br/>
<!-- $$$set -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="set-method">
<td class="tblQmlFuncNode"><p>
<a name="set-method"></a><span class="name">set</span>(<span class="type"><a href="qml-int.html">int</a></span> <i>index</i>, <span class="type">jsobject</span> <i>dict</i>)</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Changes the item at <i>index</i> in the list model with the values in <i>dict</i>. Properties not appearing in <i>dict</i> are left unchanged.</p>
<pre class="cpp">
fruitModel<span class="operator">.</span>set(<span class="number">3</span><span class="operator">,</span> {<span class="string">"cost"</span>: <span class="number">5.95</span><span class="operator">,</span> <span class="string">"name"</span>:<span class="string">"Pizza"</span>})
</pre>
<p>If <i>index</i> is equal to count() then a new item is appended to the list. Otherwise, <i>index</i> must be an element in the list.</p>
<p><b>See also </b><a href="qml-qtqml-models-listmodel.html#append-method">append()</a>.</p>
</div></div><!-- @@@set -->
<br/>
<!-- $$$setProperty -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="setProperty-method">
<td class="tblQmlFuncNode"><p>
<a name="setProperty-method"></a><span class="name">setProperty</span>(<span class="type"><a href="qml-int.html">int</a></span> <i>index</i>, <span class="type"><a href="qml-string.html">string</a></span> <i>property</i>, <span class="type"><a href="qml-variant.html">variant</a></span> <i>value</i>)</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Changes the <i>property</i> of the item at <i>index</i> in the list model to <i>value</i>.</p>
<pre class="cpp">
fruitModel<span class="operator">.</span>setProperty(<span class="number">3</span><span class="operator">,</span> <span class="string">"cost"</span><span class="operator">,</span> <span class="number">5.95</span>)
</pre>
<p>The <i>index</i> must be an element in the list.</p>
<p><b>See also </b><a href="qml-qtqml-models-listmodel.html#append-method">append()</a>.</p>
</div></div><!-- @@@setProperty -->
<br/>
<!-- $$$sync -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="sync-method">
<td class="tblQmlFuncNode"><p>
<a name="sync-method"></a><span class="name">sync</span>()</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Writes any unsaved changes to the list model after it has been modified from a worker script.</p>
</div></div><!-- @@@sync -->
<br/>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2019 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br/> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br/> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-updates
>
by-pkgid
>
6e2327ca1c896c6d674ae53117299f21
>
files
>
102
