Item views: improve initial Z-value handling

Respect the initial Z-values of item, highlight, header, footer and
section delegate instances. Mention also the default values in docs.

Change-Id: I2ce4bb537898a0f5fdfa776b79d5747b1c080a7b
Reviewed-by: Michael Brasser <michael.brasser@live.com>
Reviewed-by: Alan Alpert <aalpert@blackberry.com>
Reviewed-by: Martin Jones <martin.jones@jollamobile.com>

3 files changed, 32 insertions, 9 deletions

diff --git a/src/quick/items/qquickgridview.cpp b/src/quick/items/qquickgridview.cpp
index e7b1437cf3..d56b5d0cab 100644
--- a/src/quick/items/qquickgridview.cpp
+++ b/src/quick/items/qquickgridview.cpp
@@ -1345,6 +1345,8 @@ void QQuickGridView::setHighlightFollowsCurrentItem(bool autoHighlight)
     The item size of the GridView is determined by cellHeight and cellWidth. It will not resize the items
     based on the size of the root item in the delegate.
 
+    The default \l {QQuickItem::z}{stacking order} of delegate instances is \c 1.
+
     \note Delegates are instantiated as needed and may be destroyed at any time.
     State should \e never be stored in a delegate.
 */
@@ -1373,6 +1375,8 @@ void QQuickGridView::setHighlightFollowsCurrentItem(bool autoHighlight)
 
   The highlightItem is managed by the view unless
   \l highlightFollowsCurrentItem is set to false.
+  The default \l {QQuickItem::z}{stacking order}
+  of the highlight item is \c 0.
 
   \sa highlight, highlightFollowsCurrentItem
 */
@@ -1391,6 +1395,7 @@ void QQuickGridView::setHighlightFollowsCurrentItem(bool autoHighlight)
   An instance of the highlight component is created for each view.
   The geometry of the resulting component instance will be managed by the view
   so as to stay with the current item, unless the highlightFollowsCurrentItem property is false.
+  The default \l {QQuickItem::z}{stacking order} of the highlight item is \c 0.
 
   \sa highlightItem, highlightFollowsCurrentItem
 */
@@ -1691,7 +1696,8 @@ void QQuickGridView::setSnapMode(SnapMode mode)
     This property holds the component to use as the footer.
 
     An instance of the footer component is created for each view.  The
-    footer is positioned at the end of the view, after any items.
+    footer is positioned at the end of the view, after any items. The
+    default \l {QQuickItem::z}{stacking order} of the footer is \c 1.
 
     \sa header, footerItem
 */
@@ -1701,6 +1707,7 @@ void QQuickGridView::setSnapMode(SnapMode mode)
 
     An instance of the header component is created for each view.  The
     header is positioned at the beginning of the view, before any items.
+    The default \l {QQuickItem::z}{stacking order} of the header is \c 1.
 
     \sa footer, headerItem
 */
@@ -1711,6 +1718,7 @@ void QQuickGridView::setSnapMode(SnapMode mode)
 
     An instance of the header component is created for each view.  The
     header is positioned at the beginning of the view, before any items.
+    The default \l {QQuickItem::z}{stacking order} of the header is \c 1.
 
     \sa header, footerItem
 */
@@ -1720,7 +1728,8 @@ void QQuickGridView::setSnapMode(SnapMode mode)
     This holds the footer item created from the \l footer component.
 
     An instance of the footer component is created for each view.  The
-    footer is positioned at the end of the view, after any items.
+    footer is positioned at the end of the view, after any items. The
+    default \l {QQuickItem::z}{stacking order} of the footer is \c 1.
 
     \sa footer, headerItem
 */
diff --git a/src/quick/items/qquickitemview.cpp b/src/quick/items/qquickitemview.cpp
index e51a562490..9685834578 100644
--- a/src/quick/items/qquickitemview.cpp
+++ b/src/quick/items/qquickitemview.cpp
@@ -2318,7 +2318,8 @@ void QQuickItemView::initItem(int, QObject *object)
 {
     QQuickItem* item = qmlobject_cast<QQuickItem*>(object);
     if (item) {
-        item->setZ(1);
+        if (qFuzzyIsNull(item->z()))
+            item->setZ(1);
         item->setParentItem(contentItem());
         QQuickItemPrivate::get(item)->setCulled(true);
     }
@@ -2382,7 +2383,8 @@ QQuickItem *QQuickItemViewPrivate::createComponentItem(QQmlComponent *component,
         item = new QQuickItem;
     }
     if (item) {
-        item->setZ(zValue);
+        if (qFuzzyIsNull(item->z()))
+            item->setZ(zValue);
         QQml_setParent_noEvent(item, q->contentItem());
         item->setParentItem(q->contentItem());
     }
diff --git a/src/quick/items/qquicklistview.cpp b/src/quick/items/qquicklistview.cpp
index 3ac28f438b..786468bbfd 100644
--- a/src/quick/items/qquicklistview.cpp
+++ b/src/quick/items/qquicklistview.cpp
@@ -966,7 +966,8 @@ QQuickItem * QQuickListViewPrivate::getSectionItem(const QString &section)
             if (!sectionItem) {
                 delete nobj;
             } else {
-                sectionItem->setZ(2);
+                if (qFuzzyIsNull(sectionItem->z()))
+                    sectionItem->setZ(2);
                 QQml_setParent_noEvent(sectionItem, contentItem);
                 sectionItem->setParentItem(contentItem);
             }
@@ -1881,6 +1882,8 @@ QQuickListView::~QQuickListView()
     It is recommended that the delegate's size be a whole number to avoid sub-pixel
     alignment of items.
 
+    The default \l {QQuickItem::z}{stacking order} of delegate instances is \c 1.
+
     \note Delegates are instantiated as needed and may be destroyed at any time.
     They are parented to ListView's \l {Flickable::contentItem}{contentItem}, not to the view itself.
     State should \e never be stored in a delegate.
@@ -1908,6 +1911,8 @@ QQuickListView::~QQuickListView()
 
   The \c highlightItem is managed by the view unless
   \l highlightFollowsCurrentItem is set to false.
+  The default \l {QQuickItem::z}{stacking order}
+  of the highlight item is \c 0.
 
   \sa highlight, highlightFollowsCurrentItem
 */
@@ -1924,7 +1929,8 @@ QQuickListView::~QQuickListView()
     An instance of the highlight component is created for each list.
     The geometry of the resulting component instance is managed by the list
     so as to stay with the current item, unless the highlightFollowsCurrentItem
-    property is false.
+    property is false. The default \l {QQuickItem::z}{stacking order} of the
+    highlight item is \c 0.
 
     \sa highlightItem, highlightFollowsCurrentItem,
     {Qt Quick Examples - Views#Highlight demonstrates adding a custom highlight to a ListView.}{ListView highlight example}
@@ -2202,7 +2208,9 @@ void QQuickListView::setOrientation(QQuickListView::Orientation orientation)
     A case insensitive comparison is used when determining section
     boundaries.
 
-    \c section.delegate holds the delegate component for each section.
+    \c section.delegate holds the delegate component for each section. The
+    default \l {QQuickItem::z}{stacking order} of section delegate instances
+    is \c 2.
 
     \c section.labelPositioning determines whether the current and/or
     next section labels stick to the start/end of the view, and whether
@@ -2388,7 +2396,8 @@ void QQuickListView::setSnapMode(SnapMode mode)
     This property holds the component to use as the footer.
 
     An instance of the footer component is created for each view.  The
-    footer is positioned at the end of the view, after any items.
+    footer is positioned at the end of the view, after any items. The
+    default \l {QQuickItem::z}{stacking order} of the footer is \c 1.
 
     \sa header, footerItem
 */
@@ -2400,6 +2409,7 @@ void QQuickListView::setSnapMode(SnapMode mode)
 
     An instance of the header component is created for each view.  The
     header is positioned at the beginning of the view, before any items.
+    The default \l {QQuickItem::z}{stacking order} of the header is \c 1.
 
     \sa footer, headerItem
 */
@@ -2410,6 +2420,7 @@ void QQuickListView::setSnapMode(SnapMode mode)
 
     An instance of the header component is created for each view.  The
     header is positioned at the beginning of the view, before any items.
+    The default \l {QQuickItem::z}{stacking order} of the header is \c 1.
 
     \sa header, footerItem
 */
@@ -2419,7 +2430,8 @@ void QQuickListView::setSnapMode(SnapMode mode)
     This holds the footer item created from the \l footer component.
 
     An instance of the footer component is created for each view.  The
-    footer is positioned at the end of the view, after any items.
+    footer is positioned at the end of the view, after any items. The
+    default \l {QQuickItem::z}{stacking order} of the footer is \c 1.
 
     \sa footer, headerItem
 */