File: qml-views.html

package info (click to toggle)
qt4-x11 4%3A4.8.2%2Bdfsg-11
  • links: PTS, VCS
  • area: main
  • in suites: wheezy
  • size: 701,696 kB
  • sloc: cpp: 2,686,179; ansic: 375,485; python: 25,859; sh: 19,349; xml: 17,091; perl: 14,765; yacc: 5,383; asm: 5,038; makefile: 1,259; lex: 555; ruby: 526; objc: 347; cs: 112; pascal: 112; php: 54; sed: 34
file content (219 lines) | stat: -rw-r--r-- 17,134 bytes parent folder | download 
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
 
<?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" />
<!-- qmlviews.qdoc -->
  <title>Qt 4.8: Presenting Data with Views</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>Presenting Data with Views</li>
    </ul>
  </div>
</div>
<div class="content mainContent">
  <link rel="prev" href="qdeclarativemodels.html" />
  <link rel="next" href="qml-extending.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="qdeclarativemodels.html">Structuring Data with Models</a>
<a class="nextPage" href="qml-extending.html">Extending QML Functionalities using C++</a>
</p><p/>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#models">Models</a></li>
<li class="level1"><a href="#view-delegates">View Delegates</a></li>
<li class="level1"><a href="#decorating-views">Decorating Views</a></li>
<li class="level1"><a href="#listview-sections">ListView Sections</a></li>
</ul>
</div>
<h1 class="title">Presenting Data with Views</h1>
<span class="subtitle"></span>
<!-- $$$qml-views.html-description -->
<div class="descr"> <a name="details"></a>
<p>Views are containers for collections of items. They are feature-rich and can be customizable to meet style or behavior requirements.</p>
<a name="qml-view-elements"></a><p>A set of standard views are provided in the basic set of Qt Quick graphical elements:</p>
<ul>
<li><a href="qml-listview.html">ListView</a> arranges items in a horizontal or vertical list</li>
<li><a href="qml-gridview.html">GridView</a> arranges items in a grid within the available space</li>
<li><a href="qml-pathview.html">PathView</a> arranges items on a path</li>
<li><a href="qml-webview.html">WebView</a> - available from the <a href="qmlwebkit.html">QtWebKit QML Module</a>.</li>
</ul>
<p>Unlike other views, <a href="qml-webview.html">WebView</a> is not a fully-featured view item, and needs to be combined with a <a href="qml-flickable.html">Flickable</a> item to create a view that performs like a Web browser.</p>
<p>These elements have properties and behaviors exclusive to each element. Visit their respective documentation for more information.</p>
<a name="models"></a>
<h2>Models</h2>
<p>Views display <a href="qdeclarativemodels.html">models</a> onto the screen. A model could be a simple list of <a href="qdeclarativemodels.html#an-integer">integer</a> or a <a href="qdeclarativemodels.html#qml-c-models">C++ model</a>.</p>
<p>To assign a model to a view, bind the view's <tt>model</tt> property to a model.</p>
<pre class="qml"> <span class="type"><a href="qml-listmodel.html">ListModel</a></span> {
     <span class="name">id</span>: <span class="name">petlist</span>
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">type</span>: <span class="string">&quot;Cat&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">type</span>: <span class="string">&quot;Dog&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">type</span>: <span class="string">&quot;Mouse&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">type</span>: <span class="string">&quot;Rabbit&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">type</span>: <span class="string">&quot;Horse&quot;</span> }
 }
 <span class="type"><a href="qml-listview.html">ListView</a></span> {
     <span class="name">id</span>: <span class="name">view</span>
     <span class="name">anchors</span>.fill: <span class="name">parent</span>

     <span class="name">model</span>: <span class="name">petlist</span>
     <span class="name">delegate</span>: <span class="name">petdelegate</span>
 }</pre>
<p>For more information, consult the <a href="qdeclarativemodels.html">QML Data Models</a> article.</p>
<a name="qml-view-delegate"></a><a name="view-delegates"></a>
<h2>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 <tt>index</tt> property as well as the item's properties.</p>
<pre class="qml"> <span class="type"><a href="qml-component.html">Component</a></span> {
     <span class="name">id</span>: <span class="name">petdelegate</span>
     <span class="type"><a href="qml-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">&quot; (default)&quot;</span>
         else
             <span class="name">text</span>: <span class="name">type</span>
     }
 }</pre>
<p class="centerAlign"><img src="images/listview-setup.png" alt="" /></p><a name="decorating-views"></a>
<h2>Decorating Views</h2>
<p>Views allow visual customization through <i>decoration</i> properties such as the <tt>header</tt>, <tt>footer</tt>, and <tt>section</tt> properties. By binding an object, usually another visual object, to these properties, the views are decoratable. A footer may include a <a href="qml-rectangle.html">Rectangle</a> element 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 <tt>model</tt> and the <tt>delegate</tt> will display the model's content.</p>
<pre class="qml"> <span class="type"><a href="qml-listmodel.html">ListModel</a></span> {
     <span class="name">id</span>: <span class="name">nameModel</span>
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">name</span>: <span class="string">&quot;Alice&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">name</span>: <span class="string">&quot;Bob&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">name</span>: <span class="string">&quot;Jane&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">name</span>: <span class="string">&quot;Harry&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">name</span>: <span class="string">&quot;Wendy&quot;</span> }
 }
 <span class="type"><a href="qml-component.html">Component</a></span> {
     <span class="name">id</span>: <span class="name">nameDelegate</span>
     <span class="type"><a href="qml-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 <tt>header</tt> and <tt>footer</tt> properties. The visual object may be defined inline, in another file, or in a <a href="qml-component.html">Component</a> element.</p>
<pre class="qml"> <span class="type"><a href="qml-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">&quot;lightgray&quot;</span>
     }
 }

 <span class="type"><a href="qml-component.html">Component</a></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-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">&quot;#9EDDF2&quot;</span>; <span class="name">width</span>: <span class="number">2</span>}
         <span class="type"><a href="qml-text.html">Text</a></span> {
             <span class="name">anchors</span>.centerIn: <span class="name">parent</span>
             <span class="name">text</span>: <span class="string">&quot;Club Members&quot;</span>
             <span class="name">font</span>.pixelSize: <span class="number">32</span>
         }
     }
 }
 <span class="type"><a href="qml-gradient.html">Gradient</a></span> {
     <span class="name">id</span>: <span class="name">clubcolors</span>
     <span class="type"><a href="qml-gradientstop.html">GradientStop</a></span> { <span class="name">position</span>: <span class="number">0.0</span>; <span class="name">color</span>: <span class="string">&quot;#8EE2FE&quot;</span>}
     <span class="type"><a href="qml-gradientstop.html">GradientStop</a></span> { <span class="name">position</span>: <span class="number">0.66</span>; <span class="name">color</span>: <span class="string">&quot;#7ED2EE&quot;</span>}
 }</pre>
<p class="centerAlign"><img src="images/listview-decorations.png" alt="" /></p><a name="listview-sections"></a>
<h2>ListView Sections</h2>
<p><a href="qml-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="#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"><a href="qml-listmodel.html">ListModel</a></span> {
     <span class="name">id</span>: <span class="name">nameModel</span>
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">name</span>: <span class="string">&quot;Alice&quot;</span>; <span class="name">team</span>: <span class="string">&quot;Crypto&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">name</span>: <span class="string">&quot;Bob&quot;</span>; <span class="name">team</span>: <span class="string">&quot;Crypto&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">name</span>: <span class="string">&quot;Jane&quot;</span>; <span class="name">team</span>: <span class="string">&quot;QA&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">name</span>: <span class="string">&quot;Victor&quot;</span>; <span class="name">team</span>: <span class="string">&quot;QA&quot;</span> }
     <span class="type"><a href="qml-listelement.html">ListElement</a></span> { <span class="name">name</span>: <span class="string">&quot;Wendy&quot;</span>; <span class="name">team</span>: <span class="string">&quot;Graphics&quot;</span> }
 }
 <span class="type"><a href="qml-component.html">Component</a></span> {
     <span class="name">id</span>: <span class="name">nameDelegate</span>
     <span class="type"><a href="qml-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-listview.html">ListView</a> element has the <tt>section</tt> <a href="propertybinding.html#attached-properties">attached property</a> that can combine adjacent and related elements into a section. The section's <tt>property</tt> property is for selecting which list element property to use as sections. The <tt>criteria</tt> can dictate how the section names are displayed and the <tt>delegate</tt> is similar to the views' <a href="#qml-view-delegate">delegate</a> property.</p>
<pre class="qml"> <span class="type"><a href="qml-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">&quot;lightblue&quot;</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">&quot;team&quot;</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">&quot;#b0dfb0&quot;</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-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></div>
<!-- @@@qml-views.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="qdeclarativemodels.html">Structuring Data with Models</a>
<a class="nextPage" href="qml-extending.html">Extending QML Functionalities using C++</a>
</p>
  <div class="ft">
    <span></span>
  </div>
</div> 
<div class="footer">
    <p>
      <acronym title="Copyright">&copy;</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>