doc: Clarify that the delegate populate transition doesn't always run

Fixes: QTBUG-42798
Change-Id: If10f06450f1e50893e5ba103e7c8c2d83667a651
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>

2 files changed, 45 insertions, 2 deletions

diff --git a/src/quick/items/qquickgridview.cpp b/src/quick/items/qquickgridview.cpp
index 272d4a4df5..dd45211115 100644
--- a/src/quick/items/qquickgridview.cpp
+++ b/src/quick/items/qquickgridview.cpp
@@ -1758,7 +1758,7 @@ void QQuickGridView::setSnapMode(SnapMode mode)
 
     \list
     \li The view is first created
-    \li The view's \l model changes
+    \li The view's \l model changes in such a way that the visible delegates are completely replaced
     \li The view's \l model is \l {QAbstractItemModel::reset()}{reset}, if the model is a QAbstractItemModel subclass
     \endlist
 
@@ -1776,6 +1776,28 @@ void QQuickGridView::setSnapMode(SnapMode mode)
     When the view is initialized, the view will create all the necessary items for the view,
     then animate them to their correct positions within the view over one second.
 
+    However when scrolling the view later, the populate transition does not
+    run, even though delegates are being instantiated as they become visible.
+    When the model changes in a way that new delegates become visible, the
+    \l add transition is the one that runs. So you should not depend on the
+    \c populate transition to initialize properties in the delegate, because it
+    does not apply to every delegate. If your animation sets the \c to value of
+    a property, the property should initially have the \c to value, and the
+    animation should set the \c from value in case it is animated:
+
+    \code
+    GridView {
+        ...
+        delegate: Rectangle {
+            opacity: 1 // not necessary because it's the default; but don't set 0
+            ...
+        }
+        populate: Transition {
+            NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 1000 }
+        }
+    }
+    \endcode
+
     For more details and examples on how to use view transitions, see the ViewTransition
     documentation.
 
diff --git a/src/quick/items/qquicklistview.cpp b/src/quick/items/qquicklistview.cpp
index 75a24c7d76..c4c22526f3 100644
--- a/src/quick/items/qquicklistview.cpp
+++ b/src/quick/items/qquicklistview.cpp
@@ -2724,7 +2724,7 @@ void QQuickListView::setFooterPositioning(QQuickListView::FooterPositioning posi
 
     \list
     \li The view is first created
-    \li The view's \l model changes
+    \li The view's \l model changes in such a way that the visible delegates are completely replaced
     \li The view's \l model is \l {QAbstractItemModel::reset()}{reset}, if the model is a QAbstractItemModel subclass
     \endlist
 
@@ -2742,6 +2742,27 @@ void QQuickListView::setFooterPositioning(QQuickListView::FooterPositioning posi
     When the view is initialized, the view will create all the necessary items for the view,
     then animate them to their correct positions within the view over one second.
 
+    However when scrolling the view later, the populate transition does not
+    run, even though delegates are being instantiated as they become visible.
+    When the model changes in a way that new delegates become visible, the
+    \l add transition is the one that runs. So you should not depend on the
+    \c populate transition to initialize properties in the delegate, because it
+    does not apply to every delegate. If your animation sets the \c to value of
+    a property, the property should initially have the \c to value, and the
+    animation should set the \c from value in case it is animated:
+
+    \code
+    ListView {
+        ...
+        delegate: Rectangle {
+            opacity: 1 // not necessary because it's the default
+        }
+        populate: Transition {
+            NumberAnimation { property: "opacity"; from: 0; to: 1; duration: 1000 }
+        }
+    }
+    \endcode
+
     For more details and examples on how to use view transitions, see the ViewTransition
     documentation.