/****************************************************************************
**
** 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 qtquick-modelview.html
\title QML Models and Views
\brief how to display and form data in QML

Simply put, applications need to form data and display the data. QML 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
elements 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 an element.

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

    \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
    \endlist

    These elements have properties and behaviors exclusive to each element.
    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 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/qml/listview-decorations.qml model
    \snippet doc/src/snippets/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} element.
    \snippet doc/src/snippets/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 doc/src/snippets/qml/listview-sections.qml model
    \snippet doc/src/snippets/qml/listview-sections.qml delegate

    The ListView element has the \c section \l{Property Binding in QML#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/qml/listview-sections.qml section
    \image listview-section.png

\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/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 doc/src/snippets/qml/models/views-models-delegates.qml rectangle

\keyword 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 doc/src/snippets/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 element 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
    elements. In addition, models can be created with Qt C++ and then made
    available to the \l{The QML Engine}{QML engine} for use by
    QML components. For information about creating these models, visit the
    \l{Exposing C++ Models} and \l{Creating QML Types} articles.

    The use of positioner items to arrange items from a model is covered in
    \l{Generating Items with Repeaters}.

    \section2 ListModel

    ListModel is a simple hierarchy of elements specified in QML.  The
    available roles are specified by the \l ListElement properties.

    \snippet doc/src/snippets/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 doc/src/snippets/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 doc/src/snippets/qml/qml-data-models/dynamic-listmodel.qml model
    \dots
    \snippet doc/src/snippets/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 XmlListModel

    XmlListModel allows construction of a model from an XML data source. The roles
    are specified via the \l XmlRole element. The element 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 \l{declarative/rssnews}{RSS News demo} shows how XmlListModel can
    be used to display an RSS feed.


    \section2 VisualItemModel

    VisualItemModel allows QML items 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.

    \snippet doc/src/snippets/qml/models/visual-model-and-view.qml visual model and view

    Note that in the above example there is no delegate required.
    The items of the model itself provide the visual elements that
    will be positioned by the view.

    \section2 Integers as Models

    An integer can be used as a model that contains a certain number
    of elements. 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


    \section2 Object Instances as Models

    An object instance can be used to specify a model with a single object
    element. 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 element 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

    \keyword 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{Exposing C++ Models} 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 \l{#Grid}{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 doc/src/snippets/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. This is explained in the \l{QML Data Models#An Integer}{QML Data Models}
document.

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.

Additionally, changing the opacity of items to zero will cause them to
disappear using the remove transition, and making the opacity non-zero will
cause them to appear using the add transition.


*/