path: root/doc/src/declarative/animation.qdoc

/****************************************************************************
**
** 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 documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\page qdeclarativeanimation.html
\title QML Animation


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.



\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

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.

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.

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. Here is an example, using a 
PropertyAnimation object. The animation is explicitly started when the 
\l Rectangle is clicked:

\snippet doc/src/snippets/declarative/animation-standalone.qml 0

A standalone animation 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.)

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

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:

\snippet doc/src/snippets/declarative/animation-transitions.qml 0

The PropertyChanges object in the \e moved state defines that when the
\l Rectangle is in this state, its position should be changed
to (50, 50). When the \l Rectangle changes to the \e moved state, the 
\l Transition will be triggered, and the transition's \l PropertyAnimation will
animate the changes in the \c x and \c y properties to their new values.
The animation will not be applied at any time other than during the state 
change.

Notice the example does not set any \l {PropertyAnimation::}{from} and \l
{PropertyAnimation::}{to} values for the PropertyAnimation. As a convenience,
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.

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.

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}.

See the \l Transition documentation for more information.


\section1 Animation Elements

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.

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.


\section2 Property Animation Elements

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. 

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:

\snippet doc/src/snippets/declarative/animation-elements.qml color

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-elements.qml rotation

In addition, the following specialized animation elements are available:

\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.


\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.

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

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.

*/