1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qdeclarativexmllistmodel.cpp -->
<title>Qt 4.8: QML XmlListModel Element</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="content">
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
</div>
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li><a href="qdeclarativeelements.html">QML Elements</a></li>
<li>QML XmlListModel Element</li>
</ul>
</div>
</div>
<div class="content mainContent">
<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>
<h1 class="title">QML XmlListModel Element</h1>
<span class="subtitle"></span>
<!-- $$$XmlListModel-brief -->
<p>The XmlListModel element is used to specify a read-only model using XPath expressions. <a href="#details">More...</a></p>
<!-- @@@XmlListModel -->
<p>This element was introduced in Qt 4.7.</p>
<ul>
<li><a href="qml-xmllistmodel-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="properties"></a>
<h2>Properties</h2>
<ul>
<li class="fn"><b><b><a href="qml-xmllistmodel.html#count-prop">count</a></b></b> : int</li>
<li class="fn"><b><b><a href="qml-xmllistmodel.html#namespaceDeclarations-prop">namespaceDeclarations</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-xmllistmodel.html#progress-prop">progress</a></b></b> : real</li>
<li class="fn"><b><b><a href="qml-xmllistmodel.html#query-prop">query</a></b></b> : string</li>
<li class="fn"><b><b><a href="qml-xmllistmodel.html#roles-prop">roles</a></b></b> : list<XmlRole></li>
<li class="fn"><b><b><a href="qml-xmllistmodel.html#source-prop">source</a></b></b> : url</li>
<li class="fn"><b><b><a href="qml-xmllistmodel.html#status-prop">status</a></b></b> : enumeration</li>
<li class="fn"><b><b><a href="qml-xmllistmodel.html#xml-prop">xml</a></b></b> : string</li>
</ul>
<a name="methods"></a>
<h2>Methods</h2>
<ul>
<li class="fn"><b><b><a href="qml-xmllistmodel.html#errorString-method">errorString</a></b></b></li>
<li class="fn"><b><b><a href="qml-xmllistmodel.html#get-method">get</a></b></b></li>
<li class="fn"><b><b><a href="qml-xmllistmodel.html#reload-method">reload</a></b></b></li>
</ul>
<!-- $$$XmlListModel-description -->
<a name="details"></a>
<h2>Detailed Description</h2>
<p>XmlListModel 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-listview.html">ListView</a>, <a href="qml-pathview.html">PathView</a>, <a href="qml-gridview.html">GridView</a>) and other elements that interact with model data (such as <a href="qml-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 XmlListModel could create a model from this data, like this:</p>
<pre class="qml"> import QtQuick 1.0
<span class="type">XmlListModel</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-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-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-xmllistmodel.html#query-prop">query</a> value of "/rss/channel/item" specifies that the XmlListModel should generate a model item for each <tt><item></tt> in the XML document.</p>
<p>The <a href="qml-xmlrole.html">XmlRole</a> objects define the model item attributes. Here, each model item will have <tt>title</tt> and <tt>pubDate</tt> attributes that match the <tt>title</tt> and <tt>pubDate</tt> values of its corresponding <tt><item></tt>. (See <a href="qml-xmlrole.html#query-prop">XmlRole::query</a> for more examples of valid XPath expressions for <a href="qml-xmlrole.html">XmlRole</a>.)</p>
<p>The model could be used in a <a href="qml-listview.html">ListView</a>, like this:</p>
<pre class="qml"> <span class="type"><a href="qml-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 XmlListModel data is loaded asynchronously, and <a href="qml-xmllistmodel.html#status-prop">status</a> is set to <tt>XmlListModel.Ready</tt> when loading is complete. Note this means when XmlListModel 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-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-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-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="demos-declarative-rssnews.html">RSS News</a>.</p>
<!-- @@@XmlListModel -->
<h2>Property Documentation</h2>
<!-- $$$count -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="count-prop"></a><span class="qmlreadonly">read-only</span><span class="name">count</span> : <span class="type"><a href="qml-int.html">int</a></span></p></td></tr></table></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"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="namespaceDeclarations-prop"></a><span class="name">namespaceDeclarations</span> : <span class="type"><a href="qml-string.html">string</a></span></p></td></tr></table></div><div class="qmldoc"><p>The namespace declarations to be used in the XPath queries.</p>
<p>The namespaces should be declared as in <a href="xmlprocessing.html">XQuery</a>. 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-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-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"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="progress-prop"></a><span class="qmlreadonly">read-only</span><span class="name">progress</span> : <span class="type"><a href="qml-real.html">real</a></span></p></td></tr></table></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-xmllistmodel.html#status-prop">status</a> and <a href="qml-xmllistmodel.html#source-prop">source</a>.</p>
</div></div><!-- @@@progress -->
<br/>
<!-- $$$query -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="query-prop"></a><span class="name">query</span> : <span class="type"><a href="qml-string.html">string</a></span></p></td></tr></table></div><div class="qmldoc"><p>An absolute XPath query representing the base query for creating model items from this model's <a href="qml-xmlrole.html">XmlRole</a> objects. The query should start with '/' or '//'.</p>
</div></div><!-- @@@query -->
<br/>
<!-- $$$roles -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="roles-prop"></a><span class="qmlreadonly">read-only</span><span class="name">roles</span> : <span class="type"><a href="qml-list.html">list</a></span><<span class="type"><a href="qml-xmlrole.html">XmlRole</a></span>></p></td></tr></table></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"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="source-prop"></a><span class="name">source</span> : <span class="type"><a href="qml-url.html">url</a></span></p></td></tr></table></div><div class="qmldoc"><p>The location of the XML data source.</p>
<p>If both <tt>source</tt> and <a href="qml-xmllistmodel.html#xml-prop">xml</a> are set, <a href="qml-xmllistmodel.html#xml-prop">xml</a> is used.</p>
</div></div><!-- @@@source -->
<br/>
<!-- $$$status -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="status-prop"></a><span class="qmlreadonly">read-only</span><span class="name">status</span> : <span class="type"><a href="qml-enumeration.html">enumeration</a></span></p></td></tr></table></div><div class="qmldoc"><p>Specifies the model loading status, which can be one of the following:</p>
<ul>
<li><a href="qml-xmllistmodel.html">XmlListModel</a>.Null - No XML data has been set for this model.</li>
<li><a href="qml-xmllistmodel.html">XmlListModel</a>.Ready - The XML data has been loaded into the model.</li>
<li><a href="qml-xmllistmodel.html">XmlListModel</a>.Loading - The model is in the process of reading and loading XML data.</li>
<li><a href="qml-xmllistmodel.html">XmlListModel</a>.Error - An error occurred while the model was loading. See <a href="qml-xmllistmodel.html#errorString-method">errorString()</a> for details about the error.</li>
</ul>
<p><b>See also </b><a href="qml-xmllistmodel.html#progress-prop">progress</a>.</p>
</div></div><!-- @@@status -->
<br/>
<!-- $$$xml -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlPropNode"><p><a name="xml-prop"></a><span class="name">xml</span> : <span class="type"><a href="qml-string.html">string</a></span></p></td></tr></table></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-xmllistmodel.html#source-prop">source</a> and <tt>xml</tt> are set, <tt>xml</tt> is used.</p>
</div></div><!-- @@@xml -->
<br/>
<h2>Method Documentation</h2>
<!-- $$$errorString -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlFuncNode"><p><a name="errorString-method"></a><span class="type">void</span> XmlListModel::<span class="name">errorString</span> ()</p></td></tr></table></div><div class="qmldoc"><p>Returns a string description of the last error that occurred if <a href="qml-xmllistmodel.html#status-prop">status</a> is XmlListModel::Error.</p>
</div></div><!-- @@@errorString -->
<br/>
<!-- $$$get -->
<div class="qmlitem"><div class="qmlproto"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlFuncNode"><p><a name="get-method"></a><span class="type">object</span> XmlListModel::<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 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-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-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 <tt>title</tt> 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"><table class="qmlname"><tr valign="top" class="odd"><td class="tblQmlFuncNode"><p><a name="reload-method"></a>XmlListModel::<span class="name">reload</span> ()</p></td></tr></table></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-xmllistmodel.html#using-key-xml-roles">Using key XML roles</a> and <a href="qml-xmlrole.html#isKey-prop">XmlRole::isKey</a>.</p>
</div></div><!-- @@@reload -->
<br/>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2012 Nokia Corporation and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
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.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Nokia, Qt and their respective logos are trademarks of Nokia Corporation
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
</body>
</html>
|
