1 files changed, 23 insertions, 1 deletions
diff --git a/src/quick/items/qquickgridview.cpp b/src/quick/items/qquickgridview.cpp
index fecfa5fd2d..e69e9cff46 100644
--- a/src/quick/items/qquickgridview.cpp
+++ b/src/quick/items/qquickgridview.cpp
@@ -1761,7 +1761,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
 
@@ -1779,6 +1779,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.