Re-wrote QML Animation documentation and cleaned snippet code

Removed unneeded snippets and added new snippet code.

Task-number: QTBUG-16071
Reviewed-by: David Boddie

1 files changed, 140 insertions, 236 deletions

diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc
index 26545ad..77900ee 100644
--- a/doc/src/declarative/animation.qdoc
+++ b/doc/src/declarative/animation.qdoc
@@ -33,227 +33,187 @@
 \nextpage {QML Data Models}{Structuring Data with Models}
 \title QML Animation and Transitions
 
-
-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:
-
+\keyword qml-animation-elements
+\section1 Animation and Transitions Elements
 \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}
+\o \l {Transition} - Animates transitions during state changes
+\o \l {SequentialAnimation} - Runs animations sequentially
+\o \l {ParallelAnimation} - Runs animations in parallel
+\o \l {Behavior} - Specifies a default animation for property changes
+\o \l {PropertyAction} - Sets immediate property changes during animation
+\o \l {PauseAnimation} - Introduces a pause in an animation
+\o \l {SmoothedAnimation} - Allows a property to smoothly track a value
+\o \l {SpringAnimation} - Allows a property to track a value in a spring-like motion
+\o \l {ScriptAction} - Runs scripts during an animation
 \endlist
 
-To support these different types of animation methods, QML provides several
-methods for defining an animation. These are:
-
+\keyword qml-property-animation-elements
+Elements that animate properties based on data types
 \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}
+\o \l {PropertyAnimation} - Animates property changes
+\o \l {NumberAnimation} - Animates properties of type qreal
+\o \l {Vector3dAnimation} - Animates properties of type QVector3d
+\o \l {ColorAnimation} - Animates color changes
+\o \l {RotationAnimation} - Animates rotations
+\o \l {ParentAnimation} - Animates parent changes
+\o \l {AnchorAnimation} - Animates anchor 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.
-
-
+\section1 Overview
 
-\section2 Animations as Property Value Sources
+In QML, animations are created by applying animation elements to property
+values. Animation elements will interpolate property values to create smooth
+transitions. As well, state transitions may assign animations to state changes.
 
-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.
+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.
 
+\keyword qml-triggering-animations
+\section1 Triggering Animations
 
-\section2 Behavioral Animations
+There are several ways of setting animation to an object.
 
-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:
+\keyword qml-direct-animation
+\section2 Direct Property Animation
 
-\snippet doc/src/snippets/declarative/animation-behavioral.qml 0
+To create an immediate movement or animated movement, set the property value
+directly. This may be done in signal handlers or attached properties.
 
-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.
+\snippet doc/src/snippets/declarative/animation.qml direct property change
 
-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.
+However, to create more control, \e {property animations} apply smooth movements
+by interpolating values between property value changes. Property animations
+provide timing controls and allows different interpolations through
+\l{qml-easing-animation}{easing curves}.
 
-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.
+\snippet doc/src/snippets/declarative/animation.qml property animation
 
-See the \l {declarative/animation/behaviors}{Behaviors example} for a
-demonstration of behavioral animations.
+Specialized \l{qml-property-animation-elements}{property animation elements}
+have more efficient implementations than the \l{PropertyAnimation} element. They
+are for setting animations to different QML types such as \c int, \c color, and
+rotations. Similarly, the \l{ParentAnimation} can animate parent changes.
 
+See the \l {qml-controlling-animations}{Controlling Animations} section for more
+information about the different animation properties.
 
-\section2 Animations in a Signal Handler
+\keyword qml-transition-animations
+\section2 Transitions during State Changes
 
-An animation can be created within a signal handler to be triggered when the
-signal is received. For example:
+\l{QML States}{States} are property configurations where a property may have different values to reflect different states. State changes introduce
+abrupt property changes; animations smooth transitions to produce visually
+appealing state changes.
 
-\snippet doc/src/snippets/declarative/animation-signalhandler.qml 0
+The \l{Transition} element can contain
+\l{qml-animation-elements}{animation elements} to interpolate property changes
+caused by state changes. To assign the transition to an object, bind it to the
+\c transitions property.
 
-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.
+A button might have two states, the \c pressed state when the user clicks on the
+button and a \c released state when the user releases the button. We can assign
+different property configurations for each state. A transition would animate the
+change from the \c pressed state to the \c released state. Likewise, there would
+be an animation during the change from the \c released state to the \c pressed
+state.
 
+\snippet doc/src/snippets/declarative/animation.qml transition animation
 
-\section2 Standalone Animations
+Binding the \c to and \c from properties to the state's name will assign that
+particular transition to the state change. For simple or symmetric transitions,
+setting the to \c to property to the wild card symbol, "\c{*}", denotes
+that the transition applies to any state change.
 
-Animations can also be created as ordinary QML objects that are not bound to
-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.qml wildcard animation
 
-\snippet doc/src/snippets/declarative/animation-standalone.qml 0
+\section2 Default Animation as Behaviors
 
-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
-{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.)
+Default property animations are set using \e {behavior animations}. Animations
+declared in \l {Behavior} elements apply to the property and animates any
+property value changes. However, Behavior elements have an
+\c enabled property to purposely enable or disable the behavior animations.
 
-Standalone animations are useful when an animation is not targeted towards a
-single object property and the animation should be explicitly started and
-stopped.
+A ball component might have a behavior animation assigned to its \c x, \c y, and
+\c color properties. The behavior animation could be set up to simulate an
+elastic effect. In effect, this behavior animation would apply the elastic
+effect to the properties whenever the ball moves.
 
+\snippet doc/src/snippets/declarative/animation.qml behavior animation
 
-\section2 Transitions
+There are several methods of assigning behavior animations to properties. The
+\c{Behavior on <property>} declaration is a convenient way of assigning a
+behavior animation onto a property.
 
-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:
+See the \l {declarative/animation/behaviors}{Behaviors example} for a
+demonstration of behavioral animations.
 
-\snippet doc/src/snippets/declarative/animation-transitions.qml 0
+\section1 Playing Animations in Parallel or in Sequence
 
-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.
+Animations can run \e {in parallel} or \e {in sequence}. Parallel animations
+will play a group of animations at the same time while sequential animations
+play a group of animations in order: one after the other. Grouping animations in
+\l{SequentialAnimation} and \{ParallelAnimation} will play the animations in
+sequence or in parallel.
 
-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.
+A banner component may have several icons or slogans to display, one after the
+other. The \c opacity property could transform to \c 1.0 denoting an opaque
+object. Using the \l{SequentialAnimation} element, the opacity animations will
+play after the preceding animation finishes. The \l{ParallelAnimation} element
+will play the animations at the same time.
 
-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.
+\snippet doc/src/snippets/declarative/animation.qml sequential animation
 
-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}.
+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.
 
-See the \l Transition documentation for more information.
+The \l SequentialAnimation element is also useful for playing
+\l{qml-transition-animations}{transition animations} because animations are
+played in parallel inside transitions.
 
+See the \l {declarative/animation/basics}{Animation basics example} for a
+demonstration of creating and combining multiple animations in QML.
 
-\section1 Animation Elements
+\keyword qml-controlling-animations
+\section1 Controlling Animations
 
-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.
+There are different methods to control animations.
 
-All animation elements inherit from the \l Animation element. It is not
+\section2 Animation Playback
+All \l{qml-animation-elements}{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.
-
+essential properties and methods for animation elements. Animation elements have
+\c{start()}, \c{stop()}, \c{resume()}, \c{pause()}, \c {restart()}, and
+\c{complete()} -- all of these methods control the execution of animations.
 
-\section2 Property Animation Elements
+\keyword qml-easing-animation
+\section2 Easing
 
-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.
+Easing curves define how the animation will interpolate between the start value
+and the end value. Different easing curves might go beyond the defined range of
+interpolation. The easing curves simplify the creation of animation effects such
+as bounce effects, acceleration, deceleration, and cyclical animations.
 
-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:
+A QML object may have different easing curve for each property animation. There
+are also different parameters to control the curve, some of which are exclusive
+to a particular curve. For more information about the easing curves, visit the
+\l {PropertyAnimation::easing.type}{easing} documentation.
 
-\snippet doc/src/snippets/declarative/animation-elements.qml color
+The \l{declarative/animation/easing}{easing example} visually demonstrates each
+of the different easing types.
 
-RotationAnimation allows a rotation's direction to be specified. The following
-animates the rectangle's \l {Item::rotation} property:
+\section2 Other Animation Elements
 
-\snippet doc/src/snippets/declarative/animation-elements.qml rotation
+In addition, QML provides several other elements useful for animation:
 
-In addition, the following specialized animation elements are available:
+\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
 
+These are specialized animation elements that animate different property types
 \list
 \o SmoothedAnimation: a specialized NumberAnimation that provides smooth
 changes in animation when the target value changes
@@ -264,75 +224,19 @@ attributes such as \l {SpringAnimation::}{mass},
 \o AnchorAnimation: used for animating an anchor change (see AnchorChanges)
 \endlist
 
-See their respective documentation pages for more details.
-
-
-\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-elements.qml color
+\snippet doc/src/snippets/declarative/animation-propertyvaluesource.qml 0
+\snippet doc/src/snippets/declarative/animation-signalhandler.qml 0
+\snippet doc/src/snippets/declarative/animation-standalone.qml 0
 
+\snippet doc/src/snippets/declarative/animation-transitions.qml 0
 \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.
-
-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-groups.qml 1
+\snippet doc/src/snippets/declarative/animation-groups.qml 0
+\image propanim.gif
 
-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.
-
-See the \l {declarative/animation/basics}{Animation basics example} for a
-demonstration of creating and combining multiple animations in QML.
-
-
-
-\section2 Other Animation Elements
-
-In addition, QML provides several other elements useful for animation:
-
-\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
-
-See their respective documentation pages for more details.
-
-*/