View comments | RSS feed
Packagefl.transitions
Classpublic class Tween
InheritanceTween Inheritance EventDispatcher Inheritance Object

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

The Tween class lets you use ActionScript to move, resize, and fade movie clips by specifying a property of the target movie clip to animate over a number of frames or seconds.

The Tween class also lets you specify a variety of easing methods. "Easing" refers to gradual acceleration or deceleration during an animation, which helps your animations appear more realistic. The fl.transitions.easing package provides many easing methods that contain equations for this acceleration and deceleration, which change the easing animation accordingly.

To use the methods and properties of the Tween class, you use the new operator with the constructor function to create an instance of the class, and you specify an easing method as a parameter. For example:

 import fl.transitions.Tween;
 import fl.transitions.easing.*;
 var myTween:Tween = new Tween(myObject, "x", Elastic.easeOut, 0, 300, 3, true);
 

See also

fl.transitions.TransitionManager
fl.transitions.easing
Tween()


Public Properties
 PropertyDefined By
  begin : Number = NaN
The initial value of the target object's designated property before the tween starts.
Tween
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  duration : Number
The duration of the tweened animation in frames or seconds.
Tween
  finish : Number
A number indicating the ending value of the target object property that is to be tweened.
Tween
  FPS : Number
The number of frames per second calculated into the tweened animation.
Tween
  func : Function
The easing function which is used with the tween.
Tween
  isPlaying : Boolean = false
Indicates whether the tween is currently playing.
Tween
  looping : Boolean = false
Indicates whether the tween will loop.
Tween
  obj : Object = null
The target object that is being tweened.
Tween
  position : Number
The current value of the target object property being tweened.
Tween
  prop : String = ""
The name of the property affected by the tween of the target object.
Tween
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  time : Number
The current time within the duration of the animation.
Tween
  useSeconds : Boolean = false
Indicates whether the tween plays over a period of frames or seconds.
Tween
Public Methods
 MethodDefined By
  
Tween(obj:Object, prop:String, func:Function, begin:Number, finish:Number, duration:Number, useSeconds:Boolean = false)
Creates an instance of the Tween class.
Tween
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
EventDispatcher
  
continueTo(finish:Number, duration:Number):void
Instructs the tweened animation to continue tweening from its current animation point to a new finish and duration point.
Tween
 Inherited
Dispatches an event into the event flow.
EventDispatcher
  
Forwards the tweened animation directly to the final value of the tweened animation.
Tween
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
Forwards the tweened animation to the next frame of an animation that was stopped.
Tween
  
Plays the previous frame of the tweened animation from the current stopping point of an animation that was stopped.
Tween
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
  
Resumes the play of a tweened animation that has been stopped.
Tween
  
Moves the play of a tweened animation back to its starting value.
Tween
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
  
Starts the play of a tweened animation from its starting point.
Tween
  
Stops the play of a tweened animation at its current value.
Tween
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
  
Instructs the tweened animation to play in reverse from its last direction of tweened property increments.
Tween
Events
 Event Summary Defined By
 InheritedDispatched when Flash Player or an AIR application gains operating system focus and becomes active.EventDispatcher
 InheritedDispatched when Flash Player or an AIR application loses operating system focus and is becoming inactive.EventDispatcher
   Indicates that the Tween has changed and the screen has been updated.Tween
   Indicates that the Tween has reached the end and finished.Tween
   Indicates that the Tween has restarted playing from the beginning in looping mode.Tween
   Indicates that the Tween has resumed playing after being paused.Tween
   Indicates that the motion has started playing.Tween
   Indicates that the Tween has been stopped with an explicit call to Tween.stop().Tween
Property Detail
beginproperty
public var begin:Number = NaN

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

The initial value of the target object's designated property before the tween starts.

durationproperty 
duration:Number  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

The duration of the tweened animation in frames or seconds. This property is set as a parameter when creating a new Tween instance or when calling the Tween.yoyo() method.


Implementation
    public function get duration():Number
    public function set duration(value:Number):void
finishproperty 
finish:Number  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

A number indicating the ending value of the target object property that is to be tweened. This property is set as a parameter when creating a new Tween instance or when calling the Tween.yoyo() method.


Implementation
    public function get finish():Number
    public function set finish(value:Number):void

See also

FPSproperty 
FPS:Number  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

The number of frames per second calculated into the tweened animation. By default the current Stage frame rate is used to calculate the tweened animation. Setting this property recalculates the number of increments in the animated property that is displayed each second to the Tween.FPS property rather than the current Stage frame rate. Setting the Tween.FPS property does not change the actual frame rate of the Stage.

Note: The Tween.FPS property returns undefined unless it is first set explicitly.


Implementation
    public function get FPS():Number
    public function set FPS(value:Number):void
funcproperty 
public var func:Function

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

The easing function which is used with the tween.

isPlayingproperty 
public var isPlaying:Boolean = false

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Indicates whether the tween is currently playing.

loopingproperty 
public var looping:Boolean = false

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Indicates whether the tween will loop. If the value is true, the tween will restart indefinitely each time the tween has completed. If the value is false, the tween will play only once.

objproperty 
public var obj:Object = null

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

The target object that is being tweened.

positionproperty 
position:Number  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

The current value of the target object property being tweened. This value updates with each drawn frame of the tweened animation.


Implementation
    public function get position():Number
    public function set position(value:Number):void
propproperty 
public var prop:String = ""

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

The name of the property affected by the tween of the target object.

timeproperty 
time:Number  [read-write]

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

The current time within the duration of the animation.


Implementation
    public function get time():Number
    public function set time(value:Number):void
useSecondsproperty 
public var useSeconds:Boolean = false

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Indicates whether the tween plays over a period of frames or seconds. A value of true will cause the tween to animate over a period of seconds specified by the duration property. A value of false will cause the tween to animate over a period of frames.

Constructor Detail
Tween()Constructor
public function Tween(obj:Object, prop:String, func:Function, begin:Number, finish:Number, duration:Number, useSeconds:Boolean = false)

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Creates an instance of the Tween class. Use the constructor function with the new operator: var myTween:Tween = new Tween().

Parameters
obj:Object — Object that the Tween targets.
 
prop:String — Name of the property (obj parameter value) that will be affected.
 
func:Function — Name of the easing function to use.
 
begin:Number — Starting value of the prop parameter.
 
finish:Number — A number indicating the ending value of prop parameter (the target object property to be tweened).
 
duration:Number — Length of time of the motion; set to infinity if negative or omitted.
 
useSeconds:Boolean (default = false) — A flag specifying whether to use seconds instead of frames. The function uses seconds if true or frames in relation to the value specified in the duration parameter if false.

See also

Method Detail
continueTo()method
public function continueTo(finish:Number, duration:Number):void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Instructs the tweened animation to continue tweening from its current animation point to a new finish and duration point.

Parameters

finish:Number — A number indicating the ending value of the target object property that is to be tweened.
 
duration:Number — A number indicating the length of time or number of frames for the tween motion; duration is measured in length of time if the Tween.start() useSeconds parameter is set to true, or measured in frames if it is set to false.

See also

fforward()method 
public function fforward():void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Forwards the tweened animation directly to the final value of the tweened animation.

nextFrame()method 
public function nextFrame():void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Forwards the tweened animation to the next frame of an animation that was stopped. Use this method to forward a frame at a time of a tweened animation after you use the Tween.stop() method to stop it.

Note: Use this method on frame-based tweens only. A tween is set to frame based at its creation by setting the useSeconds parameter to false.

prevFrame()method 
public function prevFrame():void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Plays the previous frame of the tweened animation from the current stopping point of an animation that was stopped. Use this method to play a tweened animation backwards one frame at a time after you use the Tween.stop() method to stop it.

Note: Use this method on frame-based tweens only. A tween is set to frame based at its creation by setting the Tween.start() useSeconds parameter to false.

See also

resume()method 
public function resume():void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Resumes the play of a tweened animation that has been stopped. Use this method to continue a tweened animation after you have stopped it by using the Tween.stop() method.

Note: Use this method on frame-based tweens only. A tween is set to be frame based at its creation by setting the useSeconds parameter to false.

rewind()method 
public function rewind(t:Number = 0):void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Moves the play of a tweened animation back to its starting value. If Tween.rewind() is called while the tweened animation is still playing, the animation rewinds to its starting value and continues playing. If Tween.rewind() is called while the tweened animation has been stopped or has finished its animation, the tweened animation rewinds to its starting value and remains stopped. Use this method to rewind a tweened animation to its starting point after you have stopped it by using the Tween.stop() method or to rewind a tweened animation during its play.

Parameters

t:Number (default = 0) — Starting value.

start()method 
public function start():void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Starts the play of a tweened animation from its starting point. This method is used for restarting a Tween from the beginning of its animation after it stops or has completed its animation.

stop()method 
public function stop():void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Stops the play of a tweened animation at its current value.

yoyo()method 
public function yoyo():void

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Instructs the tweened animation to play in reverse from its last direction of tweened property increments. If this method is called before a Tween object's animation is complete, the animation abruptly jumps to the end of its play and then plays in a reverse direction from that point. You can achieve an effect of an animation completing its entire play and then reversing its entire play by calling the Tween.yoyo() method within a TweenEvent.MOTION_FINISH event handler. This process ensures that the reverse effect of the Tween.yoyo() method does not begin until the current tweened animation is complete.

Event Detail
motionChange Event
Event Object Type: fl.transitions.TweenEvent
TweenEvent.type property = fl.transitions.TweenEvent.MOTION_CHANGE

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Indicates that the Tween has changed and the screen has been updated.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelablefalse
currentTargetThe object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget property.
targetThe object that dispatched the event; it is not always the object listening for the event. Use the currentTarget property to always access the object listening for the event.
timeThe time of the Tween when the event occurred.
positionThe value of the property controlled by the Tween, when the event occurred.
motionFinish Event  
Event Object Type: fl.transitions.TweenEvent
TweenEvent.type property = fl.transitions.TweenEvent.MOTION_FINISH

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Indicates that the Tween has reached the end and finished.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelablefalse
currentTargetThe object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget property.
targetThe object that dispatched the event; it is not always the object listening for the event. Use the currentTarget property to always access the object listening for the event.
timeThe time of the Tween when the event occurred.
positionThe value of the property controlled by the Tween, when the event occurred.
motionLoop Event  
Event Object Type: fl.transitions.TweenEvent
TweenEvent.type property = fl.transitions.TweenEvent.MOTION_LOOP

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Indicates that the Tween has restarted playing from the beginning in looping mode.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelablefalse
currentTargetThe object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget property.
targetThe object that dispatched the event; it is not always the object listening for the event. Use the currentTarget property to always access the object listening for the event.
timeThe time of the Tween when the event occurred.
positionThe value of the property controlled by the Tween, when the event occurred.
motionResume Event  
Event Object Type: fl.transitions.TweenEvent
TweenEvent.type property = fl.transitions.TweenEvent.MOTION_RESUME

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Indicates that the Tween has resumed playing after being paused.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelablefalse
currentTargetThe object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget property.
targetThe object that dispatched the event; it is not always the object listening for the event. Use the currentTarget property to always access the object listening for the event.
timeThe time of the Tween when the event occurred.
positionThe value of the property controlled by the Tween, when the event occurred.
motionStart Event  
Event Object Type: fl.transitions.TweenEvent
TweenEvent.type property = fl.transitions.TweenEvent.MOTION_START

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Indicates that the motion has started playing.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelablefalse
currentTargetThe object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget property.
targetThe object that dispatched the event; it is not always the object listening for the event. Use the currentTarget property to always access the object listening for the event.
timeThe time of the Tween when the event occurred.
positionThe value of the property controlled by the Tween, when the event occurred.
motionStop Event  
Event Object Type: fl.transitions.TweenEvent
TweenEvent.type property = fl.transitions.TweenEvent.MOTION_STOP

Language Version : ActionScript 3.0
Runtime Versions : AIR 1.0, Flash Player 9

Indicates that the Tween has been stopped with an explicit call to Tween.stop().

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelablefalse
currentTargetThe object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget property.
targetThe object that dispatched the event; it is not always the object listening for the event. Use the currentTarget property to always access the object listening for the event.
timeThe time of the Tween when the event occurred.
positionThe value of the property controlled by the Tween, when the event occurred.




 


Comments


No screen name said on May 5, 2007 at 7:14 AM :
Has anyone else experienced freezing with these tweens?

I figured at first they would freeze when the variable would loose scope, but now they just seem to break randomly.
KeenoChris said on Jun 7, 2007 at 8:05 AM :
I have this problem also, i am running 3 tweens on a MC (x, y and rotate). Sometimes its fine; others it just stops dead on the screen (the MOTION_FINISHED does not get called)

im not really doing much else
thegamemaker said on Jul 2, 2007 at 2:37 PM :
agreed TweenEvent.MOTION_FINISH occasionally does not fire and it drives me nuts.
No screen name said on Jul 2, 2007 at 9:37 PM :
Yeah i have this problem also.
djtechwriter said on Jul 5, 2007 at 4:29 PM :
If you store the Tween in a local variable (within a function), the variable may be garbage collected before the completion of the scripted motion. The Tween object needs to exist throughout the duration of the motion and should be declared in a larger scope.
No screen name said on Aug 3, 2007 at 6:46 AM :
How can I get access to the fl.transitions package. It is not accessible by default in my Eclipse environment after having installed the flex builder plug-in.
Robert Penner said on Aug 6, 2007 at 2:52 PM :
The fl.transitions package comes with Flash CS3.
No screen name said on Aug 24, 2007 at 12:29 AM :
> djtechwriter

i have my tween variable declared in class property (which is like global prop for that class). in function i fire new tweens: tween = new Tween(...) in "for" loop about 20 times. tweens crashes also, like other pip says.

any suggestions?
Robert Penner said on Aug 28, 2007 at 2:37 PM :
It sounds like you are creating 20 tweens, but only using one property. Each tween needs to be stored in its own property, so it can continue to exist.
ADI D said on Sep 17, 2007 at 2:01 AM :
maybe You wright... so U see any idea how to start and operate dynamic number of tweens (20-100)?
Robert Penner said on Sep 18, 2007 at 3:32 PM :
For a dynamic number of Tween objects, create an array and store them there.
JoshuaSullivan said on Oct 11, 2007 at 6:55 AM :
I've been banging my head against the "freezing tween" problem for a week now. Thank you for pointing out the garbage collection issue. Still, that shouldn't be happening if the tween has an event listener attached to it, should it?
swartz1999 said on Oct 11, 2007 at 5:54 PM :
Even if there is an event listener registered for an object, the object may be garbage collected if it is a local variable (within the scope of a function). To prevent this, declare the variable globally, as in the following:

var myTween:Tween;

function someFunction()
{
myTween = new Tween(myObject, "x", Elastic.easeOut, 0, 300, 3, true);
myTween.addEventListener(TweenEvent.MOTION_FINISH, listenerFunction);
// ...
}
No screen name said on Nov 1, 2007 at 9:14 AM :
So the only way around this problem is to set up (in my case) 300 tween vars, and then refer to each one in my loops? This is such a step backwards from 2.0.... I will be shopping for another Tween solution, because this new 3.0 method is obviously not built for handling multiple tweens easily.
intrinicity2 said on Nov 5, 2007 at 6:14 PM :
I too, am having the freezing problem and it is NOT fixed by declaring the Tween variable outside the scope of the calling function. About 20-ish iterations in to it and the tweens start failing to complete (not all, just most). A solution was suggested (by Robert Penner) to create many tween variables ), so that each iteration has its own, and store them in array.

I have struggled with this notion for a while now without success (generating dynamic variable names in AS3 is another task that's appears to have become more difficult than in its predecessor).

Could someone please post (and subsequently add to the documentation) a working example of how to generate multiple tweens rapidly, such that they complete.

Thanks
intrinicity2 said on Nov 5, 2007 at 6:31 PM :
As is often the case, you fire off a plea for help and then solve it within minutes of clicking submit.

Ignoring the details of the tween itself - this seemed to work fine:

this["aTween"+i] = new Tween(evt.target.loader, "alpha", Strong.easeOut, 0, 1, 2, true);
this["xTween"+i] = new Tween(evt.target.loader, "x", Regular.easeOut, evt.target.loader.x, numx*102+((stage.stageWidth-612)/2), 1.5, true);
this["yTween"+i] = new Tween(evt.target.loader, "y", Regular.easeIn, evt.target.loader.y, numy*34+((stage.stageHeight-136)/2), 1.5, true);

No tween variables defined elsewhere and no "var" in the statment... I'm actually a bit surprised that I could get away with it, AS3 being so strict on variable definition and all ...
nopaper said on Dec 3, 2007 at 10:18 AM :
It seems that a motionStop event is being dispatched even if the Tween has
normally finished (without an explicit call to tween.stop()). I found this when i
attached a listener to motionStop which removed all the listeners and
another one to motionFinished. Even if the tween would normally finish, the
listeners would all be removed before the motionFinished event is
dispatched.
No screen name said on Feb 26, 2008 at 1:07 PM :
Here is my 2 cents because I couldn't find a decent explanation anywhere. Please read and add your comments!

PROBLEM
Tweens finish early because they get randomly garbage collected


SOLUTION
Some form of reference that prevents garbage collection BUT does allow garbage collection when appropriate.

(Note the last part you don't want your Flash to clog up memory after executing for a long period of time)

Some people state declaring each tween globally (sometimes doesn't work?) others have made each tween a property of some global object. This is my solution for handling many tweens...


MY SOLUTION
//Anti Garbage Collection for Tweens
var antiGC:Dictionary = new Dictionary(false);

//Function with two tweens
function zoomIn(){
var scale:Number = diagram_mc.scaleX *1.12;

var xT:Tween = new Tween(diagram_mc, "scaleX",Strong.easeOut, diagram_mc.scaleX, scale, 5);
xT.addEventListener(TweenEvent.MOTION_FINISH, tweenFinished);
antiGC[xT] = xT;

var yT:Tween = new Tween(diagram_mc, "scaleY",Strong.easeOut, diagram_mc.scaleY, scale, 5);
yT.addEventListener(TweenEvent.MOTION_FINISH, tweenFinished);
antiGC[yT] = yT;


}

//Allows Garbage Collection
function tweenFinished(e:TweenEvent){

antiGC[e.currentTarget] = null; //GC Object
delete antiGC[e.currentTarget]; //GC Key

}

EXPLANATION

-Global dictionary with strong references will not be garbage collected
-Local tweens ok (e.g. in functions)
-...because tweens are stored in the dictionary
-EventListener triggers a global function to remove all references once finished
-...removing references allows garbage collection to do what it does

Note if you want your own MOTION_FINISH listener just remember to call the tweenFinished function



I'm no Flash or ActionScript expert, but I haven't seen anything tidier that is scalable and allows appropriate garbage collection.

Enjoy
OrbitalFlex said on Feb 27, 2008 at 2:16 PM :
I just ran across the issue of tweens stopping prematurely and would like to confirm swartz1999's solution. I had initially declared them local to a method within the object. I simply moved the tween variables out to become properties of the object itself. As long as the object is in play, so are it's tweens. All tweens now execute as expected.
ryanmagnon said on Apr 7, 2008 at 3:12 PM :
If you're still having a problem, you'll also check to make sure the object that the tween is a property of is not also being garbage collected due to scope or something else.
MythosVylok said on Apr 28, 2008 at 9:59 AM :
This worked for me:

TransitionManager.start(r_mc, {type:Zoom, direction:0, duration:1, easing: Strong.easeOut});
No screen name said on Jul 6, 2008 at 6:12 PM :
I had a similar problem with tweens freezing when using them to fade in an externalswf loader. Declaring the variable globally solved the problem and I haven't had a frozen fade since.

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/fl/transitions/Tween.html