Docs - clarify use of PropertyChanges for immediate property changes in

a State (e.g. for setting a transformOrigin for a RotationAnimation).
Also improve some other animation docs in general.

2 files changed, 167 insertions, 121 deletions

diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp
index 3b8cb37..4e9e8d5 100644
--- a/src/declarative/util/qdeclarativeanimation.cpp
+++ b/src/declarative/util/qdeclarativeanimation.cpp
@@ -694,9 +694,12 @@ QDeclarativeColorAnimation::~QDeclarativeColorAnimation()
     }
     \endqml
 
-    If this value is not set and the ColorAnimation is defined within
-    a \l Transition, it defaults to the value defined in the starting 
-    state of the \l Transition.
+    If the ColorAnimation is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the starting state of the
+    \l Transition, or the current value of the property at the moment the 
+    \l Behavior is triggered.
+
+    \sa {QML Animation}
 */
 QColor QDeclarativeColorAnimation::from() const
 {
@@ -714,9 +717,12 @@ void QDeclarativeColorAnimation::setFrom(const QColor &f)
 
     This property holds the color value at which the animation should end.
 
-    If this value is not set and the ColorAnimation is defined within
-    a \l Transition or \l Behavior, it defaults to the value defined in the end 
-    state of the \l Transition or \l Behavior.
+    If the ColorAnimation is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the end state of the
+    \l Transition, or the value of the property change that triggered the
+    \l Behavior.
+
+    \sa {QML Animation}
 */
 QColor QDeclarativeColorAnimation::to() const
 {
@@ -887,29 +893,45 @@ QAbstractAnimation *QDeclarativeScriptAction::qtAnimation()
     \inherits Animation
     \brief The PropertyAction element allows immediate property changes during animation.
 
-    PropertyAction is used to specify an immediate property change
-    during an animation. The property change is not animated.
+    PropertyAction is used to specify an immediate property change during an 
+    animation. The property change is not animated.
 
-    For example, to explicitly set \c {theImage.smooth = true} during a \l Transition:
-    \code
-    transitions: Transition {
-        ...
-        PropertyAction { target: theImage; property: "smooth"; value: true }
-        ...
-    }
-    \endcode
+    It is useful for setting non-animated property values during an animation.
 
-    Or, to set \c theWebView.url to the value set for the destination state:
-    \code
+    For example, here is a SequentialAnimation that sets the image's
+    \l {Image::}{smooth} property to \c true, animates the width of the image,
+    then sets \l {Image::}{smooth} back to \c false:
+
+    \snippet doc/src/snippets/declarative/propertyaction.qml standalone
+
+    PropertyAction is also useful for setting the exact point at which a property 
+    change should occur during a \l Transition. For example, if PropertyChanges 
+    was used in a \l State to rotate an item around a particular 
+    \l {Item::}{transformOrigin}, it might be implemented like this:
+
+    \snippet doc/src/snippets/declarative/propertyaction.qml transition
+
+    However, with this code, the \c transformOrigin is not set until \e after
+    the animation, as a \l State is taken to define the values at the \e end of
+    a transition. The animation would rotate at the default \c transformOrigin,
+    then jump to \c Item.BottomRight. To fix this, insert a PropertyChanges 
+    before the RotationAnimation begins:
+
+    \qml
     transitions: Transition {
-        ...
-        PropertyAction { target: theWebView; property: "url" }
-        ...
+        SequentialAnimation {
+            PropertyAction { target: rect; property: "transformOrigin" }
+            RotationAnimation { ... }
+        }
     }
-    \endcode
-
+    \endqml
+    
+    This immediately sets the \c transformOrigin property to the value defined
+    in the end state of the \l Transition (i.e. the value defined in the 
+    PropertyChanges object) so that the rotation animation begins with the
+    correct transform origin.
 
-    \sa QtDeclarative
+    \sa {QML Animation}, QtDeclarative
 */
 /*!
     \internal
@@ -1014,7 +1036,11 @@ QDeclarativeListProperty<QObject> QDeclarativePropertyAction::exclude()
 /*!
     \qmlproperty any PropertyAction::value
     This property holds the value to be set on the property.
-    If not set, then the value defined for the end state of the transition.
+
+    If the PropertyAction is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the end state of the
+    \l Transition, or the value of the property change that triggered the
+    \l Behavior.
 */
 QVariant QDeclarativePropertyAction::value() const
 {
@@ -1190,7 +1216,7 @@ void QDeclarativeNumberAnimation::init()
 
 /*!
     \qmlproperty real NumberAnimation::from
-    This property holds the starting number value.
+    This property holds the starting value for the animation.
 
     For example, the following animation is not applied until the \c x value
     has reached 100:
@@ -1205,9 +1231,12 @@ void QDeclarativeNumberAnimation::init()
     }
     \endqml
 
-    If this value is not set and the NumberAnimation is defined within
-    a \l Transition, it defaults to the value defined in the start 
-    state of the \l Transition.
+    If the NumberAnimation is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the starting state of the
+    \l Transition, or the current value of the property at the moment the 
+    \l Behavior is triggered.
+
+    \sa {QML Animation}
 */
 
 qreal QDeclarativeNumberAnimation::from() const
@@ -1223,11 +1252,14 @@ void QDeclarativeNumberAnimation::setFrom(qreal f)
 
 /*!
     \qmlproperty real NumberAnimation::to
-    This property holds the ending number value.
+    This property holds the end value for the animation.
 
-    If this value is not set and the NumberAnimation is defined within
-    a \l Transition or \l Behavior, it defaults to the value defined in the end 
-    state of the \l Transition or \l Behavior.
+    If the NumberAnimation is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the end state of the
+    \l Transition, or the value of the property change that triggered the
+    \l Behavior.
+
+    \sa {QML Animation}
 */
 qreal QDeclarativeNumberAnimation::to() const
 {
@@ -1280,10 +1312,14 @@ QDeclarativeVector3dAnimation::~QDeclarativeVector3dAnimation()
 
 /*!
     \qmlproperty real Vector3dAnimation::from
-    This property holds the starting value.
+    This property holds the starting value for the animation.
+
+    If the Vector3dAnimation is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the starting state of the
+    \l Transition, or the current value of the property at the moment the 
+    \l Behavior is triggered.
 
-    If this value is not set, it defaults to the value defined in the start 
-    state of the \l Transition.
+    \sa {QML Animation}
 */
 QVector3D QDeclarativeVector3dAnimation::from() const
 {
@@ -1298,10 +1334,14 @@ void QDeclarativeVector3dAnimation::setFrom(QVector3D f)
 
 /*!
     \qmlproperty real Vector3dAnimation::to
-    This property holds the ending value.
+    This property holds the end value for the animation.
 
-    If this value is not set, it defaults to the value defined in the end 
-    state of the \l Transition or \l Behavior.
+    If the Vector3dAnimation is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the end state of the
+    \l Transition, or the value of the property change that triggered the
+    \l Behavior.
+
+    \sa {QML Animation}
 */
 QVector3D QDeclarativeVector3dAnimation::to() const
 {
@@ -1343,6 +1383,12 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t)
     your own properties via \l {PropertyAnimation::properties}{properties} or 
     \l {PropertyAnimation::property}{property}.
 
+    Also, note the \l Rectangle will be rotated around its default
+    \l {Item::}{transformOrigin} (which is \c Item.Center). To use a different
+    transform origin, set the origin in the PropertyChanges object and apply
+    the change at the start of the animation using PropertyAction. See the
+    PropertyAction documentation for more details.
+
     Like any other animation element, a RotationAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
     sources. The \l {QML Animation} documentation shows a variety of methods
@@ -1408,7 +1454,7 @@ QDeclarativeRotationAnimation::~QDeclarativeRotationAnimation()
 
 /*!
     \qmlproperty real RotationAnimation::from
-    This property holds the starting number value.
+    This property holds the starting value for the animation.
 
     For example, the following animation is not applied until the \c angle value
     has reached 100:
@@ -1423,8 +1469,12 @@ QDeclarativeRotationAnimation::~QDeclarativeRotationAnimation()
     }
     \endqml
 
-    If this value is not set, it defaults to the value defined in the start 
-    state of the \l Transition.
+    If the RotationAnimation is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the starting state of the
+    \l Transition, or the current value of the property at the moment the 
+    \l Behavior is triggered.
+
+    \sa {QML Animation}
 */
 qreal QDeclarativeRotationAnimation::from() const
 {
@@ -1439,10 +1489,14 @@ void QDeclarativeRotationAnimation::setFrom(qreal f)
 
 /*!
     \qmlproperty real RotationAnimation::to
-    This property holds the ending value.
+    This property holds the end value for the animation..
+
+    If the RotationAnimation is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the end state of the
+    \l Transition, or the value of the property change that triggered the
+    \l Behavior.
 
-    If this value is not set, it defaults to the value defined in the end 
-    state of the \l Transition or \l Behavior.
+    \sa {QML Animation}
 */
 qreal QDeclarativeRotationAnimation::to() const
 {
@@ -1854,8 +1908,14 @@ void QDeclarativePropertyAnimation::setDuration(int duration)
 
 /*!
     \qmlproperty real PropertyAnimation::from
-    This property holds the starting value.
-    If not set, then the value defined in the start state of the transition.
+    This property holds the starting value for the animation.
+
+    If the PropertyAnimation is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the starting state of the
+    \l Transition, or the current value of the property at the moment the 
+    \l Behavior is triggered.
+
+    \sa {QML Animation}
 */
 QVariant QDeclarativePropertyAnimation::from() const
 {
@@ -1875,8 +1935,14 @@ void QDeclarativePropertyAnimation::setFrom(const QVariant &f)
 
 /*!
     \qmlproperty real PropertyAnimation::to
-    This property holds the ending value.
-    If not set, then the value defined in the end state of the transition or \l Behavior.
+    This property holds the end value for the animation.
+
+    If the PropertyAnimation is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the end state of the
+    \l Transition, or the value of the property change that triggered the
+    \l Behavior.
+
+    \sa {QML Animation}
 */
 QVariant QDeclarativePropertyAnimation::to() const
 {
@@ -2502,7 +2568,10 @@ void QDeclarativeParentAnimation::setTarget(QDeclarativeItem *target)
     \qmlproperty Item ParentAnimation::newParent
     The new parent to animate to.
 
-    If not set, then the parent defined in the end state of the transition.
+    If the ParentAnimation is defined within a \l Transition or \l Behavior,
+    this value defaults to the value defined in the end state of the
+    \l Transition, or the value of the property change that triggered the
+    \l Behavior.
 */
 QDeclarativeItem *QDeclarativeParentAnimation::newParent() const
 {
diff --git a/src/declarative/util/qdeclarativepropertychanges.cpp b/src/declarative/util/qdeclarativepropertychanges.cpp
index 25edd35..c28ada3 100644
--- a/src/declarative/util/qdeclarativepropertychanges.cpp
+++ b/src/declarative/util/qdeclarativepropertychanges.cpp
@@ -65,48 +65,30 @@ QT_BEGIN_NAMESPACE
     \since 4.7
     \brief The PropertyChanges element describes new property bindings or values for a state.
 
-    PropertyChanges provides a state change that modifies the properties of an item.
+    PropertyChanges is used to define the property values or bindings in a 
+    \l State. This enables an item's property values to be changed when it
+    \l {QML States}{changes between states}.
 
-    Here is a property change that modifies the text and color of a \l Text element
-    when it is clicked:
+    To create a PropertyChanges object, specify the \l target item whose 
+    properties are to be modified, and define the new property values or
+    bindings. For example:
     
-    \qml
-    Text {
-        id: myText
-        width: 100; height: 100
-        text: "Hello"
-        color: "blue"
-
-        states: State {
-            name: "myState"
-
-            PropertyChanges {
-                target: myText
-                text: "Goodbye"
-                color: "red"
-            }
-        }
-
-        MouseArea { anchors.fill: parent; onClicked: myText.state = 'myState' }
-    }
-    \endqml
-
-    By default, PropertyChanges will establish new bindings where appropriate.
-    For example, the following creates a new binding for myItem's \c height property.
-
-    \qml
-    PropertyChanges {
-        target: myItem
-        height: parent.height
-    }
-    \endqml
-
-    If you don't want a binding to be established (and instead just want to assign
-    the value of the binding at the time the state is entered),
-    you should set the PropertyChange's \l{PropertyChanges::explicit}{explicit}
+    \snippet doc/src/snippets/declarative/propertychanges.qml import 
+    \codeline
+    \snippet doc/src/snippets/declarative/propertychanges.qml 0
+
+    When the mouse is pressed, the \l Rectangle changes to the \e resized
+    state. In this state, the PropertyChanges object sets the rectangle's 
+    color to blue and the \c height value to that of \c container.height.
+
+    Note this automatically binds \c rect.height to \c container.height 
+    in the \e resized state. If a property binding should not be
+    established, and the height should just be set to the value of
+    \c container.height at the time of the state change, set the \l explicit
     property to \c true.
-    
-    State-specific script for signal handlers can also be specified:
+   
+    A PropertyChanges object can also override the default signal handler
+    for an object to implement a signal handler specific to the new state:
 
     \qml
     PropertyChanges {
@@ -115,36 +97,31 @@ QT_BEGIN_NAMESPACE
     }
     \endqml
 
-    You can reset a property in a state change by assigning \c undefined. In the following
-    example we reset \c theText's width when we enter state1. This will give the text its
-    natural width (which is the whole string on one line).
+    \note PropertyChanges can be used to change anchor margins, but not other anchor
+    values; use AnchorChanges for this instead. Similarly, to change an \l Item's
+    \l {Item::}{parent} value, use ParentChanges instead.
 
-    \qml
-    import Qt 4.7
-
-    Rectangle {
-        width: 640
-        height: 480
-        Text {
-            id: theText
-            width: 50
-            wrapMode: Text.WordWrap
-            text: "a text string that is longer than 50 pixels"
-        }
 
-        states: State {
-            name: "state1"
-            PropertyChanges {
-                target: theText
-                width: undefined
-            }
-        }
-    }
-    \endqml
+    \section2 Resetting property values
 
-    Anchor margins should be changed with PropertyChanges, but other anchor changes or changes to
-    an Item's parent should be done using the associated change elements
-    (ParentChange and AnchorChanges, respectively).
+    The \c undefined value can be used to reset the property value for a state.
+    In the following example, when \c theText changes to the \e widerText
+    state, its \c width property is reset, giving the text its natural width
+    and displaying the whole string on a single line.
+
+    \snippet doc/src/snippets/declarative/propertychanges.qml reset
+
+
+    \section2 Immediate property changes in transitions
+
+    When \l Transitions are used to animate state changes, they animate 
+    properties from their values in the current state to those defined in the
+    new state (as defined by PropertyChanges objects). However, 
+    it is sometimes desirable to set a property value \e immediately during a 
+    \l Transition, without animation; in these cases, the PropertyAction 
+    element can be used to force an immediate property change.
+
+    See the PropertyAction documentation for more details.
 
     \sa {declarative/animation/states}{states example}, {qmlstate}{States}, QtDeclarative
 */
@@ -397,12 +374,12 @@ void QDeclarativePropertyChanges::setObject(QObject *o)
 
 /*!
     \qmlproperty bool PropertyChanges::restoreEntryValues
-    
-    Whether or not the previous values should be restored when
-    leaving the state. By default, restoreEntryValues is true.
 
-    By setting restoreEntryValues to false, you can create a temporary state
-    that has permanent effects on property values.
+    This property holds whether the previous values should be restored when
+    leaving the state. 
+
+    The default value is \c true. Setting this value to \c false creates a
+    temporary state that has permanent effects on property values.
 */
 bool QDeclarativePropertyChanges::restoreEntryValues() const
 {