ListView doc improvements and examples clean up

11 files changed, 53 insertions, 34 deletions

diff --git a/doc/src/declarative/pics/ListViewSections.png b/doc/src/declarative/pics/ListViewSections.png
index 9270126..4e8f076 100644
--- a/doc/src/declarative/pics/ListViewSections.png
+++ b/doc/src/declarative/pics/ListViewSections.png
diff --git a/doc/src/examples/qml-examples.qdoc b/doc/src/examples/qml-examples.qdoc
index b6069f2..ee708a8 100644
--- a/doc/src/examples/qml-examples.qdoc
+++ b/doc/src/examples/qml-examples.qdoc
@@ -213,7 +213,7 @@
     \title Models and Views: ListView
     \example declarative/modelviews/listview
 
-    This example shows how to use the ListView element.
+    These examples show how to use the ListView element.
 */
 
 /*!
diff --git a/examples/declarative/modelviews/listview/PetsModel.qml b/examples/declarative/modelviews/listview/PetsModel.qml
index 70cdcdd..b77557d 100644
--- a/examples/declarative/modelviews/listview/PetsModel.qml
+++ b/examples/declarative/modelviews/listview/PetsModel.qml
@@ -40,10 +40,7 @@
 
 import Qt 4.7
 
-// ListModel allows free form list models to be defined and populated.
-
 ListModel {
-    id: petsModel
     ListElement {
         name: "Polly"
         type: "Parrot"
diff --git a/examples/declarative/modelviews/listview/RecipesModel.qml b/examples/declarative/modelviews/listview/RecipesModel.qml
index 03ab961..e6d829f 100644
--- a/examples/declarative/modelviews/listview/RecipesModel.qml
+++ b/examples/declarative/modelviews/listview/RecipesModel.qml
@@ -41,7 +41,6 @@
 import Qt 4.7
 
 ListModel {
-    id: recipesModel
     ListElement {
         title: "Pancakes"
         picture: "content/pics/pancakes.jpg"
diff --git a/examples/declarative/modelviews/listview/content/PressAndHoldButton.qml b/examples/declarative/modelviews/listview/content/PressAndHoldButton.qml
index 7c174e3..0d5a255 100644
--- a/examples/declarative/modelviews/listview/content/PressAndHoldButton.qml
+++ b/examples/declarative/modelviews/listview/content/PressAndHoldButton.qml
@@ -51,6 +51,11 @@ Image {
 
     scale: pressed ? 0.9 : 1
 
+    function release() {
+        autoRepeatClicks.stop()
+        container.pressed = false
+    }
+
     SequentialAnimation on pressed {
         id: autoRepeatClicks
         running: false
@@ -70,10 +75,8 @@ Image {
         anchors.fill: parent
 
         onPressed: autoRepeatClicks.start()
-        onReleased: { 
-            autoRepeatClicks.stop()
-            container.pressed = false
-        }
+        onReleased: container.release()
+        onCanceled: container.release()
     }
 }
 
diff --git a/examples/declarative/modelviews/listview/dynamiclist.qml b/examples/declarative/modelviews/listview/dynamiclist.qml
index 0e290f5..12c331b 100644
--- a/examples/declarative/modelviews/listview/dynamiclist.qml
+++ b/examples/declarative/modelviews/listview/dynamiclist.qml
@@ -45,7 +45,7 @@ import "content"
 
 Rectangle {
     id: container
-    width: 640; height: 480
+    width: 500; height: 400
     color: "#343434"
 
     // The model:
diff --git a/examples/declarative/modelviews/listview/expandingdelegates.qml b/examples/declarative/modelviews/listview/expandingdelegates.qml
index 94ea48f..24d6386 100644
--- a/examples/declarative/modelviews/listview/expandingdelegates.qml
+++ b/examples/declarative/modelviews/listview/expandingdelegates.qml
@@ -138,7 +138,8 @@ Rectangle {
                     id: flick
                     width: parent.width
                     anchors { top: methodTitle.bottom; bottom: parent.bottom }
-                    contentHeight: methodText.height; clip: true
+                    contentHeight: methodText.height
+                    clip: true
 
                     Text { id: methodText; text: method; wrapMode: Text.WordWrap; width: details.width }
                 }
@@ -197,6 +198,5 @@ Rectangle {
         anchors.fill: parent
         model: RecipesModel {}
         delegate: recipeDelegate
-        clip: true
     }
 }
diff --git a/examples/declarative/modelviews/listview/highlight.qml b/examples/declarative/modelviews/listview/highlight.qml
index 5748974..9f43409 100644
--- a/examples/declarative/modelviews/listview/highlight.qml
+++ b/examples/declarative/modelviews/listview/highlight.qml
@@ -38,6 +38,10 @@
 **
 ****************************************************************************/
 
+// This example shows how to create your own highlight delegate for a ListView
+// that uses a SpringFollow animation to provide custom movement when the
+// highlight bar is moved between items.
+
 import Qt 4.7
 
 Rectangle {
diff --git a/examples/declarative/modelviews/listview/highlightranges.qml b/examples/declarative/modelviews/listview/highlightranges.qml
index 162d8b7..f0d7f75 100644
--- a/examples/declarative/modelviews/listview/highlightranges.qml
+++ b/examples/declarative/modelviews/listview/highlightranges.qml
@@ -43,31 +43,31 @@ import Qt 4.7
 Rectangle {
     width: 600; height: 300
 
-    // Show the model in three lists, with different highlight ranges.
-    // preferredHighlightBegin and preferredHighlightEnd set the
-    // range in which to attempt to maintain the highlight.
+    // This example shows the same model in three different ListView items, 
+    // with different highlight ranges. The highlight ranges are set by the 
+    // preferredHighlightBegin and preferredHighlightEnd properties in ListView.
     //
-    // The second and third ListView set their currentIndex to be the
-    // same as the first, and the first ListView is given keyboard focus.
+    // The second and third ListViews set their currentIndex to be the
+    // same as the first. The first ListView is given keyboard focus.
     //
-    // The first list does not set a highlight range, so its currentItem
+    // The first ListView does not set a highlight range, so its currentItem
     // can move freely within the visible area. If it moves outside the
     // visible area, the view is automatically scrolled to keep the current
     // item visible.
     //
-    // The second list sets a highlight range which attempts to keep the
+    // The second ListView sets a highlight range which attempts to keep the
     // current item within the the bounds of the range. However,
     // items will not scroll beyond the beginning or end of the view,
     // forcing the highlight to move outside the range at the ends.
     //
-    // The third list sets the highlightRangeMode to StrictlyEnforceRange
+    // The third ListView sets the highlightRangeMode to StrictlyEnforceRange
     // and sets a range smaller than the height of an item.  This
     // forces the current item to change when the view is flicked,
     // since the highlight is unable to move.
     //
     // Note that the first ListView sets its currentIndex to be equal to
-    // the third ListView's currentIndex.  By flicking List3 with
-    // the mouse, the current index of List1 will be changed.
+    // the third ListView's currentIndex.  By flicking the third ListView with
+    // the mouse, the current index of the first ListView will be changed.
 
     ListView {
         id: list1
diff --git a/examples/declarative/modelviews/listview/sections.qml b/examples/declarative/modelviews/listview/sections.qml
index 8c038a0..8e0a49f 100644
--- a/examples/declarative/modelviews/listview/sections.qml
+++ b/examples/declarative/modelviews/listview/sections.qml
@@ -38,6 +38,9 @@
 **
 ****************************************************************************/
 
+// This example shows how a ListView can be separated into sections using
+// the ListView.section attached property.
+
 import Qt 4.7
 
 //! [0]
diff --git a/src/declarative/graphicsitems/qdeclarativelistview.cpp b/src/declarative/graphicsitems/qdeclarativelistview.cpp
index 48ac4a4..b0728c1 100644
--- a/src/declarative/graphicsitems/qdeclarativelistview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativelistview.cpp
@@ -1379,7 +1379,7 @@ void QDeclarativeListViewPrivate::flick(AxisData &data, qreal minExtent, qreal m
     to set \e {clip: true} in order to have the out of view items clipped
     nicely.
 
-    \sa ListModel, GridView
+    \sa ListModel, GridView, {declarative/modelviews/listview}{ListView examples}
 */
 
 QDeclarativeListView::QDeclarativeListView(QDeclarativeItem *parent)
@@ -1663,7 +1663,7 @@ int QDeclarativeListView::count() const
     so as to stay with the current item, unless the highlightFollowsCurrentItem
     property is false.
 
-    \sa highlightItem, highlightFollowsCurrentItem
+    \sa highlightItem, highlightFollowsCurrentItem, {declarative/modelviews/listview}{ListView examples}
 */
 QDeclarativeComponent *QDeclarativeListView::highlight() const
 {
@@ -1940,28 +1940,41 @@ void QDeclarativeListView::setCacheBuffer(int b)
 
     These properties hold the expression to be evaluated for the \l section attached property.
 
-    \c section.property hold the name of the property to use to determine
-    the section that holds the item.
+    The \l section attached property enables a ListView to be visually
+    separated into different parts. These properties determine how sections
+    are created.
+    
+    \c section.property holds the name of the property that is the basis
+    of each section.
 
-    \c section.criteria holds the criteria to use to access the section. It
-    can be either:
+    \c section.criteria holds the criteria for forming each section based on
+    \c section.property. This value can be one of:
 
     \list
-    \o ViewSection.FullString (default) - section is the value of the property.
-    \o ViewSection.FirstCharacter - section is the first character of the property value.
+    \o ViewSection.FullString (default) - sections are created based on the 
+    \c section.property value.
+    \o ViewSection.FirstCharacter - sections are created based on the first
+    character of the \c section.property value (for example, 'A', 'B', 'C' 
+    sections, etc. for an address book)
     \endlist
 
     \c section.delegate holds the delegate component for each section.
 
     Each item in the list has attached properties named \c ListView.section and
     \c ListView.prevSection.  These may be used to place a section header for
-    related items.  The example below assumes that the model is sorted by size of
-    pet.  The section expression is the size property.  If \c ListView.section and
-    \c ListView.prevSection differ, the item will display a section header.
-
+    related items.  
+
+    For example, here is a ListView that displays a list of animals, separated 
+    into sections. Each item in the ListView is placed in a different section 
+    depending on the "size" property of the model item. The \c sectionHeading
+    delegate component provides the light blue bar that marks the beginning of
+    each section.
+       
     \snippet examples/declarative/modelviews/listview/sections.qml 0
 
     \image ListViewSections.png
+
+    \sa {declarative/modelviews/listview}{ListView examples}
 */
 QDeclarativeViewSection *QDeclarativeListView::sectionCriteria()
 {