# Titanium.UI.Animation

The Animation object defines an animation that can be applied to a view.

Availability

0.9

9.2.0

Extends

Titanium.Proxy

# Overview

An animation object describes the properties of an animation. At its most basic, an animation object represents a single-phase animation with an end state and a duration.

When Titanium.UI.View.animate is called on a Titanium.UI.View, the view is animated from its current state to the state described by the animation object. The properties that can be animated include the view's position, size, colors, transformation matrix and opacity.

You can also specify an animation curve or easing function to control the pace of the animation. To use an easing function, set the animation's curve property to one of the ANIMATION_CURVE constants defined in Titanium.UI. For example, Titanium.UI.ANIMATION_CURVE_EASE_IN specifies an animation that starts slowly and then speeds up.

Animations can be set to reverse themselves automatically on completion, and to repeat a given number of times. For more complicated effects, multiple animations can be combined in sequence, starting one animation when the previous animation completes.

Use the Titanium.UI.createAnimation method to create an animation object.

Note that on SDKs older than 9.1.0, when you animate a view's size or position the actual layout properties (such as top, left, width, height) are not changed by the animation. See the description of the Titanium.UI.View.animate method for more information.

As of 9.1.0, the animated properties should reflect their final values just before the complete event and/or the <Ti.UI.View.animate> callback is fired.

# iOS Platform Notes

iOS supports both 2D and 3D matrix transformations in animations.

iOS also supports transitions between windows or views. You can create a transition by creating an animation object and setting the view property to the view you want to transition to. The transition property specifies the transition effect to apply. Use one of the transition style constants defined in Titanium.UI.iOS.AnimationStyle.

# Android Platform Notes

Android supports 2D matrix transformations. Note that the Titanium.UI.Matrix2D.rotate method operates differently on Android. Called with a single argument, it rotates from zero to the specified angle. That is, it ignores any existing rotation. Called with two arguments, it interprets the first argument as a "from" angle and the second argument as a "to" angle.

# Examples

# Simple Animation Applied to a View

Create a simple animation and apply it to the view. In this example, the view will animate from red to black to orange over 2 seconds.

var view = Titanium.UI.createView({
  backgroundColor:'red'
});
var animation = Titanium.UI.createAnimation();
animation.backgroundColor = 'black';
animation.duration = 1000;
var animationHandler = function() {
  animation.removeEventListener('complete',animationHandler);
  animation.backgroundColor = 'orange';
  view.animate(animation);
};
animation.addEventListener('complete',animationHandler);
view.animate(animation);

# Animation Using Matrix Transforms

The following example uses a transformation matrix to animate a view when the view is clicked. The animation rotates and scales the view, then returns it to its original size and position. The entire animation is repeated three times.

var box = Ti.UI.createView({
  backgroundColor : 'red',
  height : '100',
  width : '100'
});
win.add(box);

box.addEventListener('click', function() {
  var matrix = Ti.UI.createMatrix2D();
  matrix = matrix.rotate(180);
  matrix = matrix.scale(2, 2);
  var a = Ti.UI.createAnimation({
    transform : matrix,
    duration : 2000,
    autoreverse : true,
    repeat : 3
  });
  box.animate(a);
});

win.add(box);

# Using an anchorPoint (Android and iOS)

Create a button and a blue square view. For each click of the button, apply a 90 degree rotation animation pivoted at one of a series of anchor points. In particular, note that an anchor point is configured using the Titanium.UI.Animation.anchorPoint property for Android and the Titanium.UI.View.anchorPoint property for iOS.

var animationType = [
  { name: 'Top Left', anchorPoint: {x:0, y:0} },
  { name: 'Top Right', anchorPoint: {x:1, y:0} },
  { name: 'Bottom Left', anchorPoint: {x:0, y:1} },
  { name: 'Bottom Right', anchorPoint: {x:1, y:1} },
  { name: 'Center', anchorPoint: {x:0.5, y:0.5} }
];
var animationTypeLength = animationType.length;
var animationCount = 0;
var animationTypePointer = 0;

var t = Ti.UI.createMatrix2D();
t = t.rotate(90);

// animation properties
var a = {
  transform: t,
  duration: 2000,
  autoreverse: true
};

Ti.UI.backgroundColor = 'white';
var win = Ti.UI.createWindow();

var view = Ti.UI.createView({
  backgroundColor:'#336699',
  width:100, height:100
});
win.add(view);

var button = Ti.UI.createButton({
  title:'Animate ' + animationType[animationTypePointer].name,
  height: (Ti.UI.Android) ? 80 : 40,
  width: (Ti.UI.Android) ? 300 : 200,
  top:30
});
win.add(button);

function updateButton(name){
  button.title = 'Animate ' + name;
}

button.addEventListener('click', function(){
  // set new anchorPoint on animation for Android
  a.anchorPoint = animationType[animationTypePointer].anchorPoint;

  // set new anchorPoint on view for iOS
  view.anchorPoint = animationType[animationTypePointer].anchorPoint;

  animationCount++;

  // determine position of next object in animationType array or return to first item
  // using modulus operator
  animationTypePointer = animationCount % animationTypeLength;

  // animate view, followed by callback to set next button title
  view.animate(a, function(){
    updateButton(animationType[animationTypePointer].name);
  });
});

win.open();

# Properties

# anchorPoint

Availability

0.9

anchorPoint :Point

Coordinate of the view about which to pivot an animation.

Used on Android only. For iOS, use anchorPoint.

Anchor point is specified as a fraction of the view's size. For example, {0, 0} is at the view's top-left corner, {0.5, 0.5} at its center and {1, 1} at its bottom-right corner.

This property's value will overwrite the anchorPoint used in the matrix's creation dictionary.

See the "Using an anchorPoint" example for a demonstration.

# autoreverse

Availability

0.9

9.2.0

autoreverse :Boolean

Specifies if the animation should be replayed in reverse upon completion.

Default: false

# backgroundColor

Availability

0.9

9.2.0

backgroundColor :String | Titanium.UI.Color

Value of the backgroundColor property at the end of the animation, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

# bottom

Availability

0.9

9.2.0

bottom :Number

Availability

8.1.0

9.2.0

dampingRatio :Number

The damping ratio for the spring animation as it approaches its quiescent state.

Use a value between 0 and 1. For a smoother deceleration use values closer to 1. To increase oscillation use value closer to 0.

# delay

Availability

0.9

9.2.0

delay :Number

Delay, in milliseconds before starting the animation.

# duration

Availability

0.9

9.2.0

duration :Number

Duration of the animation, in milliseconds.

Availability

0.9

9.2.0

repeat :Number

Number of times the animation should be performed.

If autoreverse is true, then one repeat of the animation consists of the animation being played once forward, and once backward.

Default: 1 (no repeat)

# right

Availability

0.9

9.2.0

right :Number

Value of the right property at the end of the animation.

# springVelocity

Availability

8.1.0

9.2.0

springVelocity :Number

The initial spring velocity.

Availability

0.9

9.2.0

visible :Boolean

Value of the visible property at the end of the animation.

# width

Availability

0.9

9.2.0

width :Number

Value of the width property at the end of the animation.

# zIndex

Availability

0.9

9.2.0

zIndex :Number

Value of the zIndex property at the end of the animation.

Refer to zIndex for an explanation of z-index.

# Events

# complete

Availability

0.9

9.2.0

Fired when the animation completes.

# start

Availability

0.9

9.2.0

Fired when the animation starts.