Improve docs on attached properties on view delegates.

Clarify that the properties are attached to the root of the delegate,
and must be accessed as such by child items.

Task-number: QTBUG-16193
Reviewed-by: Bea Lam

7 files changed, 75 insertions, 8 deletions

diff --git a/doc/src/snippets/declarative/gridview/gridview.qml b/doc/src/snippets/declarative/gridview/gridview.qml
index 73e58ec5bb..87d70de2af 100644
--- a/doc/src/snippets/declarative/gridview/gridview.qml
+++ b/doc/src/snippets/declarative/gridview/gridview.qml
@@ -132,6 +132,32 @@ GridView {
 }
 //![highlightFollowsCurrentItem]
 
+//![isCurrentItem]
+GridView {
+    width: 300; height: 200
+    cellWidth: 80; cellHeight: 80
+
+    Component {
+        id: contactsDelegate
+        Rectangle {
+            id: wrapper
+            width: 80
+            height: 80
+            color: GridView.isCurrentItem ? "black" : "red"
+            Text {
+                id: contactInfo
+                text: name + ": " + number
+                color: wrapper.GridView.isCurrentItem ? "red" : "black"
+            }
+        }
+    }
+
+    model: ContactModel {}
+    delegate: contactsDelegate
+    focus: true
+}
+//![isCurrentItem]
+
 }
 
 }
diff --git a/doc/src/snippets/declarative/listview/listview.qml b/doc/src/snippets/declarative/listview/listview.qml
index 8ba47a86e9..370429e628 100644
--- a/doc/src/snippets/declarative/listview/listview.qml
+++ b/doc/src/snippets/declarative/listview/listview.qml
@@ -127,10 +127,16 @@ ListView {
 
     Component {
         id: contactsDelegate
-        Text {
-            id: contactInfo
-            text: name + ": " + number
-            color: contactInfo.ListView.isCurrentItem ? "red" : "black"
+        Rectangle {
+            id: wrapper
+            width: 180
+            height: contactInfo.height
+            color: ListView.isCurrentItem ? "black" : "red"
+            Text {
+                id: contactInfo
+                text: name + ": " + number
+                color: wrapper.ListView.isCurrentItem ? "red" : "black"
+            }
         }
     }
 
diff --git a/doc/src/snippets/declarative/pathview/pathattributes.qml b/doc/src/snippets/declarative/pathview/pathattributes.qml
index d6dacdbc38..be933e05bd 100644
--- a/doc/src/snippets/declarative/pathview/pathattributes.qml
+++ b/doc/src/snippets/declarative/pathview/pathattributes.qml
@@ -52,8 +52,8 @@ Rectangle {
             scale: PathView.iconScale
             opacity: PathView.iconOpacity
             Column {
-                Image { anchors.horizontalCenter: name.horizontalCenter; width: 64; height: 64; source: icon }
-                Text { text: name; font.pointSize: 16}
+                Image { anchors.horizontalCenter: nameText.horizontalCenter; width: 64; height: 64; source: icon }
+                Text { id: nameText; text: name; font.pointSize: 16 }
             }
         }
     }
diff --git a/doc/src/snippets/declarative/pathview/pathview.qml b/doc/src/snippets/declarative/pathview/pathview.qml
index 93298c4406..e5e90a4480 100644
--- a/doc/src/snippets/declarative/pathview/pathview.qml
+++ b/doc/src/snippets/declarative/pathview/pathview.qml
@@ -48,8 +48,18 @@ Rectangle {
     Component {
         id: delegate
         Column {
-            Image { anchors.horizontalCenter: name.horizontalCenter; width: 64; height: 64; source: icon }
-            Text { text: name; font.pointSize: 16 }
+            id: wrapper
+            Image {
+                anchors.horizontalCenter: nameText.horizontalCenter
+                width: 64; height: 64
+                source: icon
+            }
+            Text {
+                id: nameText
+                text: name
+                font.pointSize: 16
+                color: wrapper.PathView.isCurrentItem ? "red" : "black"
+            }
         }
     }
 //! [1]
diff --git a/src/declarative/graphicsitems/qdeclarativegridview.cpp b/src/declarative/graphicsitems/qdeclarativegridview.cpp
index 4a6a9dcfde..7ddf6a2590 100644
--- a/src/declarative/graphicsitems/qdeclarativegridview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativegridview.cpp
@@ -1131,6 +1131,13 @@ void QDeclarativeGridViewPrivate::flick(AxisData &data, qreal minExtent, qreal m
     Delegates are instantiated as needed and may be destroyed at any time.
     State should \e never be stored in a delegate.
 
+    GridView attaches a number of properties to the root item of the delegate, for example
+    \c {GridView.isCurrentItem}.  In the following example, the root delegate item can access
+    this attached property directly as \c GridView.isCurrentItem, while the child
+    \c contactInfo object must refer to this property as \c wrapper.GridView.isCurrentItem.
+
+    \snippet doc/src/snippets/declarative/gridview/gridview.qml isCurrentItem
+
     \note Views do not set the \l{Item::}{clip} property automatically.
     If the view is not clipped by another item or the screen, it will be necessary
     to set this property to true in order to clip the items that are partially or
@@ -1167,6 +1174,8 @@ QDeclarativeGridView::~QDeclarativeGridView()
     This attached property holds the view that manages this delegate instance.
 
     It is attached to each instance of the delegate.
+
+    \snippet doc/src/snippets/declarative/gridview/gridview.qml isCurrentItem
 */
 
 /*!
diff --git a/src/declarative/graphicsitems/qdeclarativelistview.cpp b/src/declarative/graphicsitems/qdeclarativelistview.cpp
index 86c8756081..702442bb81 100644
--- a/src/declarative/graphicsitems/qdeclarativelistview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativelistview.cpp
@@ -1416,6 +1416,13 @@ void QDeclarativeListViewPrivate::flick(AxisData &data, qreal minExtent, qreal m
     Delegates are instantiated as needed and may be destroyed at any time.
     State should \e never be stored in a delegate.
 
+    ListView attaches a number of properties to the root item of the delegate, for example
+    \c {ListView.isCurrentItem}.  In the following example, the root delegate item can access
+    this attached property directly as \c ListView.isCurrentItem, while the child
+    \c contactInfo object must refer to this property as \c wrapper.ListView.isCurrentItem.
+
+    \snippet doc/src/snippets/declarative/listview/listview.qml isCurrentItem
+
     \note Views do not enable \e clip automatically.  If the view
     is not clipped by another item or the screen, it will be necessary
     to set \e {clip: true} in order to have the out of view items clipped
diff --git a/src/declarative/graphicsitems/qdeclarativepathview.cpp b/src/declarative/graphicsitems/qdeclarativepathview.cpp
index a6f44b3ec9..e3987d065c 100644
--- a/src/declarative/graphicsitems/qdeclarativepathview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativepathview.cpp
@@ -393,6 +393,13 @@ void QDeclarativePathViewPrivate::regenerate()
     Delegates are instantiated as needed and may be destroyed at any time.
     State should \e never be stored in a delegate.
 
+    PathView attaches a number of properties to the root item of the delegate, for example
+    \c {PathView.isCurrentItem}.  In the following example, the root delegate item can access
+    this attached property directly as \c PathView.isCurrentItem, while the child
+    \c nameText object must refer to this property as \c wrapper.PathView.isCurrentItem.
+
+    \snippet doc/src/snippets/declarative/pathview/pathview.qml 1
+
     \bold Note that views do not enable \e clip automatically.  If the view
     is not clipped by another item or the screen, it will be necessary
     to set \e {clip: true} in order to have the out of view items clipped
@@ -452,6 +459,8 @@ QDeclarativePathView::~QDeclarativePathView()
     It is attached to each instance of the delegate.
 
     This property may be used to adjust the appearance of the current item.
+
+    \snippet doc/src/snippets/declarative/pathview/pathview.qml 1
 */
 
 /*!