doc, listview: document that binding to parent should be avoided

Clearify in the documentation that the parent of a delegate
can change during its lifetime, and even be null. And because
of that, they should avoid binding to it.

In general, how a control is structured internally should be
understood as a private implementation detail. Even if the
application has the freedom to read (and even change) the
internal parent-child hierarchy as it sees fit, doing so
can be fragile as the internal structure of a control
can easily change from one version to the other.

[ChangeLog][QtQuick][ListView] Since the parent of a delegate can
end up being null during its lifetime, developers are
now advised against using it in bindings.

Fixes: QTBUG-82989
Change-Id: I2d6c79102435d0969f4dc3deec13c5fff4affeb1
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
(cherry picked from commit ed73efa27acd8e7c42a960ef90c2e4a898c20c30)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

1 files changed, 24 insertions, 2 deletions

diff --git a/src/quick/items/qquicklistview.cpp b/src/quick/items/qquicklistview.cpp
index 9b72e13bd9..9dd85ded19 100644
--- a/src/quick/items/qquicklistview.cpp
+++ b/src/quick/items/qquicklistview.cpp
@@ -1967,8 +1967,30 @@ QQuickItemViewAttached *QQuickListViewPrivate::getAttachedObject(const QObject *
     The list view itself is a focus scope (see \l{Keyboard Focus in Qt Quick} for more details).
 
     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.
+    As such, state should \e never be stored in a delegate.
+    Delegates are usually parented to ListView's \l {Flickable::contentItem}{contentItem}, but
+    typically depending on whether it's visible in the view or not, the \l parent
+    can change, and sometimes be \c null. Because of that, binding to
+    the parent's properties from within the delegate is \i not recommended. If you
+    want the delegate to fill out the width of the ListView, consider
+    using one of the following approaches instead:
+
+    \code
+    ListView {
+        id: listView
+        // ...
+
+        delegate: Item {
+            // Incorrect.
+            width: parent.width
+
+            // Correct.
+            width: listView.width
+            width: ListView.view.width
+            // ...
+        }
+    }
+    \endcode
 
     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