/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** 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.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page qml-views.html
\inqmlmodule QtQuick 1
\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
\o \l{ListView} arranges items in a horizontal or vertical list
\o \l{GridView} arranges items in a grid within the available space
\o \l{PathView} arranges items on a path
\o \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 model

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 Mouse/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.


\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
*/