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>

12 files changed, 331 insertions, 54 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
 */
diff --git a/tests/auto/quick/qquickgridview/data/boundZValues.qml b/tests/auto/quick/qquickgridview/data/boundZValues.qml
new file mode 100644
index 0000000000..7a1ca48a81
--- /dev/null
+++ b/tests/auto/quick/qquickgridview/data/boundZValues.qml
@@ -0,0 +1,46 @@
+import QtQuick 2.0
+
+Rectangle {
+    width: 240
+    height: 320
+
+    GridView {
+        id: grid
+
+        property real itemZ: 342
+        property real headerZ: 341
+        property real footerZ: 340
+        property real highlightZ: 339
+
+        anchors.fill: parent
+        objectName: "grid"
+        model: ListModel { ListElement { text: "text" } }
+        currentIndex: 0
+
+        delegate: Text {
+            objectName: "wrapper"
+            font.pointSize: 20
+            text: index
+            z: grid.itemZ
+        }
+
+        header: Rectangle {
+            width: 240
+            height: 30
+            z: grid.headerZ
+        }
+
+        footer: Rectangle {
+            width: 240
+            height: 30
+            z: grid.footerZ
+        }
+
+        highlight: Rectangle {
+            width: 240
+            height: 30
+            z: grid.highlightZ
+        }
+    }
+}
+
diff --git a/tests/auto/quick/qquickgridview/data/constantZValues.qml b/tests/auto/quick/qquickgridview/data/constantZValues.qml
new file mode 100644
index 0000000000..7cf564a12e
--- /dev/null
+++ b/tests/auto/quick/qquickgridview/data/constantZValues.qml
@@ -0,0 +1,46 @@
+import QtQuick 2.0
+
+Rectangle {
+    width: 240
+    height: 320
+
+    GridView {
+        id: grid
+
+        property real itemZ: 241
+        property real headerZ: 242
+        property real footerZ: 243
+        property real highlightZ: 244
+
+        anchors.fill: parent
+        objectName: "grid"
+        model: ListModel { ListElement { text: "text" } }
+        currentIndex: 0
+
+        delegate: Text {
+            objectName: "wrapper"
+            font.pointSize: 20
+            text: index
+            z: 241
+        }
+
+        header: Rectangle {
+            width: 240
+            height: 30
+            z: 242
+        }
+
+        footer: Rectangle {
+            width: 240
+            height: 30
+            z: 243
+        }
+
+        highlight: Rectangle {
+            width: 240
+            height: 30
+            z: 244
+        }
+    }
+}
+
diff --git a/tests/auto/quick/qquickgridview/data/initialZValues.qml b/tests/auto/quick/qquickgridview/data/defaultZValues.qml
index 9768b2c695..53f11bb2da 100644
--- a/tests/auto/quick/qquickgridview/data/initialZValues.qml
+++ b/tests/auto/quick/qquickgridview/data/defaultZValues.qml
@@ -7,11 +7,15 @@ Rectangle {
     GridView {
         id: grid
 
-        property real initialZ: 342
+        property real itemZ: 1
+        property real headerZ: 1
+        property real footerZ: 1
+        property real highlightZ: 0
 
         anchors.fill: parent
         objectName: "grid"
-        model: ListModel {}
+        model: ListModel { ListElement { text: "text" } }
+        currentIndex: 0
 
         delegate: Text {
             objectName: "wrapper"
@@ -22,13 +26,11 @@ Rectangle {
         header: Rectangle {
             width: 240
             height: 30
-            z: grid.initialZ
         }
 
         footer: Rectangle {
             width: 240
             height: 30
-            z: grid.initialZ
         }
     }
 }
diff --git a/tests/auto/quick/qquickgridview/tst_qquickgridview.cpp b/tests/auto/quick/qquickgridview/tst_qquickgridview.cpp
index f4eec18690..890174e2a8 100644
--- a/tests/auto/quick/qquickgridview/tst_qquickgridview.cpp
+++ b/tests/auto/quick/qquickgridview/tst_qquickgridview.cpp
@@ -121,6 +121,7 @@ private slots:
     void footer();
     void footer_data();
     void initialZValues();
+    void initialZValues_data();
     void header();
     void header_data();
     void extents();
@@ -3200,8 +3201,9 @@ void tst_QQuickGridView::footer_data()
 
 void tst_QQuickGridView::initialZValues()
 {
+    QFETCH(QString, fileName);
     QQuickView *window = createView();
-    window->setSource(testFileUrl("initialZValues.qml"));
+    window->setSource(testFileUrl(fileName));
     qApp->processEvents();
 
     QQuickGridView *gridview = findItem<QQuickGridView>(window->rootObject(), "grid");
@@ -3209,15 +3211,29 @@ void tst_QQuickGridView::initialZValues()
     QQuickItem *contentItem = gridview->contentItem();
     QTRY_VERIFY(contentItem != 0);
 
+    QVERIFY(gridview->currentItem());
+    QTRY_COMPARE(gridview->currentItem()->z(), gridview->property("itemZ").toReal());
+
     QVERIFY(gridview->headerItem());
-    QTRY_COMPARE(gridview->headerItem()->z(), gridview->property("initialZ").toReal());
+    QTRY_COMPARE(gridview->headerItem()->z(), gridview->property("headerZ").toReal());
 
     QVERIFY(gridview->footerItem());
-    QTRY_COMPARE(gridview->footerItem()->z(), gridview->property("initialZ").toReal());
+    QTRY_COMPARE(gridview->footerItem()->z(), gridview->property("footerZ").toReal());
+
+    QVERIFY(gridview->highlightItem());
+    QTRY_COMPARE(gridview->highlightItem()->z(), gridview->property("highlightZ").toReal());
 
     delete window;
 }
 
+void tst_QQuickGridView::initialZValues_data()
+{
+    QTest::addColumn<QString>("fileName");
+    QTest::newRow("defaults") << "defaultZValues.qml";
+    QTest::newRow("constants") << "constantZValues.qml";
+    QTest::newRow("bindings") << "boundZValues.qml";
+}
+
 void tst_QQuickGridView::header()
 {
     QFETCH(QQuickGridView::Flow, flow);
diff --git a/tests/auto/quick/qquicklistview/data/boundZValues.qml b/tests/auto/quick/qquicklistview/data/boundZValues.qml
new file mode 100644
index 0000000000..10810e540d
--- /dev/null
+++ b/tests/auto/quick/qquicklistview/data/boundZValues.qml
@@ -0,0 +1,55 @@
+import QtQuick 2.0
+
+Rectangle {
+    width: 240
+    height: 320
+
+    ListView {
+        id: list
+
+        property real itemZ: 342
+        property real headerZ: 341
+        property real footerZ: 340
+        property real highlightZ: 339
+        property real sectionZ: 338
+
+        anchors.fill: parent
+        objectName: "list"
+        model: ListModel { ListElement { text: "text" } }
+        currentIndex: 0
+
+        delegate: Text {
+            objectName: "wrapper"
+            font.pointSize: 20
+            text: index
+            z: list.itemZ
+        }
+
+        header: Rectangle {
+            width: 240
+            height: 30
+            z: list.headerZ
+        }
+
+        footer: Rectangle {
+            width: 240
+            height: 30
+            z: list.footerZ
+        }
+
+        highlight: Rectangle {
+            width: 240
+            height: 30
+            z: list.highlightZ
+        }
+
+        section.property: "text"
+        section.delegate: Text {
+            objectName: "section"
+            font.pointSize: 20
+            text: section
+            z: list.sectionZ
+        }
+    }
+}
+
diff --git a/tests/auto/quick/qquicklistview/data/constantZValues.qml b/tests/auto/quick/qquicklistview/data/constantZValues.qml
new file mode 100644
index 0000000000..48917fed4f
--- /dev/null
+++ b/tests/auto/quick/qquicklistview/data/constantZValues.qml
@@ -0,0 +1,55 @@
+import QtQuick 2.0
+
+Rectangle {
+    width: 240
+    height: 320
+
+    ListView {
+        id: list
+
+        property real itemZ: 241
+        property real headerZ: 242
+        property real footerZ: 243
+        property real highlightZ: 244
+        property real sectionZ: 245
+
+        anchors.fill: parent
+        objectName: "list"
+        model: ListModel { ListElement { text: "text" } }
+        currentIndex: 0
+
+        delegate: Text {
+            objectName: "wrapper"
+            font.pointSize: 20
+            text: index
+            z: 241
+        }
+
+        header: Rectangle {
+            width: 240
+            height: 30
+            z: 242
+        }
+
+        footer: Rectangle {
+            width: 240
+            height: 30
+            z: 243
+        }
+
+        highlight: Rectangle {
+            width: 240
+            height: 30
+            z: 244
+        }
+
+        section.property: "text"
+        section.delegate: Text {
+            objectName: "section"
+            font.pointSize: 20
+            text: section
+            z: 245
+        }
+    }
+}
+
diff --git a/tests/auto/quick/qquicklistview/data/defaultZValues.qml b/tests/auto/quick/qquicklistview/data/defaultZValues.qml
new file mode 100644
index 0000000000..7326340ae4
--- /dev/null
+++ b/tests/auto/quick/qquicklistview/data/defaultZValues.qml
@@ -0,0 +1,49 @@
+import QtQuick 2.0
+
+Rectangle {
+    width: 240
+    height: 320
+
+    ListView {
+        id: list
+
+        property real itemZ: 1
+        property real headerZ: 1
+        property real footerZ: 1
+        property real highlightZ: 0
+        property real sectionZ: 2
+
+        anchors.fill: parent
+        objectName: "list"
+        model: ListModel { ListElement { text: "text" } }
+        currentIndex: 0
+
+        delegate: Text {
+            objectName: "wrapper"
+            font.pointSize: 20
+            text: index
+        }
+
+        header: Rectangle {
+            width: 240
+            height: 30
+        }
+
+        footer: Rectangle {
+            width: 240
+            height: 30
+        }
+
+        highlight: Rectangle {
+            width: 240
+            height: 30
+        }
+
+        section.property: "text"
+        section.delegate: Text {
+            objectName: "section"
+            font.pointSize: 20
+            text: section
+        }
+    }
+}
diff --git a/tests/auto/quick/qquicklistview/data/initialZValues.qml b/tests/auto/quick/qquicklistview/data/initialZValues.qml
deleted file mode 100644
index 3a8e78debb..0000000000
--- a/tests/auto/quick/qquicklistview/data/initialZValues.qml
+++ /dev/null
@@ -1,35 +0,0 @@
-import QtQuick 2.0
-
-Rectangle {
-    width: 240
-    height: 320
-
-    ListView {
-        id: list
-
-        property real initialZ: 342
-
-        anchors.fill: parent
-        objectName: "list"
-        model: ListModel {}
-
-        delegate: Text {
-            objectName: "wrapper"
-            font.pointSize: 20
-            text: index
-        }
-
-        header: Rectangle {
-            width: 240
-            height: 30
-            z: list.initialZ
-        }
-
-        footer: Rectangle {
-            width: 240
-            height: 30
-            z: list.initialZ
-        }
-    }
-}
-
diff --git a/tests/auto/quick/qquicklistview/tst_qquicklistview.cpp b/tests/auto/quick/qquicklistview/tst_qquicklistview.cpp
index efd0fa8103..60c2fadb23 100644
--- a/tests/auto/quick/qquicklistview/tst_qquicklistview.cpp
+++ b/tests/auto/quick/qquicklistview/tst_qquicklistview.cpp
@@ -147,6 +147,7 @@ private slots:
     void modelChanges();
     void manualHighlight();
     void initialZValues();
+    void initialZValues_data();
     void header();
     void header_data();
     void header_delayItemCreation();
@@ -3465,8 +3466,9 @@ void tst_QQuickListView::QTBUG_11105()
 
 void tst_QQuickListView::initialZValues()
 {
+    QFETCH(QString, fileName);
     QQuickView *window = createView();
-    window->setSource(testFileUrl("initialZValues.qml"));
+    window->setSource(testFileUrl(fileName));
     qApp->processEvents();
 
     QQuickListView *listview = findItem<QQuickListView>(window->rootObject(), "list");
@@ -3474,15 +3476,33 @@ void tst_QQuickListView::initialZValues()
     QQuickItem *contentItem = listview->contentItem();
     QTRY_VERIFY(contentItem != 0);
 
+    QVERIFY(listview->currentItem());
+    QTRY_COMPARE(listview->currentItem()->z(), listview->property("itemZ").toReal());
+
     QVERIFY(listview->headerItem());
-    QTRY_COMPARE(listview->headerItem()->z(), listview->property("initialZ").toReal());
+    QTRY_COMPARE(listview->headerItem()->z(), listview->property("headerZ").toReal());
 
     QVERIFY(listview->footerItem());
-    QTRY_COMPARE(listview->footerItem()->z(), listview->property("initialZ").toReal());
+    QTRY_COMPARE(listview->footerItem()->z(), listview->property("footerZ").toReal());
+
+    QVERIFY(listview->highlightItem());
+    QTRY_COMPARE(listview->highlightItem()->z(), listview->property("highlightZ").toReal());
+
+    QQuickText *sectionItem = 0;
+    QTRY_VERIFY(sectionItem = findItem<QQuickText>(contentItem, "section"));
+    QTRY_COMPARE(sectionItem->z(), listview->property("sectionZ").toReal());
 
     delete window;
 }
 
+void tst_QQuickListView::initialZValues_data()
+{
+    QTest::addColumn<QString>("fileName");
+    QTest::newRow("defaults") << "defaultZValues.qml";
+    QTest::newRow("constants") << "constantZValues.qml";
+    QTest::newRow("bindings") << "boundZValues.qml";
+}
+
 void tst_QQuickListView::header()
 {
     QFETCH(QQuickListView::Orientation, orientation);