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
|
/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtquick-modelviewsdata-modelview.html
\title Models and Views in Qt Quick
\brief how to display and form data in Qt Quick
Simply put, applications need to form data and display the data. Qt Quick has the
notion of \e models, \e views, and \e delegates 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.
\image modelview-overview.png
\list
\li \b Model - contains the data and its structure. There are several QML
types for creating models.
\li \b View - a container that displays the data. The view might
display the data in a list or a grid.
\li \b Delegate - 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.
\endlist
To visualize data, bind the view's \c model property to a model and the
\c delegate property to a component or another compatible type.
\section1 Displaying Data with Views
Views are containers for collections of items. They are feature-rich and can be
customizable to meet style or behavior requirements.
\target qtquick-views
A set of standard views are provided in the basic set of Qt Quick
graphical types:
\list
\li \l{ListView} - arranges items in a horizontal or vertical list
\li \l{GridView} - arranges items in a grid within the available space
\li \l{PathView} - arranges items on a path
\endlist
These types have properties and behaviors exclusive to each type.
Visit their respective documentation for more information.
\section2 Decorating Views
Views allow visual customization through \e decoration properties such as
the \c header, \c footer, and \c section properties. By binding an object,
usually another visual object, to these properties, the views are
decoratable. A footer may include a \l Rectangle type showcasing borders
or a header that displays a logo on top of the list.
Suppose that a specific club wants to decorate its members list with its brand
colors. A member list is in a \c model and the \c delegate will display the
model's content.
\snippet qml/listview-decorations.qml model
\snippet qml/listview-decorations.qml delegate
The club may decorate the members list by binding visual objects to the \c
header and \c footer properties. The visual object may be defined inline, in
another file, or in a \l {Component} type.
\snippet qml/listview-decorations.qml decorations
\image listview-decorations.png
\section2 Mouse and Touch Handling
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 \c currentIndex, a MouseArea
with the appropriate touch handling logic must be provided by the delegate.
Note that if \c highlightRangeMode is set to \c StrictlyEnforceRange the
currentIndex will be affected by dragging/flicking the view, since the view
will always ensure that the \c currentIndex is within the highlight range
specified.
\section2 ListView Sections
\l {ListView} contents may be grouped into \e sections, where related list
items are labeled according to their sections. Further, the sections may be
decorated with \l{qml-view-delegate}{delegates}.
A list may contain a list indicating people's names and the team on which
team the person belongs.
\snippet qml/listview-sections.qml model
\snippet qml/listview-sections.qml delegate
The ListView type has the \c section
\l{qtqml-syntax-objectattributes.html#Attached-properties-and-attached-signal-handlers}
{attached property} that can combine adjacent and related types into a
section. The \c section.property determines which list
type property to use as sections. The \c section.criteria can dictate how the
section names are displayed and the \c section.delegate is similar to the views'
\l {qml-view-delegate}{delegate} property.
\snippet qml/listview-sections.qml section
\image listview-section.png
\target qml-view-delegate
\section1 View Delegates
Views need a \e delegate 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 \c index property as well as the
item's properties.
\snippet qml/listview.qml delegate
\image listview-setup.png
\section2 Accessing Views and Models from Delegates
The list view to which the delegate is bound is accessible from the delegate
through the \c{ListView.view} property. Likewise, the GridView
\c{GridView.view} is available to delegates. The corresponding model and its
properties, therefore, are available through \c{ListView.view.model}. In
addition, any defined signals or methods in the model are also accessible.
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.
In the following example, the delegate shows the property \e{language} of
the model, and the color of one of the fields depends on the property
\e{fruit_color} of the view.
\snippet qml/models/views-models-delegates.qml rectangle
\target qml-data-models
\section1 Models
Data is provided to the delegate via named data roles which the delegate may
bind to. Here is a ListModel with two roles, \e type and \e age, and a
ListView with a delegate that binds to these roles to display their values:
\snippet qml/qml-data-models/listmodel-listview.qml document
If there is a naming clash between the model's properties and the delegate's
properties, the roles can be accessed with the qualified \e model name
instead. For example, if a \l Text type had \e type or \e age properties,
the text in the above example would display those property values instead of
the \e type and \e age values from the model item. In this case, the
properties could have been referenced as \c model.type and \c model.age
instead to ensure the delegate displays the property values from the model
item.
A special \e index 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 \c delayRemove
attached property.)
Models that do not have named roles (such as the ListModel shown
below) will have the data provided via the \e modelData role. The \e
modelData role is also provided for models that have only one role. In this
case the \e modelData role contains the same data as the named role.
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 \l{QQmlEngine} for use by
QML components. For information about creating these models, visit the
\l{Using C++ Models with Qt Quick Views}
and \l{qtqml-typesystem-topic.html#qml-object-types}
{creating QML types} articles.
Positioning of items from a model can be achieved using a \l{Repeater}.
\section2 List Model
ListModel is a simple hierarchy of types specified in QML. The
available roles are specified by the \l ListElement properties.
\snippet qml/qml-data-models/listelements.qml model
The above model has two roles, \e name and \e cost. These can be bound
to by a ListView delegate, for example:
\snippet qml/qml-data-models/listelements.qml view
ListModel provides methods to manipulate the ListModel 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 ListModel is
created and populated via JavaScript, the roles provided by the first
insertion are the only roles that will be shown in the view:
\snippet qml/qml-data-models/dynamic-listmodel.qml model
\dots
\snippet qml/qml-data-models/dynamic-listmodel.qml mouse area
When the MouseArea is clicked, \c fruitModel will have two roles, \e cost and \e name.
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().
\section2 XML Model
XmlListModel allows construction of a model from an XML data source. The roles
are specified via the \l XmlRole type. The type needs to be imported.
\code
import QtQuick.XmlListModel 2.0
\endcode
The following model has three roles, \e title, \e link and \e description:
\qml
XmlListModel {
id: feedModel
source: "http://rss.news.yahoo.com/rss/oceania"
query: "/rss/channel/item"
XmlRole { name: "title"; query: "title/string()" }
XmlRole { name: "link"; query: "link/string()" }
XmlRole { name: "description"; query: "description/string()" }
}
\endqml
The \c query property specifies that the XmlListModel generates a model item
for each \c <item> in the XML document.
The \l{Qt Quick Demo - RSS News}{RSS News demo} shows how XmlListModel can
be used to display an RSS feed.
\section2 Object Model
ObjectModel contains the visual items to be used in a view. When an ObjectModel
is used in a view, the view does not require a delegate because the ObjectModel
already contains the visual delegate (items).
The example below places three colored rectangles in a ListView.
\code
import QtQuick 2.0
import QtQml.Models 2.1
Rectangle {
ObjectModel {
id: itemModel
Rectangle { height: 30; width: 80; color: "red" }
Rectangle { height: 30; width: 80; color: "green" }
Rectangle { height: 30; width: 80; color: "blue" }
}
ListView {
anchors.fill: parent
model: itemModel
}
}
\endcode
\note VisualItemModel can also be used, but it is only provided for compatibility
reasons. VisualItemModel allows a QML item to be provided as a model. This model
contains both the data and delegate; the child items of a VisualItemModel
provide the contents of the delegate. The model does not provide any roles.
\section2 Integers as Models
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.
The following example creates a ListView with five elements:
\qml
Item {
width: 200; height: 250
Component {
id: itemDelegate
Text { text: "I am item number: " + index }
}
ListView {
anchors.fill: parent
model: 5
delegate: itemDelegate
}
}
\endqml
\note The limit on the number of items in an integer model is 100,000,000.
\section2 Object Instances as Models
An object instance can be used to specify a model with a single object
type. The properties of the object are provided as roles.
The example below creates a list with one item, showing the color of the \e
myText text. Note the use of the fully qualified \e model.color property to
avoid clashing with \e color property of the Text type in the delegate.
\qml
Rectangle {
width: 200; height: 250
Text {
id: myText
text: "Hello"
color: "#dd44ee"
}
Component {
id: myDelegate
Text { text: model.color }
}
ListView {
anchors.fill: parent
anchors.topMargin: 30
model: myText
delegate: myDelegate
}
}
\endqml
\target qml-c++-models
\section2 C++ Data Models
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.
For information, visit the
\l{Using C++ Models with Qt Quick Views}
article.
\section1 Repeaters
\div {class="float-right"}
\inlineimage repeater-index.png
\enddiv
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 \l Repeater item is placed inside a positioner, and generates
items that the enclosing positioner arranges.
Each Repeater creates a number of items by combining each element of data
from a model, specified using the \l{Repeater::model}{model} 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.
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.
\snippet qml/repeaters/repeater-grid-index.qml document
The number of items created by a Repeater is held by its \l{Repeater::}{count}
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.
For more details, see the \l{qtquick-modelviewsdata-modelview.html#integers-as-models}{QML Data Models} document.
If the model is a string list, the delegate is also exposed to a read-only
\c modelData property that holds the string. For example:
\table
\row
\li \snippet qml/repeaters/repeater.qml modeldata
\li \image repeater-modeldata.png
\endtable
It is also possible to use a delegate as the template for the items created
by a Repeater. This is specified using the \l{Repeater::}{delegate} property.
\section1 Using Transitions
Transitions can be used to animate items that are added to, moved within,
or removed from a positioner.
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.
\note Changing the opacity of items to zero will not cause them to
disappear from the positioner. They can be removed and re-added by changing
the visible property.
*/
|