Doc: explain ListView default Z values in detail

This should save users some time when they are trying to figure
out why the delegate items are rendered underneath the header when
headerPositioning is set to ListView.OverlayHeader, for example.

Task-number: QTBUG-61346
Change-Id: I490250f2a64a8bbda463b3a31be6f820d0cfe881
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>
Reviewed-by: Robin Burchell <robin.burchell@crimson.no>

1 files changed, 55 insertions, 7 deletions

diff --git a/src/quick/items/qquicklistview.cpp b/src/quick/items/qquicklistview.cpp
index 18f9b8512d..979a3557a1 100644
--- a/src/quick/items/qquicklistview.cpp
+++ b/src/quick/items/qquicklistview.cpp
@@ -1835,6 +1835,38 @@ bool QQuickListViewPrivate::flick(AxisData &data, qreal minExtent, qreal maxExte
 
     \snippet qml/listview/listview.qml flickBothDirections
 
+    \section1 Stacking Order in ListView
+
+    The \l {QQuickItem::z}{Z value} of items determines whether they are
+    rendered above or below other items. ListView uses several different
+    default Z values, depending on what type of item is being created:
+
+    \table
+    \header
+        \li Property
+        \li Default Z value
+    \row
+        \li \l delegate
+        \li 1
+    \row
+        \li \l footer
+        \li 1
+    \row
+        \li \l header
+        \li 1
+    \row
+        \li \l highlight
+        \li 0
+    \row
+        \li \l section.delegate
+        \li 2
+    \endtable
+
+    These default values are set if the Z value of the item is \c 0, so setting
+    the Z value of these items to \c 0 has no effect. Note that the Z value is
+    of type \l [QML] {real}, so it is possible to set fractional
+    values like \c 0.1.
+
     \sa {QML Data Models}, GridView, PathView, {Qt Quick Examples - Views}
 */
 QQuickListView::QQuickListView(QQuickItem *parent)
@@ -1963,6 +1995,8 @@ QQuickListView::~QQuickListView()
     \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.
+
+    \sa {Stacking Order in ListView}
 */
 /*!
     \qmlproperty int QtQuick::ListView::currentIndex
@@ -1990,7 +2024,7 @@ QQuickListView::~QQuickListView()
   The default \l {QQuickItem::z}{stacking order}
   of the highlight item is \c 0.
 
-  \sa highlight, highlightFollowsCurrentItem
+  \sa highlight, highlightFollowsCurrentItem, {Stacking Order in ListView}
 */
 
 /*!
@@ -2009,7 +2043,8 @@ QQuickListView::~QQuickListView()
     highlight item is \c 0.
 
     \sa highlightItem, highlightFollowsCurrentItem,
-    {Qt Quick Examples - Views#Highlight}{ListView highlight example}
+    {Qt Quick Examples - Views#Highlight}{ListView highlight example},
+    {Stacking Order in ListView}
 */
 
 /*!
@@ -2352,7 +2387,8 @@ void QQuickListView::setOrientation(QQuickListView::Orientation orientation)
     differing sections will result in a section header being created
     even if that section exists elsewhere.
 
-    \sa {Qt Quick Examples - Views}{ListView examples}
+    \sa {Qt Quick Examples - Views}{ListView examples},
+    {Stacking Order in ListView}
 */
 QQuickViewSection *QQuickListView::sectionCriteria()
 {
@@ -2503,7 +2539,7 @@ void QQuickListView::setSnapMode(SnapMode mode)
     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
+    \sa header, footerItem, {Stacking Order in ListView}
 */
 
 
@@ -2515,7 +2551,7 @@ void QQuickListView::setSnapMode(SnapMode mode)
     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
+    \sa footer, headerItem, {Stacking Order in ListView}
 */
 
 /*!
@@ -2526,7 +2562,7 @@ void QQuickListView::setSnapMode(SnapMode mode)
     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
+    \sa header, footerItem, {Stacking Order in ListView}
 */
 
 /*!
@@ -2537,7 +2573,7 @@ void QQuickListView::setSnapMode(SnapMode mode)
     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
+    \sa footer, headerItem, {Stacking Order in ListView}
 */
 
 /*!
@@ -2555,6 +2591,12 @@ void QQuickListView::setSnapMode(SnapMode mode)
     The header can be pushed away by moving the content forwards, and pulled back by
     moving the content backwards.
     \endlist
+
+    \note This property has no effect on the \l {QQuickItem::z}{stacking order}
+    of the header. For example, if the header should be shown above the
+    \l delegate items when using \c ListView.OverlayHeader, its Z value
+    should be set to a value higher than that of the delegates. For more
+    information, see \l {Stacking Order in ListView}.
 */
 QQuickListView::HeaderPositioning QQuickListView::headerPositioning() const
 {
@@ -2592,6 +2634,12 @@ void QQuickListView::setHeaderPositioning(QQuickListView::HeaderPositioning posi
     The footer can be pushed away by moving the content backwards, and pulled back by
     moving the content forwards.
     \endlist
+
+    \note This property has no effect on the \l {QQuickItem::z}{stacking order}
+    of the footer. For example, if the footer should be shown above the
+    \l delegate items when using \c ListView.OverlayFooter, its Z value
+    should be set to a value higher than that of the delegates. For more
+    information, see \l {Stacking Order in ListView}.
 */
 QQuickListView::FooterPositioning QQuickListView::footerPositioning() const
 {