Using the Tween Class

July 2nd, 2007 | Posted in Flash & ActionScript, Tutorials

In the past, if you wanted to create a bouncing animation using code, you’d spend hours pouring over physics equations and adjusting variables until you got it just right. By using the Tween class instead, you can create the same effect with just a few lines of code, and skip the high school physics review. A recent project gave me a chance to play with the Tween class, a relatively obscure set of scripts that can be used to create varying programmatic animation.

Important note: This tutorial will be written using ActionScript 3 and Flash CS3.

Understanding the Tween class

The Tween class lets you move, resize, rotate, or fade a movieclip using only ActionScript. You can animate any property of a movieclip, such as x, y, rotation, scaleX, scaleY, and alpha. You can also specify how long the animation will last in either seconds or frames. The code will follow this example:

new Tween(obj, prop, func, begin, finish, duration, useSeconds)

The Tween constructor function accepts these parameters:

1. obj – The instance name of the movieclip that you want to animate.
2. prop – The property of the movieclip that you want to change, such as x or alpha, as a text string.
3. func – The type of easing you want to apply to the animation to change its acceleration.
4. begin – The starting value of the property being animated.
5. finish – The ending value of the property being animated.
6. duration: – How long the animation will take, either in frames or seconds.
7. useSeconds – If your duration is in seconds, set this to true. If your duration is in frames, set this to false.

Before using the Tween class, you’ll need to import the classes into your code. Here’s what the ActionScript would look like to animate a banana movieclip from left to right across the stage within three seconds:

import fl.transitions.Tween;
import fl.transitions.easing.*;
 
var myTween:Tween = new Tween(banana_mc, "x", Elastic.easeOut, 50, 450, 3, true);

Isn’t that much cleaner and easier that doing the math yourself? First, the two import lines make these classes available to us. Keep in mind that import statements must be at the top of all of your actions. Then we tell Flash to create a new Tween instance called myTween, and using the model above, we’re telling Flash to animate the movieclip banana_mc along the x axis, from position 50 to position 450 in three seconds. We’re using the Elastic.easeOut function, one of several options to control the acceleration of the animation.

Click the play button below to see the result:

If you have JavaScript enabled, you will see the example here.

Easing options

The banana uses Elastic.easeOut to create an overshoot effect at the end of the animation, but there are several other options to add lifelike movement to your tweens. You can select an Easing class from these choices:

• Back – Causes the animation to overshoot, and return to its position.
• Bounce – Causes the animation to reverse direction, like a ball bouncing on a floor.
• Elastic – Causes the animation to overshoot and reverse, like at the end of a rubber band.
• Regular – Accelerates along a steady curve.
• Strong – Accelerates along a steady curve, more aggressive than Regular.
• None – Results in no acceleration; a steady speed.

Then, you pair any Easing class with an easing function to control which end of the tween (beginning, ending, or both) is affected:

• easeIn – The ease is applied to the beginning of the tween.
• easeInOut – The ease is applied to bothe the beginning and the end of the tween.
• easeOut – The ease is applied to the end of the tween.

Combinations such as Bounce.easeOut or Strong.easeIn result in different effects. Click each of the buttons below to see the effect that each Easing class creates.

If you have JavaScript enabled, you will see the example here.

Controlling Tween playback

You can alter the Tween’s playback by using any of several methods:

• continueTo(finish, duration) – Instructs the animation to continue tweening from its current animation point to a new finish and duration point.
• fforward() – Fast-forwards to the end of the animation.
• nextFrame() – Forwards a stopped animation to the next frame.
• prevFrame() – Reverses a stopped animation to its previous frame.
• resume() – Plays an animation that has been stopped.
• start() – Plays an animation from its begin value.
• stop() – stops the animation.
• yoyo() – Plays the animation in reverse.

Flash will begin playing the animation the moment that the Tween is instantiated. Using the above code on its own would trigger the animation the instant that the animation is loaded, or the moment that the frame with the code is reached. If you would rather have the effect wait for some user input, such as a button click, you could stop the Tween, and then start it from within an Event handler, like this:

myTween.stop();
 
play_btn.addEventListener(MouseEvent.CLICK, moveBanana);
function moveBanana(e:MouseEvent):void{
	myTween.start();
}

Allowing the Tween to trigger additional code

The Tween class has several events that can be used to detect what the tween is currently doing:

• MOTION_CHANGE – Indicates when the animation has changed.
• MOTION_FINISH – Indicated the animation is complete.
• MOTION_LOOP – Indicates the animation has started again in looping mode.
• MOTION_RESUME – Indicates that the animation has been resumes after being paused.
• MOTION_START – Indicates that the animation has started.
• MOTION_STOP – Indicates that the animation has stopped.

For instance, you could reset the banana to its original position once the animation is complete. First, import the TweenEvent class using another import statement at the top of your code:

import fl.transitions.TweenEvent;

Then, add the following code to wait for the motion to finish and reset the banana_mc movieclip’s x value to 30.

myTween.addEventListener(TweenEvent.MOTION_FINISH, handleReset);
 
function handleReset(e:TweenEvent):void {
	banana_mc.x = 30;
}

Download the Demo FLA

For more information on the Tween class, please see the excellent Adobe documentation for Flash CS3 or Flash 8.