/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** 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 Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page qml-views.html
\ingroup qml-features
\contentspage QML Features
\previouspage {QML Data Models}{Structuring Data with Models}
\nextpage {Extending QML Functionalities using C++}
\title Presenting Data with Views

Views are containers for collections of items. They are feature-rich and can be
customizable to meet style or behavior requirements.

\keyword qml-view-elements
A set of standard views are provided in the basic set of Qt Quick
graphical elements:

\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
\li \l{WebView}{WebView} - available from the \l {QtWebKit QML Module}.
\endlist
Unlike other views, \l WebView is not a fully-featured view item, and needs
to be combined with a \l Flickable item to create a view that performs like
a Web browser.

These elements have properties and behaviors exclusive to each element. Visit
their respective documentation for more information.

\section1 Models

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}.

To assign a model to a view, bind the view's \c model property to a model.
\snippet doc/src/snippets/declarative/listview.qml model
\snippet doc/src/snippets/declarative/listview.qml view

For more information, consult the \l {QML Data Models} article.

\keyword 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 doc/src/snippets/declarative/listview.qml delegate
\image listview-setup.png

\section1 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 element 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 doc/src/snippets/declarative/listview-decorations.qml model
\snippet doc/src/snippets/declarative/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} element.
\snippet doc/src/snippets/declarative/listview-decorations.qml decorations
\image listview-decorations.png

\section1 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 doc/src/snippets/declarative/listview-sections.qml model
\snippet doc/src/snippets/declarative/listview-sections.qml delegate

The ListView element has the \c section
\l{Property Binding#Attached Properties}{attached property} that can combine
adjacent and related elements into a section. The section's \c property
property is for selecting which list element property to use as sections.
The \c criteria can dictate how the section names are displayed and the
\c delegate is similar to the views' \l {qml-view-delegate}{delegate} property.
\snippet doc/src/snippets/declarative/listview-sections.qml section
\image listview-section.png
*/