Document state fast-forwarding.

Task-number: QTBUG-16049

Change-Id: Ib64cc8ec9396d426e623481a69f5a4a1b0fe5ec5
Reviewed-on: http://codereview.qt.nokia.com/2370
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Bea Lam <bea.lam@nokia.com>

diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc
index 55f38c3..9857894 100644 (file)
--- a/doc/src/declarative/qdeclarativestates.qdoc
+++ b/doc/src/declarative/qdeclarativestates.qdoc
@@ -133,4 +133,26 @@ The \l {declarative/animation/states}{States and Transitions example}
 demonstrates how to declare a basic set of states and apply animated
 transitions between them.
 
+\l{Using QML Behaviors with States} explains a common problem when using Behaviors
+to animate state changes.
+
+\section1 State Fast Forwarding
+
+In order for Transition to correctly animate state changes, it is sometimes necessary
+for the engine to fast forward and rewind a state (that is, internally set and unset the state)
+before it is finally applied. The process is as follows:
+
+\list 1
+\o The state is fast forwarded to determine the complete set of end values.
+\o The state is rewound.
+\o The state is fully applied, with transitions.
+\endlist
+
+In some cases this may cause unintended behavior. For example, a state that changes
+a view's \i model or a Loader's \i sourceComponent will set these properties
+multiple times (to apply, rewind, and then reapply), which can be relatively expensive.
+
+State fast forwarding should be considered an implementation detail,
+and may change in later versions.
+
 */