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.

5 files changed, 273 insertions, 129 deletions

diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc
index 7416341..53a0c55 100644
--- a/doc/src/declarative/animation.qdoc
+++ b/doc/src/declarative/animation.qdoc
@@ -156,11 +156,13 @@ The \l {PropertyAnimation::}{to} property is also required to specify the new
 \section2 Standalone Animations
 
 Animations can also be created as ordinary QML objects that are not bound to
-any particular objects and properties. An example:
+any particular objects and properties. Here is an example, using a 
+PropertyAnimation object. The animation is explicitly started when the 
+\l Rectangle is clicked:
 
 \snippet doc/src/snippets/declarative/animation-standalone.qml 0
 
-A standalone animation is not running by default and must be started explicitly
+A standalone animation object is not running by default and must be started explicitly
 using the \l {Animation::}{running} property or \l {Animation::}{start()} and
 \l {Animation::}{stop()} methods. Since the animation is not bound to a
 particular object or property, it must define the \l
@@ -183,10 +185,13 @@ object and add it to an item's \l {Item::}{transitions} property. An example:
 
 \snippet doc/src/snippets/declarative/animation-transitions.qml 0
 
-When the \l Rectangle changes to the \e moved state, its \c x and \c y property
-values are changed by the PropertyChanges object, and the PropertyAnimation
-defined within the \l Transition is triggered on these properties. The
-animation will not be applied at any time other than during the state change.
+The PropertyChanges object in the \e moved state defines that when the
+\l Rectangle is in this state, its position should be changed
+to (50, 50). When the \l Rectangle changes to the \e moved state, the 
+\l Transition will be triggered, and the transition's \l PropertyAnimation will
+animate the changes in the \c x and \c y properties to their new values.
+The animation will not be applied at any time other than during the state 
+change.
 
 Notice the example does not set any \l {PropertyAnimation::}{from} and \l
 {PropertyAnimation::}{to} values for the PropertyAnimation. As a convenience,
@@ -234,7 +239,7 @@ and rotation changes.
 
 A ColorAnimation allows color values for the \l {ColorAnimation::}{from} 
 and \l {ColorAnimation::}{to} properties. The
-following animates the rectangle's \l {Rectangle::color} property:
+following animates the rectangle's \l {Rectangle::}{color} property:
 
 \snippet doc/src/snippets/declarative/animation-elements.qml color
 
diff --git a/doc/src/snippets/declarative/propertychanges.qml b/doc/src/snippets/declarative/propertychanges.qml
new file mode 100644
index 0000000..9f119bf
--- /dev/null
+++ b/doc/src/snippets/declarative/propertychanges.qml
@@ -0,0 +1,92 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//![import]
+import Qt 4.7
+//![import]
+
+Column {
+
+//![0]
+Item {
+    id: container
+    width: 300; height: 300
+
+    Rectangle {
+        id: rect
+        width: 100; height: 100
+        color: "red"
+
+        MouseArea { 
+           id: mouseArea
+           anchors.fill: parent 
+        }
+
+        states: State {
+           name: "resized"; when: mouseArea.pressed
+           PropertyChanges { target: rect; color: "blue"; height: container.height }
+        }
+    }
+}
+//![0]
+
+//![reset]
+Rectangle {
+    width: 300; height: 200
+
+    Text {
+        id: myText
+        width: 50
+        wrapMode: Text.WordWrap
+        text: "a text string that is longer than 50 pixels"
+
+        states: State {
+            name: "widerText"
+            PropertyChanges { target: myText; width: undefined }
+        }
+    }
+
+    MouseArea {
+        anchors.fill: parent
+        onClicked: myText.state = "widerText"
+    }
+}
+//![reset]
+}
diff --git a/doc/src/snippets/declarative/rotationanimation.qml b/doc/src/snippets/declarative/rotationanimation.qml
index c81395a..b56cb3f 100644
--- a/doc/src/snippets/declarative/rotationanimation.qml
+++ b/doc/src/snippets/declarative/rotationanimation.qml
@@ -52,7 +52,8 @@ Item {
         smooth: true
 
         states: State { 
-            name: "rotated"; PropertyChanges { target: rect; rotation: 180 } 
+            name: "rotated"
+            PropertyChanges { target: rect; rotation: 180 } 
         }
 
         transitions: Transition {
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
 {