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
|
/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** 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.
**
****************************************************************************/
/*!
\page quick-data-models.html
\previouspage quick-text.html
\nextpage quick-buttons.html
\title Lists and Other Data Models
Applications typically need to handle and display data that is organized
into list or grid views. Qt Quick uses models, views, and delegates for
this purpose. They modularize the visualization of data in order to give
you control over the different aspects of the data. For example, you 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
developers to dictate how to present or handle the data.
A \e model contains the data and its structure. There are several QML
types for creating different types of models. A \e view is a container
that displays the data in a list or a grid, or along a path. A \e delegate
dictates how the data should appear in the view. The delegate takes each
piece of data in the model and encapsulates it. The data is then accessible
through the delegate.
To visualize data, the view's model property is bound to a model and the
delegate property to a component.
For more information, see \l{Models and Views in Qt Quick}.
\section1 List and Grid Views
A list view organizes items as a list, whereas a grid view organizes them as
a grid. By default, items in list and grid views flow vertically from left
to right. They are laid out from left to right horizontally, and from top to
bottom vertically.
You can change the list view orientation in the \uicontrol Orientation
field and the grid view flow in the \uicontrol Flow field. You can change
the layout direction in the \uicontrol {Layout direction} field. These
properties can be combined to produce a variety of layouts.
\image qtquick-designer-listview-properties.png "List View properties"
For a list view, you can specify space between list items in the
\uicontrol Spacing field. For a grid view, you can specify the width
and height of each cell in the \uicontrol W and \uicontrol H fields.
\image qtquick-designer-gridview-properties.png "Grid View properties"
Select the \uicontrol {Navigation wraps} check box to specify that key
navigation wraps around and moves the selection to the next line or cell
in the other end of the view when it reaches the end of the view.
Both list and grid views are inherently \l {Flickable}{flickable}.
The value of the \uicontrol {Snap mode} field determines how the view
scrolling will settle following a drag or flick. By default, the view
stops anywhere within the visible area. If you select \uicontrol SnapToRow,
the view settles with a row (or column for a grid view top-to-bottom flow)
aligned with the start of the view. If you select \uicontrol SnapOneRow,
the view will settle no more than one row or column away from the first
visible row at the time the mouse button is released. This option is
particularly useful for moving one page at a time.
\section1 Delegate Cache
The value of the \uicontrol Cache field determines whether delegates are
retained outside the visible area of the view.
If this value is greater than zero, the view may keep as many delegates
instantiated as will fit within the cache specified. For example, if in
a vertical view the delegate is 20 pixels high, there are three columns
and the cache is set to 40, then up to six delegates above and below the
visible area may be created or retained. The cached delegates are created
asynchronously, allowing creation to occur across multiple frames and
reducing the likelihood of skipping frames. In order to improve painting
performance delegates outside the visible area are not painted.
The default value of this property is platform dependent, but will usually
be a value greater than zero. Negative values are ignored.
The cache is not a pixel buffer. It only maintains additional instantiated
delegates.
\note Setting the \uicontrol Cache property is not a replacement for
creating efficient delegates. It can improve the smoothness of scrolling
behavior at the expense of additional memory usage. The fewer objects and
bindings in a delegate, the faster a view can be scrolled. It is important
to realize that setting a cache will only postpone issues caused by
slow-loading delegates, it is not a solution to this problem.
\section1 View Highlight
The current item in a list or grid view is higlighted if you set
the value of the \uicontrol Range field to \uicontrol ApplyRange
or \uicontrol StrictlyEnforceRange. When you select to apply the
range, the view attempts to maintain the highlight within the range.
However, the highlight can move outside of the range at the ends of
the view or due to mouse interaction. When you select to enforce the
range, the highlight never moves outside of the range. The current
item changes if a keyboard or mouse action would cause the highlight
to move outside of the range.
The values of the \uicontrol {Preferred begin} and \uicontrol {Preferred end}
fields affect the position of the current item when the view is scrolled.
For example, if the currently selected item should stay in the middle of the
view when it is scrolled, set the begin and end values to the top and bottom
coordinates of where the middle item would be. If the current item is
changed programmatically, the view will automatically scroll so that the
current item is in the middle of the view. The begin value must be less than
the end value.
Select the \uicontrol {Follows current item} check box to enable the view to
manage the highlight. The highlight is moved smoothly to follow the current
item. Otherwise, the highlight is not moved by the view, and any movement
must be implemented by the highlight.
The values of the \uicontrol {Move duration}, \uicontrol {Move velocity}
\uicontrol {Resize duration}, and \uicontrol {Resize velocity} fields
control the speed of the move and resize animations for the highlight.
\section1 Editing List Models
When you add a \l{GridView}{Grid View}, \l{ListView}{List View}, or
\l{PathView}{Path View}, the ListModel and the delegate component that
creates an instance for each item in the model are added automatically.
For grid and list views, you can edit the list model in \QC.
\image qtquick-designer-listview-preview.png "Preview of a list view"
To edit list models:
\list 1
\li Drag and drop a \uicontrol {Grid View} or \uicontrol {List View}
from \uicontrol Library to \uicontrol Navigator or
\uicontrol {Form Editor}.
\li Right-click the view in \uicontrol Navigator, and select
\uicontrol {Edit List Model} in the context-menu to open
the list model editor:
\image qtquick-designer-edit-list-model.png "List view in model editor"
\li Double-click the column headings and cells to change their values.
\li Use the toolbar buttons to add, remove, or move rows and columns.
In a list, each column represents a property and each row adds a
list item.
\endlist
You can replace the default model and delegate with other,
more complex models and delegates in \uicontrol {Text Editor}.
\l{ItemDelegate}{Item Delegate} and \l{SwipeDelegate}{Swipe Delegate}
types are also available in \uicontrol Library.
\include qtquick-pathview-editor.qdocinc pathview
\if defined(qtdesignstudio)
\include qtquick-pathview-editor.qdocinc svgpath
\endif
\section1 Summary of Model Components
The following table lists the QML types that you can use to add data models
to UIs. The \e Location column contains the tab name where you can find the
type in \uicontrol Library. The \e MCU column indicates which types are
supported on MCUs.
\table
\header
\li Icon
\li Name
\li Location
\li MCU
\li Purpose
\row
\li \inlineimage gridview-icon16.png
\li \l{GridView}{Grid View}
\li Qt Quick - Views
\li
\li A grid vizualization of a model.
\row
\li \inlineimage icons/itemdelegate-icon16.png
\li \l{ItemDelegate}{Item Delegate}
\li Qt Quick - Controls 2
\li
\li A standard view item that can be used as a delegate in various
views and controls, such as \l ListView and \l ComboBox.
\row
\li \inlineimage listview-icon16.png
\li \l{ListView}{List View}
\li Qt Quick - Views
\li \inlineimage ok
\li A list vizualization of a model.
\row
\li \inlineimage pathview-icon16.png
\li \l{Path View}
\li Qt Quick - Views
\li
\li Vizualizes the contents of a model along a path.
\row
\li \inlineimage icons/scrollview-icon16.png
\li \l [QtQuickControls] {ScrollView}{Scroll View}
\li Qt Quick - Controls 2
\li
\li Provides scrolling for user-defined content. It can be used instead
of a \l Flickable item.
\row
\li \inlineimage icons/stackview-icon16.png
\li \l [QtQuickControls] {StackView}{Stack View}
\li Qt Quick - Controls 2
\li
\li A stack-based navigation model.
\if defined(qtdesignstudio)
\row
\li \inlineimage icons/item-svg-16px.png
\li SvgPath
\li Studio Components
\li
\li An SVG path data string that is used to draw a path as a line.
\endif
\row
\li \inlineimage icons/itemdelegate-icon16.png
\li \l{SwipeDelegate}{Swipe Delegate}
\li Qt Quick - Controls 2
\li
\li A view item that can be swiped left or right to expose more
options or information. It is used as a delegate in views such
as \l ListView.
\row
\li \inlineimage icons/swipeview-icon16.png
\li \l[QtQuickControls] {SwipeView}{Swipe View}
\li Qt Quick - Controls 2
\li \inlineimage ok
\li Enables users to navigate pages by swiping sideways.
\endtable
*/
|
