Improve docs on QML Animation page and associated elements

Task-number: QTBUG-12666

18 files changed, 843 insertions, 298 deletions

diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc
index 401cf16..7416341 100644
--- a/doc/src/declarative/animation.qdoc
+++ b/doc/src/declarative/animation.qdoc
@@ -29,134 +29,301 @@
 \page qdeclarativeanimation.html
 \title QML Animation
 
-Animation in QML is done by animating properties of objects. Properties of type
-real, int, color, rect, point, size, and vector3d can all be animated.
 
-QML supports three main forms of animation: basic property animation,
-transitions, and property behaviors.
+In QML, animations are created by applying animation objects to object property
+values to gradually change them over time. Animation objects are created from
+the built-in set of animation elements, which can be used to animate various
+types of property values. In addition, animation objects can be applied in
+different ways depending on the context in which they are required.
+
+To create an animation, use an appropriate animation element for the type of
+the property that is to be animated, and apply the animation depending on the
+type of behavior that is required. This page describes the \l {Types of
+Animations} that can be created and the \l {Animation Elements} that are used
+to create these animations.
+
+
+\section1 Types of Animations
+
+An animation is created in different ways depending on the context in which it
+is required. Suppose a \l Rectangle's movement - that is, changes in its \c x
+or \c y property values - should be animated. The semantics of the animation
+differ depending on whether you want to create:
+
+\list
+\o An animation that moves the \l Rectangle as soon as it is created, to a
+known position
+\o An animation that only triggers when the \l Rectangle is moved by external
+sources - for example, when the mouse is clicked, animate the movement to the
+mouse position
+\o An animation that triggers when a particular signal is received
+\o A standalone animation that is not bound to the \l Rectangle's movement, but
+instead can be started and stopped from script as required
+\o An animation that only triggers during \l{QML States}{state changes}
+\endlist
+
+To support these different types of animation methods, QML provides several
+methods for defining an animation. These are:
+
+\list
+\o Creating an \l{Animations as Property Value Sources}{animation using
+property value sources}, to immediately animate a specific property
+\o Using \l{Behavioral Animations}{behavioral animations}, which are triggered
+when a property changes value
+\o \l{Animations in a Signal Handler}{Within a signal handler}, to be triggered
+when a signal is received
+\o As a \l{Standalone Animation}{standalone animation}, that can be
+started/stopped from script and can be rebound to different objects
+\o Using \l{Transitions}{transitions}, to provide animations between \l{QML
+States}{state changes}
+\endlist
+
+These methods are demonstrated below. Notice these examples use
+PropertyAnimation, which is one of several QML elements that can be used to
+create an animation. See the \l {Animation Elements} section further below for 
+details.
 
-\tableofcontents
 
-\section1 Basic Property Animation
 
-The simplest form of animation is a \l PropertyAnimation, which can animate all of the property
-types listed above. If the property you are animating is a number or color, you can alternatively use
-NumberAnimation or ColorAnimation. These elements don't add any additional functionality,
-but will help enforce type correctness and are slightly more efficient.
+\section2 Animations as Property Value Sources
+
+An animation is applied as a \l{QDeclarativePropertyValueSource}{property value
+source} using the \e Animation \bold on \e Property syntax. Here is a \l
+Rectangle whose movement is animated using this method:
+
+\snippet doc/src/snippets/declarative/animation-propertyvaluesource.qml 0
+	
+This applies a PropertyAnimation to the \l Rectangle's \c x and \c y properties
+to animate from their current values (i.e. zero) to 50, over 1000 milliseconds.
+The animation starts as soon as the \l Rectangle is loaded. To animate from
+specific values rather than the current \c x and \c y values, set the
+PropertyAnimation's \l {PropertyAnimation::}{from} property.
+
+Specifying an animation as a property value source is useful for animating a
+property to a particular value as soon as the object is loaded.
+
+
+\section2 Behavioral Animations
+
+Often an animation should be applied whenever a particular property value
+changes. In these cases, a \l Behavior can be used to specify a default
+animation for a property change. Here is an example:
+
+\snippet doc/src/snippets/declarative/animation-behavioral.qml 0
 
-A property animation can be specified as a value source using the \e Animation \bold on \e property syntax. This is especially useful
-for repeating animations.
+This \l Rectangle has \l Behavior objects applied to its \c x and \c y
+properties. Whenever these properties change (in this case, when the mouse is
+clicked within the parent \l Item), the PropertyAnimation objects defined
+within the behaviors will be applied to these properties, thus animating the \l
+Rectangle's movement to its new position. Unlike the method of \l {Animations
+as Property Value Sources}{defining an animation as a property value source},
+which creates a one-time animation that animates a property to a known value, a
+behavioral animation is an animation that is triggered \e {in response to} a
+value change.
 
-The following example creates a bouncing effect:
-\snippet doc/src/snippets/declarative/animation.qml property-anim-1
+Any changes to these properties will trigger their animations. If \c x or \c y
+were bound to other properties, and those properties changed, the animation
+would be triggered. The \l{Behavior::}{enabled} property can be used to force a
+\l Behavior to only apply under certain circumstances.
 
-\image propanim.gif
+Notice that unlike for property value source animations, the
+PropertyAnimation's \l {PropertyAnimation::}{from} and \l
+{PropertyAnimation::}{to} properties do not need to be defined because these
+values are already provided, respectively, by the \l Rectangle's current values
+and the new values set in the \c onClicked handler. If these properties were
+defined anyway, they would override the default values.
+
+See the \l {declarative/animation/behaviors}{Behaviors example} for a
+demonstration of behavioral animations.
+
+
+\section2 Animations in a Signal Handler
+
+An animation can be created within a signal handler to be triggered when the
+signal is received. For example:
+    
+\snippet doc/src/snippets/declarative/animation-signalhandler.qml 0
+
+The PropertyAnimation is triggered when the MouseArea is clicked, animating the
+\c x and \c y properties to a value of 50 over 1000 milliseconds. Since the
+animation is not bound to a particular object or property, it must define the
+\l {PropertyAnimation::}{target} and \l {PropertyAnimation::}{property} (or \l
+{PropertyAnimation::}{targets} and \l{PropertyAnimation::}{properties}) values.
+The \l {PropertyAnimation::}{to} property is also required to specify the new
+\c x and \c y values.
+
+
+\section2 Standalone Animations
+
+Animations can also be created as ordinary QML objects that are not bound to
+any particular objects and properties. An example:
+
+\snippet doc/src/snippets/declarative/animation-standalone.qml 0
+
+A standalone animation 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
+{PropertyAnimation::}{target} and \l {PropertyAnimation::}{property} (or \l
+{PropertyAnimation::}{targets} and \l{PropertyAnimation::}{properties}) values.
+The \l {PropertyAnimation::}{to} property is also required to specify the new
+\c x and \c y values. (The \l {PropertyAnimation::}{from} value can optionally
+be provided.)
+
+Standalone animations are useful when an animation is not targeted towards a
+single object property and the animation should be explicitly started and
+stopped.
+
+
+\section2 Transitions
 
-When you assign an animation as a value source, you do not need to specify \c property
-or \c target values; they are automatically selected for you. You do, however, need to specify a \c to value.
-An animation specified as a value source will be \c running by default.
+Transitions are used to describe the animations to be applied when a \l {QML
+States}{state change} occurs. To create a transition, define a \l Transition
+object and add it to an item's \l {Item::}{transitions} property. An example:
 
-For example, here is a rectangle that uses a \l NumberAnimation value source to animate the movement
-from its current position to an \c x value of 50. The animation starts immediately, and only the \c to 
-property is required:
+\snippet doc/src/snippets/declarative/animation-transitions.qml 0
 
-\snippet doc/src/snippets/declarative/animation.qml property-anim-2
+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.
 
-A property animation can also be specified as a resource that is manipulated from script.
+Notice the example does not set any \l {PropertyAnimation::}{from} and \l
+{PropertyAnimation::}{to} values for the PropertyAnimation. As a convenience,
+these properties are automatically set to the values of \c x and \c y before
+and after the state change, respectively. However, they can be explicitly set
+if these values should be overrided.
 
-\snippet doc/src/snippets/declarative/animation.qml property-anim-3
+Also notice the PropertyAnimation does not need to specify a \l
+{PropertyAnimation::}{target} object; any \c x or \c y value of any object that
+has changed during the state change will be animated. However, the target can
+be set if the animation should be restricted to certain objects.
 
-As can be seen, when an animation is used like this (as opposed to as a value source) you will need
-to explicitly set the \c target and \c property to animate.  This also the only case where
-an animation needs to be started explictly by either setting the \c running property to
-true or calling the \c start() method.
+The top-level animations in a \l Transition are run in parallel. To run them
+one after the other, use a SequentialAnimation, as shown below in \l {Grouping
+Animations}.
 
-Animations can be joined into a group using SequentialAnimation and ParallelAnimation.
+See the \l Transition documentation for more information.
 
-See the \l {declarative/animation/basics}{Animation basics example} for a demonstration of creating and combining multiple animations in QML.
 
-\target state-transitions
-\section1 Transitions
+\section1 Animation Elements
 
-\l Transition elements describe the animations to perform when \l{qmlstates}{state} changes occur. A transition
-can only be triggered by a state change.
+To create an animation, choose from one of the built-in QML animation elements.
+While the above examples are demonstrated using PropertyAnimation, they could
+have used other elements depending on the type of the property to be animated
+and whether a single or multiple animations are required.
 
-For example, a \l Transition could describe how an item moves from its initial position to its new position:
+All animation elements inherit from the \l Animation element. It is not
+possible to create \l Animation objects; instead, this element provides the
+essential properties and methods for animation elements. For example, it allows
+animations to be started and stopped through the \l {Animation::}{running}
+property and the \l{Animation::}{start()} and \l{Animation::}{stop()} methods.
+It can also define the number of \l {Animation::}{loops} for an animation.
 
-\snippet doc/src/snippets/declarative/animation.qml transitions-1
 
-As can be seen, transitions make use of the same basic animation classes introduced above.
-In the above example we have specified that we want to animate the \c x and \c y properties, but have not
-specified the objects to animate or the \c to values. By default these values are supplied by the framework;
-the animation will animate any \c targets whose \c x and \c y have changed, and the \c to values will be those
-defined in the end state. You can always supply explicit values to override these implicit values when needed.
+\section2 Property Animation Elements
 
-\snippet doc/src/snippets/declarative/animation.qml transitions-2
+PropertyAnimation is the most basic animation element for animating a property.
+It can be used to animate \c real, \c int, \c color, \c rect, \c point, \c size, and
+\c vector3d properties. It is inherited by NumberAnimation, ColorAnimation,
+RotationAnimation and Vector3dAnimation: NumberAnimation provides a more 
+efficient implementation for animating \c real and \c int properties, and 
+Vector3dAnimation does the same for \c vector3d properties.  ColorAnimation 
+and RotationAnimation provide more specific attributes for animating color 
+and rotation changes. 
 
-QML transitions have selectors to determine which state changes a transition should apply to.
-The following transition will only be triggered when we enter into the \c "details" state.
-(The "*" value is a wildcard value that specifies the transition should be applied when changing
-from \e any state to the "details" state.)
+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:
 
-\code
-Transition {
-    from: "*"
-    to: "details"
-    ...
-}
-\endcode
+\snippet doc/src/snippets/declarative/animation-elements.qml color
 
-Transitions can happen in parallel, in sequence, or in any combination of the two. By default, the top-level
-animations in a transition will happen in parallel. The following example shows a rather complex transition
-making use of both sequential and parallel animations:
+RotationAnimation allows a rotation's direction to be specified. The following
+animates the rectangle's \l {Item::rotation} property:
 
-\snippet doc/src/snippets/declarative/animation.qml transitions-3
+\snippet doc/src/snippets/declarative/animation-elements.qml rotation
 
+In addition, the following specialized animation elements are available:
 
-See \l {declarative/animation/states}{States and Transitions example} for a simple example of how transitions can be applied.
+\list
+\o SmoothedAnimation: a specialized NumberAnimation that provides smooth 
+changes in animation when the target value changes
+\o SpringAnimation: provides a spring-like animation with specialized 
+attributes such as \l {SpringAnimation::}{mass}, 
+\l{SpringAnimation::}{damping} and \l{SpringAnimation::}{epsilon}
+\o ParentAnimation: used for animating a parent change (see ParentChange)
+\o AnchorAnimation: used for animating an anchor change (see AnchorChanges)
+\endlist
 
+See their respective documentation pages for more details.
 
-\section1 Property Behaviors
 
-A property \l {Behavior}{behavior} specifies a default animation to run whenever the property's value changes, regardless
-of what caused the change. The \c enabled property can be used to force a \l Behavior
-to only apply under certain circumstances.
+\section3 Easing
+
+Any PropertyAnimation-based animations can specify \l
+{PropertyAnimation::easing.type}{easing attributes} to control the
+easing curve applied when a property value is animated. These control the
+effect of the animation on the property value, to provide visual effects like
+bounce, acceleration and deceleration.
+
+For example, this modified version of an \l {Animations as Property Value
+Sources}{earlier example} uses \c Easing.OutBounce to create a bouncing effect
+when the animation reaches its target value:
+
+\snippet doc/src/snippets/declarative/animation-easing.qml 0
+
+The \l{declarative/animation/easing}{easing example} visually demonstrates each
+of the different easing types.
+
+\section2 Grouping Animations
+
+Multiple animations can be combined into a single animation using one of the
+animation group elements: ParallelAnimation or SequentialAnimation. As their
+names suggest, animations in a ParallelAnimation are run at the same time,
+while animations in a SequentialAnimation are run one after the other.
+
+To run multiple animations, define the animations within an animation group.
+The following example creates a SequentialAnimation that runs three animations
+one after the other: a NumberAnimation, a PauseAnimation and another
+NumberAnimation. The SequentialAnimation is applied as a \l{Animations as
+Property Value Sources}{property value source animation} on the image's \c y
+property, so that the animation starts as soon as the image is loaded, moving
+the image up and down:
+
+\snippet doc/src/snippets/declarative/animation-groups.qml 0
+\image propanim.gif
+
+Since the SequentialAnimation is applied to the \c y property, the individual
+animations within the group are automatically applied to the \c y property as
+well; it is not required to set their \l{PropertyAnimation::}{properties}
+values to a particular property.
 
-In the following snippet, we specify that we want the \c x position of \c redRect to be animated
-whenever it changes. The animation will last 300 milliseconds and use an \l{PropertyAnimation::easing.type}{Easing.InOutQuad} easing curve.
+Animation groups can be nested. Here is a rather complex animation making use
+of both sequential and parallel animations:
 
-\snippet doc/src/snippets/declarative/animation.qml behavior
+\snippet doc/src/snippets/declarative/animation-groups.qml 1
 
-Like using an animation as a value source, when used in a \l Behavior and animation does not need to specify
-a \c target or \c property.
+Once individual animations are placed into a SequentialAnimation or
+ParallelAnimation, they can no longer be started and stopped independently. The
+sequential or parallel animation must be started and stopped as a group.
 
-To trigger this behavior, we could enter a state that changes \c x:
+See the \l {declarative/animation/basics}{Animation basics example} for a
+demonstration of creating and combining multiple animations in QML.
 
-\qml
-State {
-    name: "myState"
-    PropertyChanges {
-        target: redRect
-        x: 200
-        ...
-    }
-}
-\endqml
 
-Or, update \c x from a script:
 
-\qml
-MouseArea {
-    ....
-    onClicked: redRect.x = 24;
-}
-\endqml
+\section2 Other Animation Elements
 
-If \c x were bound to another property, triggering the binding would also trigger the behavior.
+In addition, QML provides several other elements useful for animation:
 
-If a state change has a transition animation matching a property with a \l Behavior, the transition animation
-will override the \l Behavior for that state change.
+\list
+\o PauseAnimation: enables pauses during animations
+\o ScriptAction: allows JavaScript to be executed during an animation, and can
+be used together with StateChangeScript to reused existing scripts
+\o PropertyAction: changes a property \e immediately during an animation,
+without animating the property change
+\endlist
 
-The \l {declarative/animation/behaviors}{Behaviors example} shows how behaviors can be used to provide animations.
+See their respective documentation pages for more details.
 
 */
diff --git a/doc/src/snippets/declarative/animation-behavioral.qml b/doc/src/snippets/declarative/animation-behavioral.qml
new file mode 100644
index 0000000..dc79018
--- /dev/null
+++ b/doc/src/snippets/declarative/animation-behavioral.qml
@@ -0,0 +1,61 @@
+/****************************************************************************
+**
+** 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:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//![0]
+import Qt 4.7
+
+Item {
+    width: 100; height: 100
+
+    Rectangle {
+        id: rect
+        width: 100; height: 100
+        color: "red"
+        
+        Behavior on x { PropertyAnimation { duration: 500 } }
+        Behavior on y { PropertyAnimation { duration: 500 } }
+    }
+
+    MouseArea {
+        anchors.fill: parent
+        onClicked: { rect.x = mouse.x; rect.y = mouse.y }
+    }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/animation-easing.qml b/doc/src/snippets/declarative/animation-easing.qml
new file mode 100644
index 0000000..e65c470
--- /dev/null
+++ b/doc/src/snippets/declarative/animation-easing.qml
@@ -0,0 +1,51 @@
+/****************************************************************************
+**
+** 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:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//![0]
+import Qt 4.7
+
+Rectangle {
+    width: 100; height: 100
+    color: "red"
+    
+    PropertyAnimation on x { to: 50; duration: 1000; easing.type: Easing.OutBounce }
+    PropertyAnimation on y { to: 50; duration: 1000; easing.type: Easing.OutBounce }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/animation-elements.qml b/doc/src/snippets/declarative/animation-elements.qml
new file mode 100644
index 0000000..7cb253e
--- /dev/null
+++ b/doc/src/snippets/declarative/animation-elements.qml
@@ -0,0 +1,66 @@
+/****************************************************************************
+**
+** 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:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//![0]
+import Qt 4.7
+
+Row {
+
+//![color]
+Rectangle {
+    width: 100; height: 100
+
+    ColorAnimation on color { from: "red"; to: "yellow"; duration: 1000 }
+}
+//![color]
+
+//![rotation]
+Item {
+    width: 300; height: 300
+    
+    Rectangle {
+        width: 100; height: 100; anchors.centerIn: parent
+        color: "red"
+        
+        RotationAnimation on rotation { to: 90; direction: RotationAnimation.Clockwise }
+    }
+}
+//![rotation]
+
+}
diff --git a/doc/src/snippets/declarative/animation-groups.qml b/doc/src/snippets/declarative/animation-groups.qml
new file mode 100644
index 0000000..8a8f925
--- /dev/null
+++ b/doc/src/snippets/declarative/animation-groups.qml
@@ -0,0 +1,104 @@
+/****************************************************************************
+**
+** 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:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+import Qt 4.7
+
+Row {
+
+//![0]
+Rectangle {
+    id: rect
+    width: 120; height: 200
+
+    Image {
+        id: img
+        source: "pics/qt.png"
+        anchors.horizontalCenter: parent.horizontalCenter
+        y: 0
+
+        SequentialAnimation on y {
+            loops: Animation.Infinite
+            NumberAnimation { to: rect.height - img.height; easing.type: Easing.OutBounce; duration: 2000 }
+            PauseAnimation { duration: 1000 }
+            NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 }
+        }
+    }
+}
+//![0]
+
+//![1]
+Rectangle {
+    id: redRect
+    width: 100; height: 100
+    color: "red"
+
+    MouseArea { id: mouseArea; anchors.fill: parent }
+
+    states: State {
+        name: "pressed"; when: mouseArea.pressed
+        PropertyChanges { target: redRect; color: "blue"; y: mouseArea.mouseY; width: mouseArea.mouseX }
+    }
+
+    transitions: Transition {
+
+        SequentialAnimation {
+            ColorAnimation { duration: 200 }
+            PauseAnimation { duration: 100 }
+
+            ParallelAnimation {
+                NumberAnimation {
+                    duration: 500
+                    easing.type: Easing.OutBounce
+                    targets: redRect
+                    properties: "y"
+                }
+
+                NumberAnimation {
+                    duration: 800
+                    easing.type: Easing.InOutQuad
+                    targets: redRect
+                    properties: "width"
+                }
+            }
+        }
+    }
+}
+//![1]
+
+}
diff --git a/doc/src/snippets/declarative/animation-propertyvaluesource.qml b/doc/src/snippets/declarative/animation-propertyvaluesource.qml
new file mode 100644
index 0000000..ac5f071
--- /dev/null
+++ b/doc/src/snippets/declarative/animation-propertyvaluesource.qml
@@ -0,0 +1,51 @@
+/****************************************************************************
+**
+** 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:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//![0]
+import Qt 4.7
+
+Rectangle {
+    width: 100; height: 100
+    color: "red"
+    
+    PropertyAnimation on x { to: 50; duration: 1000; loops: Animation.Infinite }
+    PropertyAnimation on y { to: 50; duration: 1000; loops: Animation.Infinite }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/animation-signalhandler.qml b/doc/src/snippets/declarative/animation-signalhandler.qml
new file mode 100644
index 0000000..749596c
--- /dev/null
+++ b/doc/src/snippets/declarative/animation-signalhandler.qml
@@ -0,0 +1,55 @@
+/****************************************************************************
+**
+** 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:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//![0]
+import Qt 4.7
+
+Rectangle {
+    id: rect
+    width: 100; height: 100
+    color: "red"
+
+    MouseArea {
+        anchors.fill: parent
+        onClicked: PropertyAnimation { target: rect; properties: "x,y"; to: 50; duration: 1000 }
+    }
+}
+
+//![0]
+
diff --git a/doc/src/snippets/declarative/animation-standalone.qml b/doc/src/snippets/declarative/animation-standalone.qml
new file mode 100644
index 0000000..d75fd92
--- /dev/null
+++ b/doc/src/snippets/declarative/animation-standalone.qml
@@ -0,0 +1,63 @@
+/****************************************************************************
+**
+** 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:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//![0]
+import Qt 4.7
+
+Rectangle {
+    id: rect
+    width: 100; height: 100
+    color: "red"
+    
+    PropertyAnimation { 
+        id: animation
+        target: rect
+        properties: "x,y"
+        duration: 1000
+    }
+    
+    MouseArea {
+        anchors.fill: parent
+        onClicked: {
+            animation.to = 50;
+            animation.running = true;
+        }
+    }		
+}
+//![0]
diff --git a/doc/src/snippets/declarative/animation-transitions.qml b/doc/src/snippets/declarative/animation-transitions.qml
new file mode 100644
index 0000000..3265065
--- /dev/null
+++ b/doc/src/snippets/declarative/animation-transitions.qml
@@ -0,0 +1,62 @@
+/****************************************************************************
+**
+** 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:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//![0]
+import Qt 4.7
+
+Rectangle {
+    id: rect
+    width: 100; height: 100
+    color: "red"
+    
+    MouseArea {
+        anchors.fill: parent
+        onClicked: rect.state = "moved"
+    }
+    
+    states: State {
+        name: "moved"
+        PropertyChanges { target: rect; x: 50; y: 50 }
+    }
+    
+    transitions: Transition {
+        PropertyAnimation { properties: "x,y"; duration: 1000 }
+    }
+}
+//![0]
diff --git a/doc/src/snippets/declarative/animation.qml b/doc/src/snippets/declarative/animation.qml
deleted file mode 100644
index 65acd36..0000000
--- a/doc/src/snippets/declarative/animation.qml
+++ /dev/null
@@ -1,181 +0,0 @@
-/****************************************************************************
-**
-** 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 Qt 4.7
-
-Row {
-
-//![property-anim-1]
-Rectangle {
-    id: rect
-    width: 120; height: 200
-
-    Image {
-        id: img
-        source: "pics/qt.png"
-        x: 60 - img.width/2
-        y: 0
-
-        SequentialAnimation on y {
-            loops: Animation.Infinite
-            NumberAnimation { to: 200 - img.height; easing.type: Easing.OutBounce; duration: 2000 }
-            PauseAnimation { duration: 1000 }
-            NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 }
-        }
-    }
-}
-//![property-anim-1]
-
-//![property-anim-2]
-Rectangle {
-    width: 200; height: 200
-
-    Rectangle {
-        color: "red"
-        width: 50; height: 50
-        NumberAnimation on x { to: 50 }
-    }
-}
-//![property-anim-2]
-
-
-Item {
-//![property-anim-3]
-PropertyAnimation {
-    id: animation
-    target: image
-    property: "scale"
-    from: 1; to: 0.5
-}
-
-Image {
-    id: image
-    source: "pics/qt.png"
-    MouseArea {
-        anchors.fill: parent
-        onPressed: animation.start()
-    }
-}
-//![property-anim-3]
-}
-
-
-//![transitions-1]
-transitions: [
-    Transition {
-        NumberAnimation {
-            properties: "x,y"
-            easing.type: Easing.OutBounce
-            duration: 200
-        }
-    }
-]
-//![transitions-1]
-
-
-//![transitions-2]
-Transition {
-    from: "*"
-    to: "MyState"
-    reversible: true
-
-    SequentialAnimation {
-        NumberAnimation {
-            duration: 1000
-            easing.type: Easing.OutBounce
-
-            // animate myItem's x and y if they have changed in the state
-            target: myItem
-            properties: "x,y"
-        }
-
-        NumberAnimation {
-            duration: 1000
-
-            // animate myItem2's y to 200, regardless of what happens in the state
-            target: myItem2
-            property: "y"
-            to: 200
-        }
-    }
-}
-//![transitions-2]
-
-
-//![transitions-3]
-Transition {
-    from: "*"
-    to: "MyState"
-    reversible: true
-
-    SequentialAnimation {
-        ColorAnimation { duration: 1000 }
-        PauseAnimation { duration: 1000 }
-
-        ParallelAnimation {
-            NumberAnimation {
-                duration: 1000
-                easing.type: Easing.OutBounce
-                targets: box1
-                properties: "x,y"
-            }
-            NumberAnimation {
-                duration: 1000
-                targets: box2
-                properties: "x,y"
-            }
-        }
-    }
-}
-//![transitions-3]
-
-//![behavior]
-Rectangle {
-    id: redRect
-    color: "red"
-    width: 100; height: 100
-
-    Behavior on x { 
-        NumberAnimation { duration: 300; easing.type: Easing.InOutQuad }
-    }
-}
-//![behavior]
-
-}
diff --git a/doc/src/snippets/declarative/transition.qml b/doc/src/snippets/declarative/transition.qml
index b884750..098d509 100644
--- a/doc/src/snippets/declarative/transition.qml
+++ b/doc/src/snippets/declarative/transition.qml
@@ -46,13 +46,18 @@ Rectangle {
     width: 100; height: 100
     color: "red"
 
+    MouseArea {
+        id: mouseArea
+        anchors.fill: parent
+    }
+
     states: State {
-        name: "moved"
+        name: "moved"; when: mouseArea.pressed
         PropertyChanges { target: rect; x: 50; y: 50 }
     }
 
     transitions: Transition { 
-        PropertyAnimation { properties: "x,y"; easing.type: Easing.InOutQuad } 
+        NumberAnimation { properties: "x,y"; easing.type: Easing.InOutQuad } 
     }
 }
 //![0]
diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp
index 6a9cf95..b901bb3 100644
--- a/src/declarative/util/qdeclarativeanimation.cpp
+++ b/src/declarative/util/qdeclarativeanimation.cpp
@@ -645,12 +645,13 @@ QAbstractAnimation *QDeclarativePauseAnimation::qtAnimation()
 
     Like any other animation element, a ColorAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
-    When used in a transition, ColorAnimation will by default animate
-    all properties of type color that have changed. If a \l{PropertyAnimation::}{property} 
-    or \l{PropertyAnimation::}{properties} are explicitly set for the animation, 
+    For convenience, when a ColorAnimation is used in a \l Transition, it will 
+    animate any \c color properties that have been modified during the state 
+    change. If a \l{PropertyAnimation::}{property} or 
+    \l{PropertyAnimation::}{properties} are explicitly set for the animation, 
     then those are used instead.
 
     \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
@@ -1143,7 +1144,7 @@ void QDeclarativePropertyAction::transition(QDeclarativeStateActions &actions,
 
     Like any other animation element, a NumberAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     Note that NumberAnimation may not animate smoothly if there are irregular
@@ -1244,6 +1245,11 @@ void QDeclarativeNumberAnimation::setTo(qreal t)
     Vector3dAnimation is a specialized PropertyAnimation that defines an 
     animation to be applied when a Vector3d value changes.
 
+    Like any other animation element, a Vector3dAnimation 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
+    for creating animations.
+
     \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 
@@ -1323,7 +1329,7 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t)
 
     \snippet doc/src/snippets/declarative/rotationanimation.qml 0
     
-    Notice the RotationAnimation did not need to set a \l {RotationAnimation::}{target}
+    Notice the RotationAnimation did not need to set a \l {PropertyAnimation::}{target}
     value. As a convenience, when used in a transition, RotationAnimation will rotate all
     properties named "rotation" or "angle". You can override this by providing
     your own properties via \l {PropertyAnimation::properties}{properties} or 
@@ -1331,7 +1337,7 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t)
 
     Like any other animation element, a RotationAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
@@ -1554,7 +1560,7 @@ QDeclarativeListProperty<QDeclarativeAbstractAnimation> QDeclarativeAnimationGro
 
     Like any other animation element, a SequentialAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     \note Once an animation has been grouped into a SequentialAnimation or 
@@ -1623,7 +1629,7 @@ void QDeclarativeSequentialAnimation::transition(QDeclarativeStateActions &actio
 
     Like any other animation element, a ParallelAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     \note Once an animation has been grouped into a SequentialAnimation or 
@@ -2396,8 +2402,7 @@ void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions
     \inherits Animation
     \brief The ParentAnimation element animates changes in parent values.
 
-    ParentAnimation defines an animation to applied when a ParentChange
-    occurs. This allows parent changes to be smoothly animated.
+    ParentAnimation is used to animate a parent change for an \l Item.
 
     For example, the following ParentChange changes \c blueRect to become
     a child of \c redRect when it is clicked. The inclusion of the 
@@ -2415,10 +2420,16 @@ void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions
     to animate the parent change via another item that does not have clipping
     enabled. Such an item can be set using the \l via property.
 
-    By default, when used in a transition, ParentAnimation animates all parent 
-    changes. This can be overridden by setting a specific target item using the
+    For convenience, when a ParentAnimation is used in a \l Transition, it will 
+    animate any ParentChange that has occurred during the state change. 
+    This can be overridden by setting a specific target item using the
     \l target property.
 
+    Like any other animation element, a ParentAnimation 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
+    for creating animations.
+
     \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 
@@ -2750,14 +2761,23 @@ QAbstractAnimation *QDeclarativeParentAnimation::qtAnimation()
     \inherits Animation
     \brief The AnchorAnimation element animates changes in anchor values.
 
-    AnchorAnimation is used to animate an AnchorChange. It will anchor all
-    anchor changes specified in a \l State.
+    AnchorAnimation is used to animate an anchor change. 
 
     In the following snippet we animate the addition of a right anchor to a \l Rectangle:
 
     \snippet doc/src/snippets/declarative/anchoranimation.qml 0
 
-    \sa AnchorChanges
+    For convenience, when an AnchorAnimation is used in a \l Transition, it will 
+    animate any AnchorChanges that have occurred during the state change. 
+    This can be overridden by setting a specific target item using the
+    \l target property.
+
+    Like any other animation element, an AnchorAnimation 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
+    for creating animations.
+
+    \sa {QML Animation}, AnchorChanges
 */
 
 QDeclarativeAnchorAnimation::QDeclarativeAnchorAnimation(QObject *parent)
diff --git a/src/declarative/util/qdeclarativebehavior.cpp b/src/declarative/util/qdeclarativebehavior.cpp
index fadb2ae..1e7f81a 100644
--- a/src/declarative/util/qdeclarativebehavior.cpp
+++ b/src/declarative/util/qdeclarativebehavior.cpp
@@ -84,12 +84,15 @@ public:
 
     \snippet doc/src/snippets/declarative/behavior.qml 0
 
-    To run multiple animations within a Behavior, use ParallelAnimation or
+    Note that a property cannot have more than one assigned Behavior. To provide
+    multiple animations within a Behavior, use ParallelAnimation or
     SequentialAnimation.
 
-    Note that a property cannot have more than one assigned Behavior.
+    If a \l{QML States}{state change} has a \l Transition that matches the same property as a
+    Behavior, the \l Transition animation overrides the Behavior for that
+    state change.
 
-    \sa {Property Behaviors}, {declarative/animation/behaviors}{Behavior example}, QtDeclarative
+    \sa {QML Animation}, {declarative/animation/behaviors}{Behavior example}, QtDeclarative
 */
 
 
diff --git a/src/declarative/util/qdeclarativesmoothedanimation.cpp b/src/declarative/util/qdeclarativesmoothedanimation.cpp
index 727f427..30e1491 100644
--- a/src/declarative/util/qdeclarativesmoothedanimation.cpp
+++ b/src/declarative/util/qdeclarativesmoothedanimation.cpp
@@ -287,7 +287,7 @@ void QSmoothedAnimation::init()
 
     Like any other animation element, a SmoothedAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     \sa SpringAnimation, NumberAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example}
diff --git a/src/declarative/util/qdeclarativespringanimation.cpp b/src/declarative/util/qdeclarativespringanimation.cpp
index cfc7b8e..6f4ac51 100644
--- a/src/declarative/util/qdeclarativespringanimation.cpp
+++ b/src/declarative/util/qdeclarativespringanimation.cpp
@@ -228,6 +228,7 @@ void QDeclarativeSpringAnimationPrivate::updateMode()
 
 /*!
     \qmlclass SpringAnimation QDeclarativeSpringAnimation
+    \inherits Animation
     \since 4.7
 
     \brief The SpringAnimation element allows a property to track a value in a spring-like motion.
@@ -246,7 +247,7 @@ void QDeclarativeSpringAnimationPrivate::updateMode()
 
     Like any other animation element, a SpringAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     \sa SmoothedAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example}, {declarative/toys/clocks}{Clocks example}
diff --git a/src/declarative/util/qdeclarativestate.cpp b/src/declarative/util/qdeclarativestate.cpp
index 0d43d21..7a78a2b 100644
--- a/src/declarative/util/qdeclarativestate.cpp
+++ b/src/declarative/util/qdeclarativestate.cpp
@@ -154,7 +154,7 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje
 
     Notice the default state is referred to using an empty string ("").
 
-    States are commonly used together with \l {state-transitions}{Transitions} to provide
+    States are commonly used together with \l {Transitions} to provide
     animations when state changes occur.
 
     \note Setting the state of an object from within another state of the same object is
diff --git a/src/declarative/util/qdeclarativestategroup.cpp b/src/declarative/util/qdeclarativestategroup.cpp
index 67cd12e..1c1e964 100644
--- a/src/declarative/util/qdeclarativestategroup.cpp
+++ b/src/declarative/util/qdeclarativestategroup.cpp
@@ -112,7 +112,7 @@ public:
    }
    \endqml
 
-   \sa {qmlstate}{States} {state-transitions}{Transitions}, {QtDeclarative}
+   \sa {qmlstate}{States} {Transitions}, {QtDeclarative}
 */
 
 QDeclarativeStateGroup::QDeclarativeStateGroup(QObject *parent)
@@ -204,7 +204,7 @@ void QDeclarativeStateGroupPrivate::clear_states(QDeclarativeListProperty<QDecla
   }
   \endqml
 
-  \sa {state-transitions}{Transitions}
+  \sa {Transitions}
 */
 QDeclarativeListProperty<QDeclarativeTransition> QDeclarativeStateGroup::transitionsProperty()
 {
diff --git a/src/declarative/util/qdeclarativetransition.cpp b/src/declarative/util/qdeclarativetransition.cpp
index 582191b..7042d0c 100644
--- a/src/declarative/util/qdeclarativetransition.cpp
+++ b/src/declarative/util/qdeclarativetransition.cpp
@@ -60,12 +60,25 @@ QT_BEGIN_NAMESPACE
 
     For example, the following \l Rectangle has two states: the default state, and
     an added "moved" state. In the "moved state, the rectangle's position changes 
-    to (50, 50).  The added \l Transition specifies that when the rectangle
+    to (50, 50).  The added Transition specifies that when the rectangle
     changes between the default and the "moved" state, any changes
     to the \c x and \c y properties should be animated, using an \c Easing.InOutQuad.
    
     \snippet doc/src/snippets/declarative/transition.qml 0
 
+    Notice the example does not require \l{PropertyAnimation::}{to} and 
+    \l{PropertyAnimation::}{from} values for the NumberAnimation. As a convenience,
+    these properties are automatically set to the values of \c x and \c y before
+    and after the state change; the \c from values are provided by
+    the current values of \c x and \c y, and the \c to values are provided by
+    the PropertyChanges object. If you wish, you can provide \l{PropertyAnimation::}{to} and 
+    \l{PropertyAnimation::}{from} values anyway to override the default values.
+
+    By default, a Transition's animations are applied for any state change in the 
+    parent item. The  Transition \l {Transition::}{from} and \l {Transition::}{to} 
+    values can be set to restrict the animations to only be applied when changing 
+    from one particular state to another.
+
     To define multiple transitions, specify \l Item::transitions as a list:
 
     \qml
@@ -78,7 +91,11 @@ QT_BEGIN_NAMESPACE
     }
     \endqml
 
-    \sa {declarative/animation/states}{states example}, {qmlstates}{States}, {state-transitions}{Transitions}, {QtDeclarative}
+    If a state change has a Transition that matches the same property as a
+    \l Behavior, the Transition animation overrides the \l Behavior for that
+    state change.
+
+    \sa {QML Animation}, {declarative/animation/states}{states example}, {qmlstates}{States}, {QtDeclarative}
 */
 
 /*!