1 /****************************************************************************
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:FDL$
10 ** GNU Free Documentation License
11 ** Alternatively, this file may be used under the terms of the GNU Free
12 ** Documentation License version 1.3 as published by the Free Software
13 ** Foundation and appearing in the file included in the packaging of
17 ** Alternatively, this file may be used in accordance with the terms
18 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
31 \contentspage QML Features
32 \previouspage {QML Data Models}{Structuring Data with Models}
33 \nextpage {Extending QML Functionalities using C++}
34 \title Presenting Data with Views
36 Views are containers for collections of items. They are feature-rich and can be
37 customizable to meet style or behavior requirements.
39 \keyword qml-view-elements
40 A set of standard views are provided in the basic set of Qt Quick
44 \o \l{ListView} arranges items in a horizontal or vertical list
45 \o \l{GridView} arranges items in a grid within the available space
46 \o \l{PathView} arranges items on a path
47 \o \l{WebView}{WebView} - available from the \l {QtWebKit QML Module}.
49 Unlike other views, \l WebView is not a fully-featured view item, and needs
50 to be combined with a \l Flickable item to create a view that performs like
53 These elements have properties and behaviors exclusive to each element. Visit
54 their respective documentation for more information.
58 Views display \l{qml-data-models}{models} onto the screen. A model could be a simple list of \l{QML Data Models#An Integer}{integer} or a \l{qml-c++-models}{C++ model}.
60 To assign a model to a view, bind the view's \c model property to a model.
61 \snippet doc/src/snippets/declarative/listview.qml model
62 \snippet doc/src/snippets/declarative/listview.qml model
64 For more information, consult the \l {QML Data Models} article.
66 \keyword qml-view-delegate
67 \section1 View Delegates
69 Views need a \e delegate to visually represent an item in a list. A view will
70 visualize each item list according to the template defined by the delegate.
71 Items in a model are accessible through the \c index property as well as the
73 \snippet doc/src/snippets/declarative/listview.qml delegate
74 \image listview-setup.png
76 \section1 Decorating Views
78 Views allow visual customization through \e decoration properties such as the \c header, \c footer, and \c section properties. By binding an object, usually
79 another visual object, to these properties, the views are decoratable. A footer
80 may include a \l Rectangle element showcasing borders or a header that displays
81 a logo on top of the list.
83 Suppose that a specific club wants to decorate its members list with its brand
84 colors. A member list is in a \c model and the \c delegate will display the
86 \snippet doc/src/snippets/declarative/listview-decorations.qml model
87 \snippet doc/src/snippets/declarative/listview-decorations.qml delegate
89 The club may decorate the members list by binding visual objects to the
90 \c header and \c footer properties. The visual object may be defined inline, in another file, or in a
91 \l {Component} element.
92 \snippet doc/src/snippets/declarative/listview-decorations.qml decorations
93 \image listview-decorations.png
95 \section1 ListView Sections
97 \l {ListView} contents may be grouped into \e sections, where related list items
98 are labeled according to their sections. Further, the sections may be decorated
99 with \l{qml-view-delegate}{delegates}.
101 A list may contain a list indicating people's names and the team on which team
103 \snippet doc/src/snippets/declarative/listview-sections.qml model
104 \snippet doc/src/snippets/declarative/listview-sections.qml delegate
106 The ListView element has the \c section
107 \l{Property Binding#Attached Properties}{attached property} that can combine
108 adjacent and related elements into a section. The section's \c property
109 property is for selecting which list element property to use as sections.
110 The \c criteria can dictate how the section names are displayed and the
111 \c delegate is similar to the views' \l {qml-view-delegate}{delegate} property.
112 \snippet doc/src/snippets/declarative/listview-sections.qml section
113 \image listview-section.png