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 Types of Animations that can be created and the Animation Elements that are used to create these animations.

Types of Animations

An animation is created in different ways depending on the context in which it is required. Suppose a Rectangle's movement - that is, changes in its x or y property values - should be animated. The semantics of the animation differ depending on whether you want to create:

• An animation that moves the Rectangle as soon as it is created, to a known position
• An animation that only triggers when the Rectangle is moved by external sources - for example, when the mouse is clicked, animate the movement to the mouse position
• An animation that triggers when a particular signal is received
• A standalone animation that is not bound to the Rectangle's movement, but instead can be started and stopped from script as required
• An animation that only triggers during state changes

To support these different types of animation methods, QML provides several methods for defining an animation. These are:

• Creating an animation using property value sources, to immediately animate a specific property
• Using behavioral animations, which are triggered when a property changes value
• Within a signal handler, to be triggered when a signal is received
• As a standalone animation, that can be started/stopped from script and can be rebound to different objects
• Using transitions, to provide animations between state changes

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 Animation Elements section further below for details.

Animations as Property Value Sources

An animation is applied as a property value source using the Animation on Property syntax. Here is a Rectangle whose movement is animated using this method:

 import QtQuick 1.0

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

This applies a PropertyAnimation to the Rectangle's x and y properties to animate from their current values (i.e. zero) to 50, over 1000 milliseconds. The animation starts as soon as the Rectangle is loaded. To animate from specific values rather than the current x and y values, set the PropertyAnimation's 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.

Behavioral Animations

Often an animation should be applied whenever a particular property value changes. In these cases, a Behavior can be used to specify a default animation for a property change. Here is an example:

 import QtQuick 1.0

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

This Rectangle has Behavior objects applied to its x and y properties. Whenever these properties change (in this case, when the mouse is clicked within the parent Item), the PropertyAnimation objects defined within the behaviors will be applied to these properties, thus animating the Rectangle's movement to its new position. Unlike the method of 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 in response to a value change.

Any changes to these properties will trigger their animations. If x or y were bound to other properties, and those properties changed, the animation would be triggered. The enabled property can be used to force a Behavior to only apply under certain circumstances.

Notice that unlike for property value source animations, the PropertyAnimation's from and to properties do not need to be defined because these values are already provided, respectively, by the Rectangle's current values and the new values set in the onClicked handler. If these properties were defined anyway, they would override the default values.

See the Behaviors example for a demonstration of behavioral animations.

Animations in a Signal Handler

An animation can be created within a signal handler to be triggered when the signal is received. For example:

 import QtQuick 1.0

 Rectangle {
     id: rect
     width: 100; height: 100
     color: "red"

     MouseArea {
         anchors.fill: parent
         onClicked: PropertyAnimation { target: rect; properties: "x,y"; to: 50; duration: 1000 }
     }
 }

The PropertyAnimation is triggered when the MouseArea is clicked, animating the x and 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 target and property (or targets and properties) values. The to property is also required to specify the new x and y values.

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 Rectangle is clicked:

 import QtQuick 1.0

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

A standalone animation object is not running by default and must be started explicitly using the running property or start() and stop() methods. Since the animation is not bound to a particular object or property, it must define the target and property (or targets and properties) values. The to property is also required to specify the new x and y values. (The 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.

Transitions

Transitions are used to describe the animations to be applied when a state change occurs. To create a transition, define a Transition object and add it to an item's transitions property. An example:

 import QtQuick 1.0

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

The PropertyChanges object in the moved state defines that when the Rectangle is in this state, its position should be changed to (50, 50). When the Rectangle changes to the moved state, the Transition will be triggered, and the transition's PropertyAnimation will animate the changes in the x and 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 from and to values for the PropertyAnimation. As a convenience, these properties are automatically set to the values of x and 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 target object; any x or 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 Transition are run in parallel. To run them one after the other, use a SequentialAnimation, as shown below in Grouping Animations.

See the Transition documentation for more information.

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 Animation element. It is not possible to create 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 running property and the start() and stop() methods. It can also define the number of loops for an animation.

Property Animation Elements

PropertyAnimation is the most basic animation element for animating a property. It can be used to animate real, int, color, rect, point, size, and vector3d properties. It is inherited by NumberAnimation, ColorAnimation, RotationAnimation and Vector3dAnimation: NumberAnimation provides a more efficient implementation for animating real and int properties, and Vector3dAnimation does the same for vector3d properties. ColorAnimation and RotationAnimation provide more specific attributes for animating color and rotation changes.

A ColorAnimation allows color values for the from and to properties. The following animates the rectangle's color property:

 Rectangle {
     width: 100; height: 100

     ColorAnimation on color { from: "red"; to: "yellow"; duration: 1000 }
 }

RotationAnimation allows a rotation's direction to be specified. The following animates the rectangle's Item::rotation property:

 Item {
     width: 300; height: 300

     Rectangle {
         width: 100; height: 100; anchors.centerIn: parent
         color: "red"

         RotationAnimation on rotation { to: 90; direction: RotationAnimation.Clockwise }
     }
 }

In addition, the following specialized animation elements are available:

• SmoothedAnimation: a specialized NumberAnimation that provides smooth changes in animation when the target value changes
• SpringAnimation: provides a spring-like animation with specialized attributes such as mass, damping and epsilon
• ParentAnimation: used for animating a parent change (see ParentChange)
• AnchorAnimation: used for animating an anchor change (see AnchorChanges)

See their respective documentation pages for more details.

Easing

Any PropertyAnimation-based animations can specify 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 earlier example uses Easing.OutBounce to create a bouncing effect when the animation reaches its target value:

 import QtQuick 1.0

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

The easing example visually demonstrates each of the different easing types.

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 property value source animation on the image's y property, so that the animation starts as soon as the image is loaded, moving the image up and down:

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

Since the SequentialAnimation is applied to the y property, the individual animations within the group are automatically applied to the y property as well; it is not required to set their 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:

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

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 Animation basics example for a demonstration of creating and combining multiple animations in QML.

Other Animation Elements

In addition, QML provides several other elements useful for animation:

• PauseAnimation: enables pauses during animations
• ScriptAction: allows JavaScript to be executed during an animation, and can be used together with StateChangeScript to reused existing scripts
• PropertyAction: changes a property immediately during an animation, without animating the property change

See their respective documentation pages for more details.