Add note to QQuickItem docs about directly setting properties in C++.

It's not obvious that calling setPosition() directly, for example,
won't trigger animations defined in behaviors that react to that
item's x and y properties changing, because a quick glance at the
code shows that they have almost identical code paths and both
emit geometryChanged().

Change-Id: Ic7f7019b1bbba24732569c0de777ee02d79c1d3b
Reviewed-by: Gunnar Sletta <gunnar@sletta.org>

1 files changed, 13 insertions, 0 deletions

diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index a1376682af..0fb8d0e2f8 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -1749,6 +1749,19 @@ void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus)
     surface. Using scene graph API directly is always significantly
     faster.
 
+    \section1 Behavior Animations
+
+    If your Item uses the \l Behavior type to define animations for property
+    changes, you should always use either QObject::setProperty(),
+    QQmlProperty(), or QMetaProperty::write() when you need to modify those
+    properties from C++. This ensures that the QML engine knows about the
+    property change. Otherwise, the engine won't be able to carry out your
+    requested animation. For example, if you call \l setPosition() directly,
+    any behavior that reacts to changes in the x or y properties will not take
+    effect, as you are bypassing Qt's meta-object system. Note that these
+    functions incur a slight performance penalty. For more details, see
+    \l {Accessing Members of a QML Object Type from C++}.
+
     \sa QQuickWindow, QQuickPaintedItem
 */