<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qqmlxmllistmodel.cpp -->
<title>XmlListModel QML Type | Qt Quick 5.9</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.9</td><td ><a href="qtquick-index.html">Qt Quick</a></td><td ><a href="qtquick-qmlmodule.html">QML Types</a></td><td >XmlListModel QML Type</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</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="#using-key-xml-roles">Using Key XML Roles</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">XmlListModel QML Type</h1>
<span class="subtitle"></span>
<!-- $$$XmlListModel-brief -->
<p>For specifying a read-only model using XPath expressions <a href="#details">More...</a></p>
<!-- @@@XmlListModel -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Import Statement:</td><td class="memItemRight bottomAlign"> import QtQuick.XmlListModel 2.0</td></tr></table></div><ul>
<li><a href="qml-qtquick-xmllistmodel-xmllistmodel-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-qtquick-xmllistmodel-xmllistmodel.html#count-prop">count</a></b></b> : int</li>
<li class="fn"><b><b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#namespaceDeclarations-prop">namespaceDeclarations</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#progress-prop">progress</a></b></b> : real</li>
<li class="fn"><b><b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#query-prop">query</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#roles-prop">roles</a></b></b> : list<XmlRole></li>
<li class="fn"><b><b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#source-prop">source</a></b></b> : url</li>
<li class="fn"><b><b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#status-prop">status</a></b></b> : enumeration</li>
<li class="fn"><b><b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#xml-prop">xml</a></b></b> : string</li>
</ul>
<a name="methods"></a>
<h2 id="methods">Methods</h2>
<ul>
<li class="fn">void <b><b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#errorString-method">errorString</a></b></b>()</li>
<li class="fn">object <b><b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#get-method">get</a></b></b>(int <i>index</i>)</li>
<li class="fn">void <b><b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#reload-method">reload</a></b></b>()</li>
</ul>
<!-- $$$XmlListModel-description -->
<a name="details"></a>
<h2 id="details">Detailed Description</h2>
<p>To use this element, you will need to import the module with the following line:</p>
<pre class="cpp">
import <span class="type"><a href="qtquick-qmlmodule.html">QtQuick</a></span><span class="operator">.</span>XmlListModel <span class="number">2.0</span>
</pre>
<p><a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a> is used to create a read-only model from XML data. It can be used as a data source for view elements (such as <a href="qml-qtquick-listview.html">ListView</a>, <a href="qml-qtquick-pathview.html">PathView</a>, <a href="qml-qtquick-gridview.html">GridView</a>) and other elements that interact with model data (such as <a href="qml-qtquick-repeater.html">Repeater</a>).</p>
<p>For example, if there is a XML document at http://www.mysite.com/feed.xml like this:</p>
<pre class="cpp">
<span class="operator"><</span><span class="operator">?</span>xml version<span class="operator">=</span><span class="string">"1.0"</span> encoding<span class="operator">=</span><span class="string">"utf-8"</span><span class="operator">?</span><span class="operator">></span>
<span class="operator"><</span>rss version<span class="operator">=</span><span class="string">"2.0"</span><span class="operator">></span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="operator"><</span>channel<span class="operator">></span>
<span class="operator"><</span>item<span class="operator">></span>
<span class="operator"><</span>title<span class="operator">></span>A blog post<span class="operator"><</span><span class="operator">/</span>title<span class="operator">></span>
<span class="operator"><</span>pubDate<span class="operator">></span>Sat<span class="operator">,</span> <span class="number">07</span> Sep <span class="number">2010</span> <span class="number">10</span>:<span class="number">00</span>:<span class="number">01</span> GMT<span class="operator"><</span><span class="operator">/</span>pubDate<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>item<span class="operator">></span>
<span class="operator"><</span>item<span class="operator">></span>
<span class="operator"><</span>title<span class="operator">></span>Another blog post<span class="operator"><</span><span class="operator">/</span>title<span class="operator">></span>
<span class="operator"><</span>pubDate<span class="operator">></span>Sat<span class="operator">,</span> <span class="number">07</span> Sep <span class="number">2010</span> <span class="number">15</span>:<span class="number">35</span>:<span class="number">01</span> GMT<span class="operator"><</span><span class="operator">/</span>pubDate<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>item<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>channel<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>rss<span class="operator">></span>
</pre>
<p>A <a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a> could create a model from this data, like this:</p>
<pre class="qml">
import QtQuick 2.0
import QtQuick.XmlListModel 2.0
<span class="type"><a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a></span> {
<span class="name">id</span>: <span class="name">xmlModel</span>
<span class="name">source</span>: <span class="string">"http://www.mysite.com/feed.xml"</span>
<span class="name">query</span>: <span class="string">"/rss/channel/item"</span>
<span class="type"><a href="qml-qtquick-xmllistmodel-xmlrole.html">XmlRole</a></span> { <span class="name">name</span>: <span class="string">"title"</span>; <span class="name">query</span>: <span class="string">"title/string()"</span> }
<span class="type"><a href="qml-qtquick-xmllistmodel-xmlrole.html">XmlRole</a></span> { <span class="name">name</span>: <span class="string">"pubDate"</span>; <span class="name">query</span>: <span class="string">"pubDate/string()"</span> }
}
</pre>
<p>The <a href="qml-qtquick-xmllistmodel-xmllistmodel.html#query-prop">query</a> value of "/rss/channel/item" specifies that the <a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a> should generate a model item for each <code><item></code> in the XML document.</p>
<p>The <a href="qml-qtquick-xmllistmodel-xmlrole.html">XmlRole</a> objects define the model item attributes. Here, each model item will have <code>title</code> and <code>pubDate</code> attributes that match the <code>title</code> and <code>pubDate</code> values of its corresponding <code><item></code>. (See <a href="qml-qtquick-xmllistmodel-xmlrole.html#query-prop">XmlRole::query</a> for more examples of valid XPath expressions for <a href="qml-qtquick-xmllistmodel-xmlrole.html">XmlRole</a>.)</p>
<p>The model could be used in a <a href="qml-qtquick-listview.html">ListView</a>, like this:</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
<span class="name">width</span>: <span class="number">180</span>; <span class="name">height</span>: <span class="number">300</span>
<span class="name">model</span>: <span class="name">xmlModel</span>
<span class="name">delegate</span>: <span class="name">Text</span> { <span class="name">text</span>: <span class="name">title</span> <span class="operator">+</span> <span class="string">": "</span> <span class="operator">+</span> <span class="name">pubDate</span> }
}
</pre>
<p class="centerAlign"><img src="images/qml-xmllistmodel-example.png" alt="" /></p><p>The <a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a> data is loaded asynchronously, and <a href="qml-qtquick-xmllistmodel-xmllistmodel.html#status-prop">status</a> is set to <code>XmlListModel.Ready</code> when loading is complete. Note this means when <a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a> is used for a view, the view is not populated until the model is loaded.</p>
<a name="using-key-xml-roles"></a>
<h3 >Using Key XML Roles</h3>
<p>You can define certain roles as "keys" so that when <a href="qml-qtquick-xmllistmodel-xmllistmodel.html#reload-method">reload()</a> is called, the model will only add and refresh data that contains new values for these keys.</p>
<p>For example, if above role for "pubDate" was defined like this instead:</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-xmllistmodel-xmlrole.html">XmlRole</a></span> { <span class="name">name</span>: <span class="string">"pubDate"</span>; <span class="name">query</span>: <span class="string">"pubDate/string()"</span>; <span class="name">isKey</span>: <span class="number">true</span> }
</pre>
<p>Then when <a href="qml-qtquick-xmllistmodel-xmllistmodel.html#reload-method">reload()</a> is called, the model will only add and reload items with a "pubDate" value that is not already present in the model.</p>
<p>This is useful when displaying the contents of XML documents that are incrementally updated (such as RSS feeds) to avoid repainting the entire contents of a model in a view.</p>
<p>If multiple key roles are specified, the model only adds and reload items with a combined value of all key roles that is not already present in the model.</p>
<p><b>See also </b><a href="qtquick-demos-rssnews-example.html">Qt Quick Demo - RSS News</a>.</p>
<!-- @@@XmlListModel -->
<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">int</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>The number of data entries in the model.</p>
</div></div><!-- @@@count -->
<br/>
<!-- $$$namespaceDeclarations -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="namespaceDeclarations-prop">
<td class="tblQmlPropNode"><p>
<a name="namespaceDeclarations-prop"></a><span class="name">namespaceDeclarations</span> : <span class="type">string</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>The namespace declarations to be used in the XPath queries.</p>
<p>The namespaces should be declared as in XQuery. For example, if a requested document at http://mysite.com/feed.xml uses the namespace "http://www.w3.org/2005/Atom", this can be declared as the default namespace:</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a></span> {
<span class="name">source</span>: <span class="string">"http://mysite.com/feed.xml"</span>
<span class="name">query</span>: <span class="string">"/feed/entry"</span>
<span class="name">namespaceDeclarations</span>: <span class="string">"declare default element namespace 'http://www.w3.org/2005/Atom';"</span>
<span class="type"><a href="qml-qtquick-xmllistmodel-xmlrole.html">XmlRole</a></span> { <span class="name">name</span>: <span class="string">"title"</span>; <span class="name">query</span>: <span class="string">"title/string()"</span> }
}
</pre>
</div></div><!-- @@@namespaceDeclarations -->
<br/>
<!-- $$$progress -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="progress-prop">
<td class="tblQmlPropNode"><p>
<a name="progress-prop"></a><span class="name">progress</span> : <span class="type">real</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>This indicates the current progress of the downloading of the XML data source. This value ranges from 0.0 (no data downloaded) to 1.0 (all data downloaded). If the XML data is not from a remote source, the progress becomes 1.0 as soon as the data is read.</p>
<p>Note that when the progress is 1.0, the XML data has been downloaded, but it is yet to be loaded into the model at this point. Use the status property to find out when the XML data has been read and loaded into the model.</p>
<p><b>See also </b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#status-prop">status</a> and <a href="qml-qtquick-xmllistmodel-xmllistmodel.html#source-prop">source</a>.</p>
</div></div><!-- @@@progress -->
<br/>
<!-- $$$query -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="query-prop">
<td class="tblQmlPropNode"><p>
<a name="query-prop"></a><span class="name">query</span> : <span class="type">string</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>An absolute XPath query representing the base query for creating model items from this model's <a href="qml-qtquick-xmllistmodel-xmlrole.html">XmlRole</a> objects. The query should start with '/' or '//'.</p>
</div></div><!-- @@@query -->
<br/>
<!-- $$$roles -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="roles-prop">
<td class="tblQmlPropNode"><p>
<a name="roles-prop"></a><span class="name">roles</span> : <span class="type">list</span><<span class="type"><a href="qml-qtquick-xmllistmodel-xmlrole.html">XmlRole</a></span>></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>The roles to make available for this model.</p>
</div></div><!-- @@@roles -->
<br/>
<!-- $$$source -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="source-prop">
<td class="tblQmlPropNode"><p>
<a name="source-prop"></a><span class="name">source</span> : <span class="type">url</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>The location of the XML data source.</p>
<p>If both <code>source</code> and <a href="qml-qtquick-xmllistmodel-xmllistmodel.html#xml-prop">xml</a> are set, <a href="qml-qtquick-xmllistmodel-xmllistmodel.html#xml-prop">xml</a> is used.</p>
</div></div><!-- @@@source -->
<br/>
<!-- $$$status -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="status-prop">
<td class="tblQmlPropNode"><p>
<a name="status-prop"></a><span class="name">status</span> : <span class="type">enumeration</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Specifies the model loading status, which can be one of the following:</p>
<ul>
<li><a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a>.Null - No XML data has been set for this model.</li>
<li><a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a>.Ready - The XML data has been loaded into the model.</li>
<li><a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a>.Loading - The model is in the process of reading and loading XML data.</li>
<li><a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a>.Error - An error occurred while the model was loading. See <a href="qml-qtquick-xmllistmodel-xmllistmodel.html#errorString-method">errorString()</a> for details about the error.</li>
</ul>
<p><b>See also </b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#progress-prop">progress</a>.</p>
</div></div><!-- @@@status -->
<br/>
<!-- $$$xml -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="xml-prop">
<td class="tblQmlPropNode"><p>
<a name="xml-prop"></a><span class="name">xml</span> : <span class="type">string</span></p></td></tr>
</table></div>
</div><div class="qmldoc"><p>This property holds the XML data for this model, if set.</p>
<p>The text is assumed to be UTF-8 encoded.</p>
<p>If both <a href="qml-qtquick-xmllistmodel-xmllistmodel.html#source-prop">source</a> and <code>xml</code> are set, <code>xml</code> is used.</p>
</div></div><!-- @@@xml -->
<br/>
<h2>Method Documentation</h2>
<!-- $$$errorString -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="errorString-method">
<td class="tblQmlFuncNode"><p>
<a name="errorString-method"></a><span class="type">void</span> <span class="name">errorString</span>()</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Returns a string description of the last error that occurred if <a href="qml-qtquick-xmllistmodel-xmllistmodel.html#status-prop">status</a> is XmlListModel::Error.</p>
</div></div><!-- @@@errorString -->
<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">int</span> <i>index</i>)</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Returns the item at <i>index</i> in the model.</p>
<p>For example, for a model like this:</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-xmllistmodel-xmllistmodel.html">XmlListModel</a></span> {
<span class="name">id</span>: <span class="name">model</span>
<span class="name">source</span>: <span class="string">"http://mysite.com/feed.xml"</span>
<span class="name">query</span>: <span class="string">"/feed/entry"</span>
<span class="type"><a href="qml-qtquick-xmllistmodel-xmlrole.html">XmlRole</a></span> { <span class="name">name</span>: <span class="string">"title"</span>; <span class="name">query</span>: <span class="string">"title/string()"</span> }
}
</pre>
<p>This will access the <code>title</code> value for the first item in the model:</p>
<pre class="js">
var <span class="name">title</span> = <span class="name">model</span>.<span class="name">get</span>(<span class="number">0</span>).<span class="name">title</span>;
</pre>
</div></div><!-- @@@get -->
<br/>
<!-- $$$reload -->
<div class="qmlitem"><div class="qmlproto">
<div class="table"><table class="qmlname">
<tr valign="top" class="odd" id="reload-method">
<td class="tblQmlFuncNode"><p>
<a name="reload-method"></a><span class="type">void</span> <span class="name">reload</span>()</p></td></tr>
</table></div>
</div><div class="qmldoc"><p>Reloads the model.</p>
<p>If no key roles have been specified, all existing model data is removed, and the model is rebuilt from scratch.</p>
<p>Otherwise, items are only added if the model does not already contain items with matching key role values.</p>
<p><b>See also </b><a href="qml-qtquick-xmllistmodel-xmllistmodel.html#using-key-xml-roles">Using key XML roles</a> and <a href="qml-qtquick-xmllistmodel-xmlrole.html#isKey-prop">XmlRole::isKey</a>.</p>
</div></div><!-- @@@reload -->
<br/>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 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>
