Reorganize "concept" pages in QtQuick docs

This removes concepts/topic.qdoc and move this content into individual
concept topic pages under individual directories for each concept to
avoid having a really long "concepts" index page.

This change also:
- Moves components.qdoc ("Defining reusable components") into the
 appdevguide/ since it's not specific to QtQuick features - it's more
 about how to use a QtQml feature to build QML apps.
- Moves the part of qtqml/doc/src/cppintegration/data.qdoc that
 discusses how to use C++ models with QtQuick views into
 quick/doc/src/concepts/modelviewsdata/data-cppmodels.qdoc.

Change-Id: Id18a1d56acaaac41714c13cbc94bb3b80f337355
Reviewed-by: Chris Adams <christopher.adams@nokia.com>

1 files changed, 384 insertions, 0 deletions

diff --git a/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc b/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc
new file mode 100644
index 0000000000..d2c0307d03
--- /dev/null
+++ b/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc
@@ -0,0 +1,384 @@
+/****************************************************************************
+**
+** 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-modelviewsdata-modelview.html
+\title Models and Views in Qt Quick
+\brief how to display and form data in Qt Quick
+
+Simply put, applications need to form data and display the data. Qt Quick 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
+types 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 qtquick-views
+    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 qml/listview-decorations.qml model
+    \snippet 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 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 qml/listview-sections.qml model
+    \snippet qml/listview-sections.qml delegate
+
+    The ListView element has the \c section
+    \l{qtqml-syntax-objectattributes.html#Attached-properties-and-attached-signal-handlers}
+    {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 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 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 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 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{qtqml-cppclasses-engine.html}{QML engine} for use by
+    QML components. For information about creating these models, visit the
+    \l{qtquick-modelviewsdata-cppmodels.html}{Using C++ Models with QtQuick Views}
+    and \l{qtqml-typesystem-topic.html#qml-object-types}
+    {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 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 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 qml/qml-data-models/dynamic-listmodel.qml model
+    \dots
+    \snippet 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 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{qtquick-modelviewsdata-cppmodels.html}{Using C++ Models with QtQuick Views}
+    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 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 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.
+
+
+*/