source: trunk/doc/src/declarative/animation.qdoc@ 846

/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** 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 [email protected].
** $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