1 files changed, 22 insertions, 1 deletions
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.