Re-wrote QML Views overview page. Created new snippets and images.

Task-number: QTBUG-16071

8 files changed, 316 insertions, 61 deletions

diff --git a/doc/src/declarative/qmlviews.qdoc b/doc/src/declarative/qmlviews.qdoc
index c207d9a..8b2ca96 100644
--- a/doc/src/declarative/qmlviews.qdoc
+++ b/doc/src/declarative/qmlviews.qdoc
@@ -33,74 +33,82 @@
 \nextpage {Extending QML Functionalities using C++}
 \title Presenting Data with Views
 
-\section1 Introduction
-
 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}{ListView} arranges items in a horizontal or vertical list
-\o \l{#GridView}{GridView} arranges items in a grid within the available space
-\o \l{#PathView}{PathView} arranges items on a path
-\o \l{WebView}{WebView} - available from the Qt WebKit module.
-
+\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 these items, \l WebView is not a fully-featured view item, and needs
+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 a \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++ 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
 
-\section1 ListView
-
-\l ListView shows a classic list of items with horizontal or vertical placing
-of items.
-
-\beginfloatright
-\inlineimage qml-listview-snippet.png
-\endfloat
-
-The following example shows a minimal ListView displaying a sequence of
-numbers (using an \l{QML Data Models#An Integer}{integer as a model}).
-A simple delegate is used to define an items for each piece of data in the
-model.
-
-\clearfloat
-\snippet doc/src/snippets/declarative/listview/listview-snippet.qml document
+For more information, consult the \l {QML Data Models} article.
 
+\keyword qml-view-delegate
+\section1 View Delegates
 
-
-\section2 GridView
-
-\l GridView displays items in a grid like an file manager's icon view.
-
-\section2 PathView
-
-\l PathView displays items on a path, where the selection remains in
-the same place and the items move around it.
+Views need a \e delegate to visually represent an item in a list. A view will
+visual each item list according to the template defined by the delegate.
+Properties of the model are accessible as well as an \c index property.
+\snippet doc/src/snippets/declarative/listview.qml delegate
+\image listview-setup.png
 
 \section1 Decorating Views
 
-\section2 Headers and Footers
-
-\section2 Sections
-
-\section2 Navigation
-
-In traditional user interfaces, views can be scrolled using standard
-controls, such as scroll bars and arrow buttons. In some situations, it
-is also possible to drag the view directly by pressing and holding a
-mouse button while moving the cursor. In touch-based user interfaces,
-this dragging action is often complemented with a flicking action, where
-scrolling continues after the user has stopped touching the view.
+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 labelled 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{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/declarative/listview-sections.qml section
+\image listview-section.png
 
-\section1 Further Reading
 */
diff --git a/doc/src/images/listview-decorations.png b/doc/src/images/listview-decorations.png
new file mode 100644
index 0000000..445c648
--- /dev/null
+++ b/doc/src/images/listview-decorations.png
diff --git a/doc/src/images/listview-section.png b/doc/src/images/listview-section.png
new file mode 100644
index 0000000..a3664fc
--- /dev/null
+++ b/doc/src/images/listview-section.png
diff --git a/doc/src/images/listview-setup.png b/doc/src/images/listview-setup.png
new file mode 100644
index 0000000..5293d05
--- /dev/null
+++ b/doc/src/images/listview-setup.png
diff --git a/doc/src/images/qml-listview-snippet.png b/doc/src/images/qml-listview-snippet.png
deleted file mode 100644
index 0ee0ffc..0000000
--- a/doc/src/images/qml-listview-snippet.png
+++ /dev/null
diff --git a/doc/src/snippets/declarative/listview-decorations.qml b/doc/src/snippets/declarative/listview-decorations.qml
new file mode 100644
index 0000000..6b6d950
--- /dev/null
+++ b/doc/src/snippets/declarative/listview-decorations.qml
@@ -0,0 +1,111 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [document]
+import QtQuick 1.0
+
+//! [parent begin]
+Rectangle {
+//! [parent begin]
+    width: 550; height: 220; color: "white"
+
+//! [model]
+ListModel {
+    id: nameModel
+    ListElement { name: "Alice" }
+    ListElement { name: "Bob" }
+    ListElement { name: "Jane" }
+    ListElement { name: "Harry" }
+    ListElement { name: "Wendy" }
+}
+//! [model]
+
+//! [delegate]
+Component {
+    id: nameDelegate
+    Text {
+        text: name;
+        font.pixelSize: 24
+    }
+}
+//! [delegate]
+
+//! [decorations]
+ListView {
+    anchors.fill: parent
+    clip: true
+    model: nameModel
+    delegate: nameDelegate
+    header: bannercomponent
+    footer: Rectangle {
+        width: parent.width; height: 30;
+        gradient: clubcolors
+    }
+    highlight: Rectangle {
+        width: parent.width
+        color: "lightgray"
+    }
+}
+
+Component {     //instantiated when header is processed
+    id: bannercomponent
+    Rectangle {
+        id: banner
+        width: parent.width; height: 50
+        gradient: clubcolors
+        border {color: "#9EDDF2"; width: 2}
+        Text {
+            anchors.centerIn: parent
+            text: "Club Members"
+            font.pixelSize: 32
+        }
+    }
+}
+Gradient {
+    id: clubcolors
+    GradientStop { position: 0.0; color: "#8EE2FE"}
+    GradientStop { position: 0.66; color: "#7ED2EE"}
+}
+//! [decorations]
+
+//! [parent end]
+}
+//! [parent end]
+//! [document]
diff --git a/doc/src/snippets/declarative/listview-sections.qml b/doc/src/snippets/declarative/listview-sections.qml
new file mode 100644
index 0000000..a573059
--- /dev/null
+++ b/doc/src/snippets/declarative/listview-sections.qml
@@ -0,0 +1,101 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+** notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//! [document]
+import QtQuick 1.0
+
+//! [parent begin]
+Rectangle {
+//! [parent begin]
+    width: 150; height: 300; color: "white"
+
+//! [model]
+ListModel {
+    id: nameModel
+    ListElement { name: "Alice"; team: "Crypto" }
+    ListElement { name: "Bob"; team: "Crypto" }
+    ListElement { name: "Jane"; team: "QA" }
+    ListElement { name: "Victor"; team: "QA" }
+    ListElement { name: "Wendy"; team: "Graphics" }
+}
+//! [model]
+
+//! [delegate]
+Component {
+    id: nameDelegate
+    Text {
+        text: name;
+        font.pixelSize: 24
+        anchors.left: parent.left
+        anchors.leftMargin: 2
+    }
+}
+//! [delegate]
+
+//! [section]
+ListView {
+    anchors.fill: parent
+    model: nameModel
+    delegate: nameDelegate
+    focus: true
+    highlight: Rectangle {
+        color: "lightblue"
+        width: parent.width
+    }
+    section {
+        property: "team"
+        criteria: ViewSection.FullString
+        delegate: Rectangle {
+            color: "#b0dfb0"
+            width: parent.width
+            height: childrenRect.height + 4
+            Text { anchors.horizontalCenter: parent.horizontalCenter
+                font.pixelSize: 16
+                font.bold: true
+                text: section
+            }
+        }
+    }
+}
+//! [section]
+
+//! [parent end]
+}
+//! [parent end]
+//! [document]
diff --git a/doc/src/snippets/declarative/listview/listview-snippet.qml b/doc/src/snippets/declarative/listview.qml
index f73dec9..4bb48bc 100644
--- a/doc/src/snippets/declarative/listview/listview-snippet.qml
+++ b/doc/src/snippets/declarative/listview.qml
@@ -13,15 +13,15 @@
 ** modification, are permitted provided that the following conditions are
 ** met:
 **   * Redistributions of source code must retain the above copyright
-**     notice, this list of conditions and the following disclaimer.
+** notice, this list of conditions and the following disclaimer.
 **   * Redistributions in binary form must reproduce the above copyright
-**     notice, this list of conditions and the following disclaimer in
-**     the documentation and/or other materials provided with the
-**     distribution.
+** notice, this list of conditions and the following disclaimer in
+** the documentation and/or other materials provided with the
+** distribution.
 **   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
-**     the names of its contributors may be used to endorse or promote
-**     products derived from this software without specific prior written
-**     permission.
+** the names of its contributors may be used to endorse or promote
+** products derived from this software without specific prior written
+** permission.
 **
 ** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 ** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
@@ -41,12 +41,47 @@
 //! [document]
 import QtQuick 1.0
 
-ListView {
-    width: 50; height: 200
-    model: 4
-    delegate: Text {
-        text: index;
-        font.pixelSize: 40
+//! [parent begin]
+Rectangle {
+//! [parent begin]
+    width: 175; height: 175; color: "white"
+
+//! [model]
+ListModel {
+    id: petlist
+    ListElement { type: "Cat" }
+    ListElement { type: "Dog" }
+    ListElement { type: "Mouse" }
+    ListElement { type: "Rabbit" }
+    ListElement { type: "Horse" }
+}
+//! [model]
+
+//! [delegate]
+Component {
+    id: petdelegate
+    Text {
+        id: label
+        font.pixelSize: 24
+        text: if (index == 0)
+            label.text = type + " (default)"
+        else
+            text: type
     }
 }
+//! [delegate]
+
+//! [view]
+ListView {
+    id: view
+    anchors.fill: parent
+
+    model: petlist
+    delegate: petdelegate
+}
+//! [view]
+
+//! [parent end]
+}
+//! [parent end]
 //! [document]