This documentation relates to previous versions of Titanium.

To see the latest documentation, visit docs.appcelerator.com.

This space has been migrated to https://techweb.axway.com/confluence/display/dr and will be removed from the Appcelerator wiki on August 9th, 2018
Skip to end of metadata
Go to start of metadata
Chapters

Summary

In this guide, you will learn about how to work with animations and transformations. By the end of this guide, you should understand:

  • Point to point animations
  • Animating an element's opacity
  • The basics of working with transforms

Before we start

This tutorial assumes a basic understanding of animations. For a general introduction to animations, please see the Animation guide.

The video below shows what we will obtain at the end of this tutorial.

Setting up for Animations

First of all we need a UI element to animate. In this tutorial we will demonstrate animating labels and views. Let's start off by creating a couple labels.

We'll use the openingLabel to demonstrate 3D matrix transforms and save the closingLabel for demonstrating opacity animation. Let's take a closer look at openingLabel first. We already have our label so let's go ahead and create a 3D matrix that we will use as part of the animation:

2D & 3D matrices provide a number of methods that allow us to operate on the newly created matrix. Refer to the Titanium.UI.2DMatrix & Titanium.UI.3DMatrix API Docs for more information on these. If you need a quick synopsis on the fundamentals of transforms, we recommend the article at eleqtriq.com entitled, The Matrix Revolutions.

Starting an Animation

To animate our label we call the animate method on our label passing it an object that contains a transform and a duration. The transform in this case is the 3D matrix we created previously and the duration is simply the number of milliseconds we would like this animation to last. A callback function can also be provided which will allow for us to take some action after the animation has completed.

When applied to our openingLabel, the result is a label that grows, spins, and eventually moves out of view.

Using Animation Objects

The animation object is used for specifying lower-level animation properties and more low-level control of events during an animation. An animation object can be created via Titanium.UI.createAnimation. We'll make use of this to animate the closingLabel in this example. The closingLabel is initially hidden via opacity 0. Let's look at how we can animate the opacity of this UI element and scale it at the same time. This will enable us to create an appear/zoom effect for the closing credits of this example.

Over the course of 2500 milliseconds this label will grow 1.5x the size and fade in to become fully visible.

Animating Views

Of course the most interesting part of this example is the falling snowflakes. Let's review how such an effect might be created. Snowflakes come in all shapes and sizes. Their path to the ground is influenced by things like wind and other objects they meet in flight. To imitate such behavior we'll need to create views of varying shapes, sizes, angles, etc. We'll also need to randomize the location they start their journey and their path to the ground. We'll make use of the Animation object, 2D matrices, opacity, duration, etc. Let's start by creating a few helper functions:

With our helper functions in place we'll build up a set of snowflakes (views with a background image) to play with:

When we are ready for the snowfall to begin we iterate over our snowflake array and call the animate method on each view.

We are passing a custom animation object each time we call animate. When we created the viewsToAnimate array earlier each view was given a random top and left starting position. You'll notice we are also setting these properties again in our custom animation object, but with different values. Top is being set to a value just shy of the bottom of the screen. This is so that we can make the snowflakes appear to pile up at the bottom of the screen like snow. We could have used some conditional logic to determine the platform and based on that knowledge hardcoded some screen dimensions to figure out the correct top value offset needed to achieve this effect. However, as we can see in this example, there is another option. Titanium.Platform.displayCaps provides us with platformHeight & platformWidth properties that we can use to do the same thing without the extra overhead. Setting a new left value will cause our snowflake to move either left or right (depending on the original position) like the wind is blowing it. To make that left to right movement a bit smoother we use the Ti.UI.ANIMATION_CURVE_LINEAR curve constant.

We initially created 30 snowflakes, but we want the overall duration of the example to last a bit longer than the time it takes for 30 snowflakes to fall without dramatically slowing down each snowflake. To help solve this we make use of the repeat property. With repeat set at 3 each animation repeats 3 times and we end up with 90 falling snowflakes.

Download the project

The full source for this tutorial is available for both iPhone & iPad. Download it here.