Improve docs on QML Animation page and associated elements

Task-number: QTBUG-12666

1 files changed, 256 insertions, 89 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.
 
 */