actionscript 3.0 for journalists

Tween Class

The Tween class is a piece of code that allows you to animate objects using ActionScript. Using the Tween class to animate an object requires only one line of code, however that one line requires multiple arguments.

Before you can use the Tween class, you must import the code in so it can be available to you. Flash automatically includes several classes that are commonly used by most people, however the Tween class (and several others) have to be manually imported. This is a way to reduce the overall size of Flash projects by not including unnecessary classes.

To import the Tween class, include the following two lines of code:

import fl.transitions.Tween;
import fl.transitions.easing.*;

You only have to include these two lines of code once for each Flash document that uses the Tween class. The class will be available to you throughout the rest of your Flash document. The second line of code has an asterisk ( * ) at the end which is a wild card and means that you will import all of the easing classes.

Using the Tween class

The Tween class has several parts. Here is a list of the arguments required to use the Tween class:

new Tween( [object], "[property]", [easing type], [from value], [to value], [how long], [use seconds?] );

  • [object] - The instance name of the object that is being animated.
  • [property] - The property being animated. Could be anything from the x value to the alpha. Must be in quotes! Some examples are "alpha" "x" "y" "scaleX" and "scaleY."
  • [easing type] - The easing type of how the animation will accelerate or decelerate. (see easing section below)
  • [from value] - The starting value of the property that is being animated.
  • [to value] - The ending value of the property that is being animated.
  • [how long] - How long the animation will take to play. Either in frames or seconds.
  • [use seconds?] - Should the previous [how long?] parameter refer to seconds or frames? If this is set to true, it will use seconds, if it is set to false it will use frames.

Let's take a look at an example of a line of code that will animate a movieclip symbol called ball_mc from an x value of 50 to 400 in one second.

new Tween(ball_mc, "x", Strong.easeOut, 50, 400, 1, true);

 

You can animate a number of properties, like the alpha. This allows you to fade movieclips in and out in your Flash project.

new Tween(ball_mc, "alpha", Strong.easeOut, 1, 0, 2, true);

 

Easing Class Options

Performing animations is pretty straightforward with the Tween class. But what about the easing animations? The easing signifies how the animation accelerates or decelerates. There are six easing types and four ways to show those easing types. Here are the easing types:

Easing Types
Type Description
Back The animation goes past the ending or starting value and snaps back.
Bounce The animation bounces from the starting or ending value, like a ball on a basketball court.
Elastic Like the Back easing type, but with a much more spring-like effect. Goes past the starting or ending value, then springs back and forth.
None No easing. Only use with easeNone.
Regular A standard acceleration or deceleration.
Strong A more pronounced acceleration or deceleration.

Below are four ways to display each of these six easing types. You can pair up any of the six easing types with one of the following properties for describing how the easing will display.

Easing Properties
Property Description
easeIn The easing is at the beginning of the animation, and will accelerate until the end.
easeOut The easing is at the end of the animation, and will decelerate until the end.
easeInOut The easing is at both the beginning and end of the animation. It will accelerate until half way through the animation, then begin to decelerate and finish with the easing.
easeNone No easing. Only use with None ease type.

Examples

The best way to understand the combinations of easing types is to see examples. Here are a few examples of the different easing types.

Strong.easeIn
The animation starts slowly and begins to accelerate through the animation.

 

Strong.easeOut
The animation starts quickly and slows down (decelerate) through the animation.

 

Strong.easeInOut
The animation includes elements from the previous two. It accelerates until half way, then starts to decelerate in the second half of the animation.

 

Tweens not completing when they are declared inside functions

A common issue with tweens occurs when you try to declare a tween inside a function. In Flash ActionScript 3.0, new garbage collection features will delete variables that are inside of functions once the function completes. To prevent this from happening, you should declare a variable first outside the function, so that they will be available globally and Flash will not delete them. Once you are done with the tween, you can delete the variable yourself. This only happens when you are running a tween inside a function. Here is an example of the correct way to do this.

//declare your variable outside the function 
var myTween:Tween;   
function startTween(e:Event):void { 
        //assign the tween to the variable 
        myTween = new Tween(ball_mc, "x", Strong.easeOut, 50, 400, 2, true); 
 }

Tween Events and methods

The Tween class, like any class, has a series of properties and events that extend its functionality beyond standard animation. A full document of the Tween class can be found on the Adobe Web help documentation.

There is a list of several methods on the Adobe Website, but this tutorial will only show three of the most commonly used events.

  • TweenEvent.MOTION_FINISH - Triggered once the animation completes. This is very useful for triggering actions that you want to occur after a tween has completed.
  • TweenEvent.MOTION_STOP - Triggered any time the animation stops. You can stop the animation (even half way through) using the stop() method.
  • TweenEvent.MOTION_RESUME - Triggered if you have stopped the tween using stop(); and restart the animation using the resume(); method.

The MOTION_FINISH tends to be one of the more common events. It is used generally to execute a function after a Tween has completed. However, to use any of these events, you must attach them to a variable. This requires you to declare a variable for your Tween. Once you declare your variable, you can use this variable to add the event listener. (Make sure your event listener comes after you declare your variable, otherwise Flash will throw an error.)

import fl.transitions.Tween; 
import fl.transitions.easing.Strong; 
import fl.transitions.TweenEvent;  

var animation:Tween = new Tween(ball_mc, "x", Strong.easeOut, 50, 400, 2, true);  
animation.addEventListener(TweenEvent.MOTION_FINISH, playAfterDone);  

function playAfterDone(e:Event):void { 
      trace("Tween is done"); 
}

Notice the third import line import fl.transitions.TweenEvent; This is required to include the class necessary to run Tween Events. In the example, the tween is assigned to the variable animation, and is used for our event handler. Once the Tween is finished, it will run the playAfterDone function.

Methods of the Tween class

The tween class has several methods that allow you to perform functions such as stopping your tween while it is playing, resuming the tween, rewinding the tween to the beginning after it has completed, or even having the tween play in reverse. Here is a list of some of the more common tween methods.

Tween Methods
Method Description
yourTweenVariable.stop() Stops the tween if it's currently playing, otherwise it does nothing. Useful if you want to stop an animation before it completes.
yourTweenVariable.start() Starts the tween from the beginning, even if you stopped it using the stop() method.
yourTweenVariable.resume() Resumes the tween from the current point in which it was stopped using the stop() method.
yourTweenVariable.rewind() Rewind is useful to put the animation back to its starting position once it completes. It does not play the animation again.
yourTweenVariable.fforward() The opposite of rewind(), and much like the stop() method this method will instantly end the animation to the last frame. Could be useful in situations where you want to allow the user to skip a long animation.
yourTweenVariable.yoyo() Plays the animation in reverse.