/usr/share/qt5/doc/qtquick/qtquick-modelviewsdata-modelview.html is in qtdeclarative5-doc-html 5.5.1-2ubuntu6.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- modelview.qdoc -->
<title>Models and Views in Qt Quick | Qt Quick 5.5</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.5</li>
<li><a href="qtquick-index.html">Qt Quick</a></li>
<li>Models and Views in Qt Quick</li>
<li id="buildversion">Qt 5.5.1 Reference Documentation</li>
</ul>
</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="#displaying-data-with-views">Displaying Data with Views</a></li>
<li class="level2"><a href="#decorating-views">Decorating Views</a></li>
<li class="level2"><a href="#mouse-and-touch-handling">Mouse and Touch Handling</a></li>
<li class="level2"><a href="#listview-sections">ListView Sections</a></li>
<li class="level1"><a href="#view-delegates">View Delegates</a></li>
<li class="level2"><a href="#accessing-views-and-models-from-delegates">Accessing Views and Models from Delegates</a></li>
<li class="level1"><a href="#models">Models</a></li>
<li class="level2"><a href="#listmodel">ListModel</a></li>
<li class="level2"><a href="#xmllistmodel">XmlListModel</a></li>
<li class="level2"><a href="#visualitemmodel">VisualItemModel</a></li>
<li class="level2"><a href="#integers-as-models">Integers as Models</a></li>
<li class="level2"><a href="#object-instances-as-models">Object Instances as Models</a></li>
<li class="level2"><a href="#c-data-models">C++ Data Models</a></li>
<li class="level1"><a href="#repeaters">Repeaters</a></li>
<li class="level1"><a href="#using-transitions">Using Transitions</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<a name="qtquick-views"></a><a name="qml-view-delegate"></a><a name="qml-data-models"></a><a name="qml-c-models"></a><h1 class="title">Models and Views in Qt Quick</h1>
<span class="subtitle"></span>
<!-- $$$qtquick-modelviewsdata-modelview.html-description -->
<div class="descr"> <a name="details"></a>
<p>Simply put, applications need to form data and display the data. Qt Quick has the notion of <i>models</i>, <i>views</i>, and <i>delegates</i> to display data. They modularize the visualization of data in order to give the developer or designer control over the different aspects of the data. A developer can swap a list view with a grid view with little changes to the data. Similarly, encapsulating an instance of the data in a delegate allows the developer to dictate how to present or handle the data.</p>
<p class="centerAlign"><img src="images/modelview-overview.png" alt="" /></p><ul>
<li><b>Model</b> - contains the data and its structure. There are several QML types for creating models.</li>
<li><b>View</b> - a container that displays the data. The view might display the data in a list or a grid.</li>
<li><b>Delegate</b> - dictates how the data should appear in the view. The delegate takes each data in the model and encapsulates it. The data is accessible through the delegate.</li>
</ul>
<p>To visualize data, bind the view's <code>model</code> property to a model and the <code>delegate</code> property to a component or another compatible type.</p>
<a name="displaying-data-with-views"></a>
<h2 id="displaying-data-with-views">Displaying Data with Views</h2>
<p>Views are containers for collections of items. They are feature-rich and can be customizable to meet style or behavior requirements.</p>
<p>A set of standard views are provided in the basic set of Qt Quick graphical types:</p>
<ul>
<li><a href="qml-qtquick-listview.html">ListView</a> - arranges items in a horizontal or vertical list</li>
<li><a href="qml-qtquick-gridview.html">GridView</a> - arranges items in a grid within the available space</li>
<li><a href="qml-qtquick-pathview.html">PathView</a> - arranges items on a path</li>
</ul>
<p>These types have properties and behaviors exclusive to each type. Visit their respective documentation for more information.</p>
<a name="decorating-views"></a>
<h3 >Decorating Views</h3>
<p>Views allow visual customization through <i>decoration</i> properties such as the <code>header</code>, <code>footer</code>, and <code>section</code> properties. By binding an object, usually another visual object, to these properties, the views are decoratable. A footer may include a <a href="qml-qtquick-rectangle.html">Rectangle</a> type showcasing borders or a header that displays a logo on top of the list.</p>
<p>Suppose that a specific club wants to decorate its members list with its brand colors. A member list is in a <code>model</code> and the <code>delegate</code> will display the model's content.</p>
<pre class="qml"><span class="type">ListModel</span> {
<span class="name">id</span>: <span class="name">nameModel</span>
<span class="type">ListElement</span> { <span class="name">name</span>: <span class="string">"Alice"</span> }
<span class="type">ListElement</span> { <span class="name">name</span>: <span class="string">"Bob"</span> }
<span class="type">ListElement</span> { <span class="name">name</span>: <span class="string">"Jane"</span> }
<span class="type">ListElement</span> { <span class="name">name</span>: <span class="string">"Harry"</span> }
<span class="type">ListElement</span> { <span class="name">name</span>: <span class="string">"Wendy"</span> }
}
<span class="type">Component</span> {
<span class="name">id</span>: <span class="name">nameDelegate</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> {
<span class="name">text</span>: <span class="name">name</span>;
<span class="name">font</span>.pixelSize: <span class="number">24</span>
}
}</pre>
<p>The club may decorate the members list by binding visual objects to the <code>header</code> and <code>footer</code> properties. The visual object may be defined inline, in another file, or in a Component type.</p>
<pre class="qml"><span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">clip</span>: <span class="number">true</span>
<span class="name">model</span>: <span class="name">nameModel</span>
<span class="name">delegate</span>: <span class="name">nameDelegate</span>
<span class="name">header</span>: <span class="name">bannercomponent</span>
<span class="name">footer</span>: <span class="name">Rectangle</span> {
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span>; <span class="name">height</span>: <span class="number">30</span>;
<span class="name">gradient</span>: <span class="name">clubcolors</span>
}
<span class="name">highlight</span>: <span class="name">Rectangle</span> {
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span>
<span class="name">color</span>: <span class="string">"lightgray"</span>
}
}
<span class="type">Component</span> { <span class="comment">//instantiated when header is processed</span>
<span class="name">id</span>: <span class="name">bannercomponent</span>
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">id</span>: <span class="name">banner</span>
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span>; <span class="name">height</span>: <span class="number">50</span>
<span class="name">gradient</span>: <span class="name">clubcolors</span>
<span class="type">border</span> {<span class="name">color</span>: <span class="string">"#9EDDF2"</span>; <span class="name">width</span>: <span class="number">2</span>}
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> {
<span class="name">anchors</span>.centerIn: <span class="name">parent</span>
<span class="name">text</span>: <span class="string">"Club Members"</span>
<span class="name">font</span>.pixelSize: <span class="number">32</span>
}
}
}
<span class="type"><a href="qml-qtquick-gradient.html">Gradient</a></span> {
<span class="name">id</span>: <span class="name">clubcolors</span>
<span class="type"><a href="qml-qtquick-gradientstop.html">GradientStop</a></span> { <span class="name">position</span>: <span class="number">0.0</span>; <span class="name">color</span>: <span class="string">"#8EE2FE"</span>}
<span class="type"><a href="qml-qtquick-gradientstop.html">GradientStop</a></span> { <span class="name">position</span>: <span class="number">0.66</span>; <span class="name">color</span>: <span class="string">"#7ED2EE"</span>}
}</pre>
<p class="centerAlign"><img src="images/listview-decorations.png" alt="" /></p><a name="mouse-and-touch-handling"></a>
<h3 >Mouse and Touch Handling</h3>
<p>The views handle dragging and flicking of their content, however they do not handle touch interaction with the individual delegates. In order for the delegates to react to touch input, e.g. to set the <code>currentIndex</code>, a <a href="qml-qtquick-mousearea.html">MouseArea</a> with the appropriate touch handling logic must be provided by the delegate.</p>
<p>Note that if <code>highlightRangeMode</code> is set to <code>StrictlyEnforceRange</code> the currentIndex will be affected by dragging/flicking the view, since the view will always ensure that the <code>currentIndex</code> is within the highlight range specified.</p>
<a name="listview-sections"></a>
<h3 >ListView Sections</h3>
<p><a href="qml-qtquick-listview.html">ListView</a> contents may be grouped into <i>sections</i>, where related list items are labeled according to their sections. Further, the sections may be decorated with <a href="qtquick-modelviewsdata-modelview.html#qml-view-delegate">delegates</a>.</p>
<p>A list may contain a list indicating people's names and the team on which team the person belongs.</p>
<pre class="qml"><span class="type">ListModel</span> {
<span class="name">id</span>: <span class="name">nameModel</span>
<span class="type">ListElement</span> { <span class="name">name</span>: <span class="string">"Alice"</span>; <span class="name">team</span>: <span class="string">"Crypto"</span> }
<span class="type">ListElement</span> { <span class="name">name</span>: <span class="string">"Bob"</span>; <span class="name">team</span>: <span class="string">"Crypto"</span> }
<span class="type">ListElement</span> { <span class="name">name</span>: <span class="string">"Jane"</span>; <span class="name">team</span>: <span class="string">"QA"</span> }
<span class="type">ListElement</span> { <span class="name">name</span>: <span class="string">"Victor"</span>; <span class="name">team</span>: <span class="string">"QA"</span> }
<span class="type">ListElement</span> { <span class="name">name</span>: <span class="string">"Wendy"</span>; <span class="name">team</span>: <span class="string">"Graphics"</span> }
}
<span class="type">Component</span> {
<span class="name">id</span>: <span class="name">nameDelegate</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> {
<span class="name">text</span>: <span class="name">name</span>;
<span class="name">font</span>.pixelSize: <span class="number">24</span>
<span class="name">anchors</span>.left: <span class="name">parent</span>.<span class="name">left</span>
<span class="name">anchors</span>.leftMargin: <span class="number">2</span>
}
}</pre>
<p>The <a href="qml-qtquick-listview.html">ListView</a> type has the <code>section</code> attached property that can combine adjacent and related types into a section. The <code>section.property</code> determines which list type property to use as sections. The <code>section.criteria</code> can dictate how the section names are displayed and the <code>section.delegate</code> is similar to the views' <a href="qtquick-modelviewsdata-modelview.html#qml-view-delegate">delegate</a> property.</p>
<pre class="qml"><span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">model</span>: <span class="name">nameModel</span>
<span class="name">delegate</span>: <span class="name">nameDelegate</span>
<span class="name">focus</span>: <span class="number">true</span>
<span class="name">highlight</span>: <span class="name">Rectangle</span> {
<span class="name">color</span>: <span class="string">"lightblue"</span>
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span>
}
<span class="type">section</span> {
<span class="name">property</span>: <span class="string">"team"</span>
<span class="name">criteria</span>: <span class="name">ViewSection</span>.<span class="name">FullString</span>
<span class="name">delegate</span>: <span class="name">Rectangle</span> {
<span class="name">color</span>: <span class="string">"#b0dfb0"</span>
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span>
<span class="name">height</span>: <span class="name">childrenRect</span>.<span class="name">height</span> <span class="operator">+</span> <span class="number">4</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> { <span class="name">anchors</span>.horizontalCenter: <span class="name">parent</span>.<span class="name">horizontalCenter</span>
<span class="name">font</span>.pixelSize: <span class="number">16</span>
<span class="name">font</span>.bold: <span class="number">true</span>
<span class="name">text</span>: <span class="name">section</span>
}
}
}
}</pre>
<p class="centerAlign"><img src="images/listview-section.png" alt="" /></p><a name="view-delegates"></a>
<h2 id="view-delegates">View Delegates</h2>
<p>Views need a <i>delegate</i> to visually represent an item in a list. A view will visualize each item list according to the template defined by the delegate. Items in a model are accessible through the <code>index</code> property as well as the item's properties.</p>
<pre class="qml"><span class="type">Component</span> {
<span class="name">id</span>: <span class="name">petdelegate</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> {
<span class="name">id</span>: <span class="name">label</span>
<span class="name">font</span>.pixelSize: <span class="number">24</span>
<span class="name">text</span>: <span class="keyword">if</span> (<span class="name">index</span> <span class="operator">==</span> <span class="number">0</span>)
<span class="name">label</span>.<span class="name">text</span> <span class="operator">=</span> <span class="name">type</span> <span class="operator">+</span> <span class="string">" (default)"</span>
<span class="keyword">else</span>
<span class="name">text</span>: <span class="name">type</span>
}
}</pre>
<p class="centerAlign"><img src="images/listview-setup.png" alt="" /></p><a name="accessing-views-and-models-from-delegates"></a>
<h3 >Accessing Views and Models from Delegates</h3>
<p>The list view to which the delegate is bound is accessible from the delegate through the <code>ListView.view</code> property. Likewise, the <a href="qml-qtquick-gridview.html">GridView</a> <code>GridView.view</code> is available to delegates. The corresponding model and its properties, therefore, are available through <code>ListView.view.model</code>. In addition, any defined signals or methods in the model are also accessible.</p>
<p>This mechanism is useful when you want to use the same delegate for a number of views, for example, but you want decorations or other features to be different for each view, and you would like these different settings to be properties of each of the views. Similarly, it might be of interest to access or show some properties of the model.</p>
<p>In the following example, the delegate shows the property <i>language</i> of the model, and the color of one of the fields depends on the property <i>fruit_color</i> of the view.</p>
<pre class="qml"><span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">200</span>
<span class="type">ListModel</span> {
<span class="name">id</span>: <span class="name">fruitModel</span>
property <span class="type">string</span> <span class="name">language</span>: <span class="string">"en"</span>
<span class="type">ListElement</span> {
<span class="name">name</span>: <span class="string">"Apple"</span>
<span class="name">cost</span>: <span class="number">2.45</span>
}
<span class="type">ListElement</span> {
<span class="name">name</span>: <span class="string">"Orange"</span>
<span class="name">cost</span>: <span class="number">3.25</span>
}
<span class="type">ListElement</span> {
<span class="name">name</span>: <span class="string">"Banana"</span>
<span class="name">cost</span>: <span class="number">1.95</span>
}
}
<span class="type">Component</span> {
<span class="name">id</span>: <span class="name">fruitDelegate</span>
<span class="type"><a href="qml-qtquick-row.html">Row</a></span> {
<span class="name">id</span>: <span class="name">fruit</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> { <span class="name">text</span>: <span class="string">" Fruit: "</span> <span class="operator">+</span> <span class="name">name</span>; <span class="name">color</span>: <span class="name">fruit</span>.<span class="name">ListView</span>.<span class="name">view</span>.<span class="name">fruit_color</span> }
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> { <span class="name">text</span>: <span class="string">" Cost: $"</span> <span class="operator">+</span> <span class="name">cost</span> }
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> { <span class="name">text</span>: <span class="string">" Language: "</span> <span class="operator">+</span> <span class="name">fruit</span>.<span class="name">ListView</span>.<span class="name">view</span>.<span class="name">model</span>.<span class="name">language</span> }
}
}
<span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
property <span class="type">color</span> <span class="name">fruit_color</span>: <span class="string">"green"</span>
<span class="name">model</span>: <span class="name">fruitModel</span>
<span class="name">delegate</span>: <span class="name">fruitDelegate</span>
<span class="name">anchors</span>.fill: <span class="name">parent</span>
}
}</pre>
<a name="models"></a>
<h2 id="models">Models</h2>
<p>Data is provided to the delegate via named data roles which the delegate may bind to. Here is a <a href="qtquick-modelviewsdata-modelview.html#listmodel">ListModel</a> with two roles, <i>type</i> and <i>age</i>, and a <a href="qml-qtquick-listview.html">ListView</a> with a delegate that binds to these roles to display their values:</p>
<pre class="qml">import QtQuick 2.0
<span class="type"><a href="qml-qtquick-item.html">Item</a></span> {
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">250</span>
<span class="type">ListModel</span> {
<span class="name">id</span>: <span class="name">myModel</span>
<span class="type">ListElement</span> { <span class="name">type</span>: <span class="string">"Dog"</span>; <span class="name">age</span>: <span class="number">8</span> }
<span class="type">ListElement</span> { <span class="name">type</span>: <span class="string">"Cat"</span>; <span class="name">age</span>: <span class="number">5</span> }
}
<span class="type">Component</span> {
<span class="name">id</span>: <span class="name">myDelegate</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> { <span class="name">text</span>: <span class="name">type</span> <span class="operator">+</span> <span class="string">", "</span> <span class="operator">+</span> <span class="name">age</span> }
}
<span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">model</span>: <span class="name">myModel</span>
<span class="name">delegate</span>: <span class="name">myDelegate</span>
}
}</pre>
<p>If there is a naming clash between the model's properties and the delegate's properties, the roles can be accessed with the qualified <i>model</i> name instead. For example, if a <a href="qml-qtquick-text.html">Text</a> type had <i>type</i> or <i>age</i> properties, the text in the above example would display those property values instead of the <i>type</i> and <i>age</i> values from the model item. In this case, the properties could have been referenced as <code>model.type</code> and <code>model.age</code> instead to ensure the delegate displays the property values from the model item.</p>
<p>A special <i>index</i> role containing the index of the item in the model is also available to the delegate. Note this index is set to -1 if the item is removed from the model. If you bind to the index role, be sure that the logic accounts for the possibility of index being -1, i.e. that the item is no longer valid. (Usually the item will shortly be destroyed, but it is possible to delay delegate destruction in some views via a <code>delayRemove</code> attached property.)</p>
<p>Models that do not have named roles (such as the <a href="qtquick-modelviewsdata-modelview.html#listmodel">ListModel</a> shown below) will have the data provided via the <i>modelData</i> role. The <i>modelData</i> role is also provided for models that have only one role. In this case the <i>modelData</i> role contains the same data as the named role.</p>
<p>QML provides several types of data models among the built-in set of QML types. In addition, models can be created with Qt C++ and then made available to QQmlEngine for use by QML components. For information about creating these models, visit the <a href="qtquick-modelviewsdata-cppmodels.html">Using C++ Models with Qt Quick Views</a> and creating QML types articles.</p>
<p>Positioning of items from a model can be achieved using a <a href="qml-qtquick-repeater.html">Repeater</a>.</p>
<a name="listmodel"></a>
<h3 >ListModel</h3>
<p><a href="qtquick-modelviewsdata-modelview.html#listmodel">ListModel</a> is a simple hierarchy of types specified in QML. The available roles are specified by the ListElement properties.</p>
<pre class="qml"><span class="type">ListModel</span> {
<span class="name">id</span>: <span class="name">fruitModel</span>
<span class="type">ListElement</span> {
<span class="name">name</span>: <span class="string">"Apple"</span>
<span class="name">cost</span>: <span class="number">2.45</span>
}
<span class="type">ListElement</span> {
<span class="name">name</span>: <span class="string">"Orange"</span>
<span class="name">cost</span>: <span class="number">3.25</span>
}
<span class="type">ListElement</span> {
<span class="name">name</span>: <span class="string">"Banana"</span>
<span class="name">cost</span>: <span class="number">1.95</span>
}
}</pre>
<p>The above model has two roles, <i>name</i> and <i>cost</i>. These can be bound to by a <a href="qml-qtquick-listview.html">ListView</a> delegate, for example:</p>
<pre class="qml"><span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">model</span>: <span class="name">fruitModel</span>
<span class="name">delegate</span>: <span class="name">Row</span> {
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> { <span class="name">text</span>: <span class="string">"Fruit: "</span> <span class="operator">+</span> <span class="name">name</span> }
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> { <span class="name">text</span>: <span class="string">"Cost: $"</span> <span class="operator">+</span> <span class="name">cost</span> }
}
}</pre>
<p><a href="qtquick-modelviewsdata-modelview.html#listmodel">ListModel</a> provides methods to manipulate the <a href="qtquick-modelviewsdata-modelview.html#listmodel">ListModel</a> directly via JavaScript. In this case, the first item inserted determines the roles available to any views that are using the model. For example, if an empty <a href="qtquick-modelviewsdata-modelview.html#listmodel">ListModel</a> is created and populated via JavaScript, the roles provided by the first insertion are the only roles that will be shown in the view:</p>
<pre class="qml"><span class="type">ListModel</span> { <span class="name">id</span>: <span class="name">fruitModel</span> }
...
<span class="type"><a href="qml-qtquick-mousearea.html">MouseArea</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">onClicked</span>: <span class="name">fruitModel</span>.<span class="name">append</span>({"cost": <span class="number">5.95</span>, "name":<span class="string">"Pizza"</span>})
}</pre>
<p>When the <a href="qml-qtquick-mousearea.html">MouseArea</a> is clicked, <code>fruitModel</code> will have two roles, <i>cost</i> and <i>name</i>. Even if subsequent roles are added, only the first two will be handled by views using the model. To reset the roles available in the model, call ListModel::clear().</p>
<a name="xmllistmodel"></a>
<h3 >XmlListModel</h3>
<p><a href="qtquick-modelviewsdata-modelview.html#xmllistmodel">XmlListModel</a> allows construction of a model from an XML data source. The roles are specified via the <a href="qml-qtquick-xmllistmodel-xmlrole.html">XmlRole</a> type. The type needs to be imported.</p>
<pre class="cpp">import <span class="type"><a href="qtquick-module.html">QtQuick</a></span><span class="operator">.</span>XmlListModel <span class="number">2.0</span></pre>
<p>The following model has three roles, <i>title</i>, <i>link</i> and <i>description</i>:</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">feedModel</span>
<span class="name">source</span>: <span class="string">"http://rss.news.yahoo.com/rss/oceania"</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">"link"</span>; <span class="name">query</span>: <span class="string">"link/string()"</span> }
<span class="type"><a href="qml-qtquick-xmllistmodel-xmlrole.html">XmlRole</a></span> { <span class="name">name</span>: <span class="string">"description"</span>; <span class="name">query</span>: <span class="string">"description/string()"</span> }
}</pre>
<p>The <a href="qtquick-demos-rssnews-example.html">RSS News demo</a> shows how <a href="qtquick-modelviewsdata-modelview.html#xmllistmodel">XmlListModel</a> can be used to display an RSS feed.</p>
<a name="visualitemmodel"></a>
<h3 >VisualItemModel</h3>
<p><a href="qtquick-modelviewsdata-modelview.html#visualitemmodel">VisualItemModel</a> allows QML items to be provided as a model.</p>
<p>This model contains both the data and delegate; the child items of a <a href="qtquick-modelviewsdata-modelview.html#visualitemmodel">VisualItemModel</a> provide the contents of the delegate. The model does not provide any roles.</p>
<pre class="qml"><span class="type">VisualItemModel</span> {
<span class="name">id</span>: <span class="name">itemModel</span>
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> { <span class="name">height</span>: <span class="number">30</span>; <span class="name">width</span>: <span class="number">80</span>; <span class="name">color</span>: <span class="string">"red"</span> }
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> { <span class="name">height</span>: <span class="number">30</span>; <span class="name">width</span>: <span class="number">80</span>; <span class="name">color</span>: <span class="string">"green"</span> }
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> { <span class="name">height</span>: <span class="number">30</span>; <span class="name">width</span>: <span class="number">80</span>; <span class="name">color</span>: <span class="string">"blue"</span> }
}
<span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">model</span>: <span class="name">itemModel</span>
}</pre>
<p>Note that in the above example there is no delegate required. The items of the model itself provide the visual types that will be positioned by the view.</p>
<a name="integers-as-models"></a>
<h3 >Integers as Models</h3>
<p>An integer can be used as a model that contains a certain number of types. In this case, the model does not have any data roles.</p>
<p>The following example creates a <a href="qml-qtquick-listview.html">ListView</a> with five elements:</p>
<pre class="qml"><span class="type"><a href="qml-qtquick-item.html">Item</a></span> {
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">250</span>
<span class="type">Component</span> {
<span class="name">id</span>: <span class="name">itemDelegate</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> { <span class="name">text</span>: <span class="string">"I am item number: "</span> <span class="operator">+</span> <span class="name">index</span> }
}
<span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">model</span>: <span class="number">5</span>
<span class="name">delegate</span>: <span class="name">itemDelegate</span>
}
}</pre>
<a name="object-instances-as-models"></a>
<h3 >Object Instances as Models</h3>
<p>An object instance can be used to specify a model with a single object type. The properties of the object are provided as roles.</p>
<p>The example below creates a list with one item, showing the color of the <i>myText</i> text. Note the use of the fully qualified <i>model.color</i> property to avoid clashing with <i>color</i> property of the Text type in the delegate.</p>
<pre class="qml"><span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">200</span>; <span class="name">height</span>: <span class="number">250</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> {
<span class="name">id</span>: <span class="name">myText</span>
<span class="name">text</span>: <span class="string">"Hello"</span>
<span class="name">color</span>: <span class="string">"#dd44ee"</span>
}
<span class="type">Component</span> {
<span class="name">id</span>: <span class="name">myDelegate</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> { <span class="name">text</span>: <span class="name">model</span>.<span class="name">color</span> }
}
<span class="type"><a href="qml-qtquick-listview.html">ListView</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">anchors</span>.topMargin: <span class="number">30</span>
<span class="name">model</span>: <span class="name">myText</span>
<span class="name">delegate</span>: <span class="name">myDelegate</span>
}
}</pre>
<a name="c-data-models"></a>
<h3 >C++ Data Models</h3>
<p>Models can be defined in C++ and then made available to QML. This mechanism is useful for exposing existing C++ data models or otherwise complex datasets to QML.</p>
<p>For information, visit the <a href="qtquick-modelviewsdata-cppmodels.html">Using C++ Models with Qt Quick Views</a> article.</p>
<a name="repeaters"></a>
<h2 id="repeaters">Repeaters</h2>
<div class="float-right"><p><img src="images/repeater-index.png" alt="" /></p>
</div><p>Repeaters create items from a template for use with positioners, using data from a model. Combining repeaters and positioners is an easy way to lay out lots of items. A <a href="qml-qtquick-repeater.html">Repeater</a> item is placed inside a positioner, and generates items that the enclosing positioner arranges.</p>
<p>Each Repeater creates a number of items by combining each element of data from a model, specified using the <a href="qml-qtquick-repeater.html#model-prop">model</a> property, with the template item, defined as a child item within the Repeater. The total number of items is determined by the amount of data in the model.</p>
<p>The following example shows a repeater used with a Grid item to arrange a set of Rectangle items. The Repeater item creates a series of 24 rectangles for the Grid item to position in a 5 by 5 arrangement.</p>
<pre class="qml">import QtQuick 2.0
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> {
<span class="name">width</span>: <span class="number">400</span>; <span class="name">height</span>: <span class="number">400</span>; <span class="name">color</span>: <span class="string">"black"</span>
<span class="type"><a href="qml-qtquick-grid.html">Grid</a></span> {
<span class="name">x</span>: <span class="number">5</span>; <span class="name">y</span>: <span class="number">5</span>
<span class="name">rows</span>: <span class="number">5</span>; <span class="name">columns</span>: <span class="number">5</span>; <span class="name">spacing</span>: <span class="number">10</span>
<span class="type"><a href="qml-qtquick-repeater.html">Repeater</a></span> { <span class="name">model</span>: <span class="number">24</span>
<span class="type"><a href="qml-qtquick-rectangle.html">Rectangle</a></span> { <span class="name">width</span>: <span class="number">70</span>; <span class="name">height</span>: <span class="number">70</span>
<span class="name">color</span>: <span class="string">"lightgreen"</span>
<span class="type"><a href="qml-qtquick-text.html">Text</a></span> { <span class="name">text</span>: <span class="name">index</span>
<span class="name">font</span>.pointSize: <span class="number">30</span>
<span class="name">anchors</span>.centerIn: <span class="name">parent</span> } }
}
}
}</pre>
<p>The number of items created by a Repeater is held by its <a href="qml-qtquick-repeater.html#count-prop">count</a> property. It is not possible to set this property to determine the number of items to be created. Instead, as in the above example, we use an integer as the model. This is explained in the <a href="qtquick-modelviewsdata-modelview.html#integers-as-models">QML Data Models</a> document.</p>
<p>It is also possible to use a delegate as the template for the items created by a Repeater. This is specified using the <a href="qml-qtquick-repeater.html#delegate-prop">delegate</a> property.</p>
<a name="using-transitions"></a>
<h2 id="using-transitions">Using Transitions</h2>
<p>Transitions can be used to animate items that are added to, moved within, or removed from a positioner.</p>
<p>Transitions for adding items apply to items that are created as part of a positioner, as well as those that are reparented to become children of a positioner. Transitions for removing items apply to items within a positioner that are deleted, as well as those that are removed from a positioner and given new parents in a document.</p>
<p>Additionally, changing the opacity of items to zero will cause them to disappear using the remove transition, and making the opacity non-zero will cause them to appear using the add transition.</p>
</div>
<!-- @@@qtquick-modelviewsdata-modelview.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 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>
|