Titanium.UI.Animation

Object of Titanium.UI.

Platform	Since
Android	0.9
iPhone	0.9
iPad	0.9
Mobile Web	1.8

Summary

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

Description

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 animate is called on a 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.

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 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 animate method for more information.

iOS Platform Notes

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

In iOS, 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.iOS. For example, ANIMATION_CURVE_EASE_IN specifies an animation that starts slowly and then speeds up.

Finally, 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.iPhone.AnimationStyle.

Android Platform Notes

Android supports 2D matrix transformations. Note that the 2DMatrix.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.

Android doesn't support any animation curves or easing functions. Animations always interpolate linearly between the start state and the end state.

Code 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.create2DMatrix()
    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);
});

Methods

Name	Summary
addEventListener	Adds the specified callback as an event listener for the named event.
fireEvent	Fires a synthesized event to any registered listeners.
getAutoreverse	Gets the value of the autoreverse property.
getBackgroundColor	Gets the value of the backgroundColor property.
getBottom	Gets the value of the bottom property.
getCenter	Gets the value of the center property.
getColor	Gets the value of the color property. (iPhone, iPad, Mobile Web only.)
getCurve	Gets the value of the curve property. (iPhone, iPad, Mobile Web only.)
getDelay	Gets the value of the delay property.
getDuration	Gets the value of the duration property.
getHeight	Gets the value of the height property.
getLeft	Gets the value of the left property.
getOpacity	Gets the value of the opacity property.
getOpaque	Gets the value of the opaque property. (iPhone, iPad only.)
getRepeat	Gets the value of the repeat property.
getRight	Gets the value of the right property.
getTop	Gets the value of the top property.
getTransform	Gets the value of the transform property.
getTransition	Gets the value of the transition property. (iPhone, iPad only.)
getVisible	Gets the value of the visible property. (iPhone, iPad, Mobile Web only.)
getWidth	Gets the value of the width property.
getZIndex	Gets the value of the zIndex property. (iPhone, iPad, Mobile Web only.)
removeEventListener	Removes the specified callback as an event listener for the named event.
setAutoreverse	Sets the value of the autoreverse property.
setBackgroundColor	Sets the value of the backgroundColor property.
setBottom	Sets the value of the bottom property.
setCenter	Sets the value of the center property.
setColor	Sets the value of the color property. (iPhone, iPad, Mobile Web only.)
setCurve	Sets the value of the curve property. (iPhone, iPad, Mobile Web only.)
setDelay	Sets the value of the delay property.
setDuration	Sets the value of the duration property.
setHeight	Sets the value of the height property.
setLeft	Sets the value of the left property.
setOpacity	Sets the value of the opacity property.
setOpaque	Sets the value of the opaque property. (iPhone, iPad only.)
setRepeat	Sets the value of the repeat property.
setRight	Sets the value of the right property.
setTop	Sets the value of the top property.
setTransform	Sets the value of the transform property.
setTransition	Sets the value of the transition property. (iPhone, iPad only.)
setVisible	Sets the value of the visible property. (iPhone, iPad, Mobile Web only.)
setWidth	Sets the value of the width property.
setZIndex	Sets the value of the zIndex property. (iPhone, iPad, Mobile Web only.)

Properties

Name	Type	Summary
autoreverse	Boolean	Specifies if the animation should be replayed in reverse upon completion.
backgroundColor	String	Value of the `backgroundColor` property at the end of the animation.
bottom	Number	Value of the `bottom` property at the end of the animation.
center	Object	Value of the `center` property at the end of the animation.
color	String	Value of the `color` property at the end of the animation. (iPhone, iPad, Mobile Web only.)
curve	Number	Animation curve or easing function to apply to the animation. (iPhone, iPad, Mobile Web only.)
delay	Number	Delay, in milliseconds before starting the animation.
duration	Number	Duration of the animation, in milliseconds.
height	Number	Value of the `height` property at the end of the animation.
left	Number	Value of the `left` property at the end of the animation.
opacity	Number	Value of the `opacity` property at the end of the animation.
opaque	Boolean	Value of the `opaque` property at the end of the animation. (iPhone, iPad only.)
repeat	Number	Number of times the animation should be performed.
right	Number	Value of the `right` property at the end of the animation.
top	Number	Value of the `top` property at the end of the animation.
transform	`Titanium.UI.2DMatrix` or `Titanium.UI.iOS.3DMatrix`	Animate the view from its current tranform to the specified transform.
transition	Number	Transition type to use during a transition animation. (iPhone, iPad only.)
visible	Boolean	Value of the `visible` property at the end of the animation. (iPhone, iPad, Mobile Web only.)
width	Number	Value of the `width` property at the end of the animation.
zIndex	Number	Value of the `zIndex` property at the end of the animation. (iPhone, iPad, Mobile Web only.)

Events

Name	Summary
complete	Fired when the animation completes.
start	Fired when the animation starts.