API Documentation | All Packages | All Classes | Index | Frames No Frames |
Class TweenLite

Package | com.greensock
Class | public class TweenLite
Inheritance | TweenLite TweenCore
Subclasses | TweenMax

TweenLite is an extremely fast, lightweight, and flexible tweening engine that serves as the foundation of the GreenSock Tweening Platform. A TweenLite instance handles tweening one or more numeric properties of any object over time, updating them on every frame. Sounds simple, but there's a wealth of capabilities and conveniences at your fingertips with TweenLite. With plenty of other tweening engines to choose from, here's why you might want to consider TweenLite:

- SPEED - TweenLite has been highly optimized for maximum performance. See some speed comparisons yourself at http://www.greensock.com/tweening-speed-test/
- Feature set - In addition to tweening ANY numeric property of ANY object, TweenLite can tween filters, hex colors, volume, tint, frames, and even do bezier tweening, plus LOTS more. TweenMax extends TweenLite and adds even more capabilities like repeat, yoyo, repeatDelay, timeScale, event dispatching, on-the-fly destination value updates, rounding and more. Overwrite management is an important consideration in a tweening engine as well which is another area where the GreenSock Tweening Platform shines. You have options for AUTO overwriting or you can manually define how each tween will handle overlapping tweens of the same object.
- Expandability - With its plugin architecture, you can activate as many (or as few) features as your project requires. Write your own plugin to handle particular special properties in custom ways. Minimize bloat, and maximize performance.
- Sequencing, grouping, and management features - TimelineLite and TimelineMax make it surprisingly simple to create complex sequences or groups of tweens that you can control as a whole. play(), pause(), restart(), or reverse(). You can even tween a timeline's `currentTime` or `currentProgress` property to fastforward or rewind the entire timeline. Add labels, gotoAndPlay(), change the timeline's timeScale, nest timelines within timelines, and lots more.
- Ease of use - Designers and Developers alike rave about how intuitive the platform is.
- Updates - Frequent updates and feature additions make the GreenSock Tweening Platform reliable and robust.
- AS2 and AS3 - Most other engines are only developed for AS2 or AS3 but not both.

SPECIAL PROPERTIES (no plugins required): The following special properties can be defined in the `vars` parameter which can be either a generic Object or a `TweenLiteVars` instance:

- delay : Number Amount of delay in seconds (or frames for frames-based tweens) before the tween should begin.
- useFrames : Boolean If useFrames is set to true, the tweens's timing mode will be based on frames. Otherwise, it will be based on seconds/time. NOTE: a tween's timing mode is always determined by its parent timeline.
- ease : Function Use any standard easing equation to control the rate of change. For example, `Elastic.easeOut`. The Default is Quad.easeOut.
- easeParams : Array An Array of extra parameters to feed the easing equation. This can be useful when using an ease like `Elastic` and want to control extra parameters like the amplitude and period. Most easing equations, however, don't require extra parameters so you won't need to pass in any easeParams.
- immediateRender : Boolean Normally when you create a tween, it begins rendering on the very next frame (when the Flash Player dispatches an ENTER_FRAME event) unless you specify a `delay`. This allows you to insert tweens into timelines and perform other actions that may affect its timing. However, if you prefer to force the tween to render immediately when it is created, set `immediateRender` to true. Or to prevent a tween with a duration of zero from rendering immediately, set `immediateRender` to false.
- onInit : Function A function that should be called just before the tween inits (renders for the first time). Since onInit runs before the start/end values are recorded internally, it is a good place to run code that affects the target's initial position or other tween-related properties. onStart, by contrast, runs AFTER the tween inits and the start/end values are recorded internally. onStart is called every time the tween begins which can happen more than once if the tween is restarted multiple times.
- onInitParams : Array An Array of parameters to pass the onInit function.
- onStart : Function A function that should be called when the tween begins (when its currentTime is at 0 and changes to some other value which can happen more than once if the tween is restarted multiple times).
- onStartParams : Array An Array of parameters to pass the onStart function.
- onUpdate : Function A function that should be called every time the tween's time/position is updated (on every frame while the tween is active)
- onUpdateParams : Array An Array of parameters to pass the onUpdate function
- onComplete : Function A function that should be called when the tween has finished
- onCompleteParams : Array An Array of parameters to pass the onComplete function
- onReverseComplete : Function A function that should be called when the tween has reached its starting point again after having been reversed.
- onReverseCompleteParams : Array An Array of parameters to pass the onReverseComplete function
- paused : Boolean If true, the tween will be paused initially.
- overwrite : int Controls how (and if) other tweens of the same target are overwritten by this tween. There are several modes to choose from, but only the first two are available in TweenLite unless `OverwriteManager.init()` has been called (please see http://www.greensock.com/overwritemanager/ for details and a full explanation of the various modes):
  - NONE (0) (or false)
  - ALL_IMMEDIATE (1) (or true) - this is the default mode in TweenLite
  - AUTO (2) - this is the default mode if TweenMax, TimelineLite, or TimelineMax is used in the swf. (these classes automatically init() OverwriteManager if you haven't done so already)
  - CONCURRENT (3) (requires OverwriteManager)
  - ALL_ONSTART (4) (requires OverwriteManager)
  - PREEXISTING (5) (requires OverwriteManager)

Note: Using a `TweenLiteVars` instance instead of a generic object to define your `vars` is a bit more verbose but provides code hinting and improved debugging because it enforces strict data typing. Use whichever one you prefer.
PLUGINS:
There are many plugins that add capabilities through other special properties. Some examples are "tint", "volume", "frame", "frameLabel", "bezier", "blurFilter", "colorMatrixFilter", "hexColors", and many more. Adding the capabilities is as simple as activating the plugin with a single line of code, like TweenPlugin.activate([TintPlugin]); Get information about all the plugins at http://www.TweenLite.com
EXAMPLES:
Please see http://www.tweenlite.com for examples, tutorials, and interactive demos.
NOTES / TIPS:

- The base TweenLite class adds about 4.7kb to your compressed swf (if no plugins are activated)
- Passing values as Strings will make the tween relative to the current value. For example, if you do `TweenLite.to(mc, 2, {x:"-20"});` it'll move the mc.x to the left 20 pixels which is the same as doing `TweenLite.to(mc, 2, {x:mc.x - 20});` You could also cast it like: `TweenLite.to(mc, 2, {x:String(myVariable)});`
- You can change the `TweenLite.defaultEase` function if you prefer something other than `Regular.easeOut`.
- Kill all tweens for a particular object anytime with the `TweenLite.killTweensOf(mc);`
- You can kill all delayedCalls to a particular function using `TweenLite.killDelayedCallsTo(myFunction);` This can be helpful if you want to preempt a call.
- Use the `TweenLite.from()` method to animate things into place. For example, if you have things set up on the stage in the spot where they should end up, and you just want to animate them into place, you can pass in the beginning x and/or y and/or alpha (or whatever properties you want).
- If you find this class useful, please consider joining Club GreenSock which not only helps to sustain ongoing development, but also gets you bonus plugins, classes and other benefits that are ONLY available to members. Learn more at http://www.greensock.com/club/

Copyright 2011, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for corporate Club GreenSock members, the software agreement that was issued with the corporate membership.

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined by
--- | --- | ---
|  | currentTime : Number Most recently rendered time (or frame for frames-based tweens/timelines) according to its `duration`. | TweenCore
|  | data : * Place to store any data you want. | TweenCore
|  | defaultEase : Function [static] Provides an easy way to change the default easing equation. | TweenLite
|  | delay : Number Length of time in seconds (or frames for frames-based tweens/timelines) before the tween should begin. | TweenCore
|  | duration : Number Duration of the tween in seconds (or frames for frames-based tweens/timelines) not including any repeats or repeatDelays. | TweenCore
|  | paused : Boolean Indicates the paused state of the tween/timeline. | TweenCore
|  | reversed : Boolean Indicates the reversed state of the tween/timeline. | TweenCore
|  | startTime : Number Start time in seconds (or frames for frames-based tweens/timelines), according to its position on its parent timeline | TweenCore
|  | target : Object Target object whose properties this tween affects. | TweenLite
|  | timeline : SimpleTimeline The parent timeline on which the tween/timeline is placed. | TweenCore
|  | totalDuration : Number Duration of the tween in seconds (or frames for frames-based tweens/timelines) including any repeats or repeatDelays (which are only available on TweenMax and TimelineMax). | TweenCore
|  | totalTime : Number Most recently rendered time (or frame for frames-based tweens/timelines) according to its `totalDuration`. | TweenCore
|  | vars : Object Stores variables (things like alpha, y or whatever we're tweening as well as special properties like "onComplete"). | TweenCore

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined by
--- | --- | ---
|  | TweenLite(target:Object, duration:Number, vars:Object) Constructor | TweenLite
|  | complete(skipRender:Boolean = false, suppressEvents:Boolean = false):void Forces the tween/timeline to completion. | TweenCore
|  | delayedCall(delay:Number, onComplete:Function, onCompleteParams:Array = null, useFrames:Boolean = false):TweenLite [static] Provides a simple way to call a function after a set amount of time (or frames). | TweenLite
|  | from(target:Object, duration:Number, vars:Object):TweenLite [static] Static method for creating a TweenLite instance that tweens in the opposite direction compared to a TweenLite.to() tween. | TweenLite
|  | invalidate():void Clears any initialization data (like starting values in tweens) which can be useful if, for example, you want to restart it without reverting to any previously recorded starting values. | TweenLite
|  | kill():void Kills the tween/timeline, stopping it immediately. | TweenCore
|  | killTweensOf(target:Object, complete:Boolean = false, vars:Object = null):void [static] Kills all the tweens (or certain tweening properties) of a particular object, optionally completing them first. | TweenLite
|  | killVars(vars:Object, permanent:Boolean = true):Boolean Allows particular properties of the tween to be killed. | TweenLite
|  | pause():void Pauses the tween/timeline | TweenCore
|  | play():void Starts playing forward from the current position. | TweenCore
|  | restart(includeDelay:Boolean = false, suppressEvents:Boolean = true):void Restarts and begins playing forward. | TweenCore
|  | resume():void Starts playing from the current position without altering direction (forward or reversed). | TweenCore
|  | reverse(forceResume:Boolean = true):void Reverses smoothly, adjusting the startTime to avoid any skipping. | TweenCore
|  | to(target:Object, duration:Number, vars:Object):TweenLite [static] Static method for creating a TweenLite instance. | TweenLite

Property detail

defaultEase | property

`public static var defaultEase:Function`

Provides an easy way to change the default easing equation.

target | property |

`public var target:Object`

Target object whose properties this tween affects. This can be ANY object, not just a DisplayObject.

Constructor detail

TweenLite | () | constructor

`public function TweenLite(target:Object, duration:Number, vars:Object)`

Constructor

Parameters

| `target:Object` — Target object whose properties this tween affects. This can be ANY object, not just a DisplayObject.
| `duration:Number` — Duration in seconds (or in frames if the tween's timing mode is frames-based)
| `vars:Object` — An object containing the end values of the properties you're tweening. For example, to tween to x=100, y=100, you could pass {x:100, y:100}. It can also contain special properties like "onComplete", "ease", "delay", etc.

Method detail

delayedCall | () | method

`public static function delayedCall(delay:Number, onComplete:Function, onCompleteParams:Array = null, useFrames:Boolean = false):TweenLite`

Provides a simple way to call a function after a set amount of time (or frames). You can optionally pass any number of parameters to the function too. For example:
`TweenLite.delayedCall(1, myFunction, ["param1", 2]);
function myFunction(param1:String, param2:Number):void {
trace("called myFunction and passed params: " + param1 + ", " + param2);
}`

Parameters

| `delay:Number` — Delay in seconds (or frames if useFrames is true) before the function should be called
| `onComplete:Function` — Function to call
| `onCompleteParams:Array` (default = `null`)`` — An Array of parameters to pass the function.
| `useFrames:Boolean` (default = `false`)`` — If the delay should be measured in frames instead of seconds, set useFrames to true (default is false)

Returns

| `TweenLite` — TweenLite instance

from | () | method |

`public static function from(target:Object, duration:Number, vars:Object):TweenLite`

Static method for creating a TweenLite instance that tweens in the opposite direction compared to a TweenLite.to() tween. In other words, you define the START values in the vars object instead of the end values, and the tween will use the current values as the end values. This can be very useful for animating things into place on the stage because you can build them in their end positions and do some simple TweenLite.from() calls to animate them into place. NOTE: By default, `immediateRender` is `true` in from() tweens, meaning that they immediately render their starting state regardless of any delay that is specified. You can override this behavior by passing `immediateRender:false` in the `vars` object so that it will wait to render until the tween actually begins (often the desired behavior when inserting into timelines). To illustrate the default behavior, the following code will immediately set the `alpha` of `mc` to 0 and then wait 2 seconds before tweening the `alpha` back to 1 over the course of 1.5 seconds:
`TweenLite.from(mc, 1.5, {alpha:0, delay:2});`

Parameters

| `target:Object` — Target object whose properties this tween affects. This can be ANY object, not just a DisplayObject.
| `duration:Number` — Duration in seconds (or in frames if the tween's timing mode is frames-based)
| `vars:Object` — An object containing the start values of the properties you're tweening. For example, to tween from x=100, y=100, you could pass {x:100, y:100}. It can also contain special properties like "onComplete", "ease", "delay", etc.

Returns

| `TweenLite` — TweenLite instance

invalidate | () | method |

`public override function invalidate():void`

Clears any initialization data (like starting values in tweens) which can be useful if, for example, you want to restart it without reverting to any previously recorded starting values. When you invalidate() a tween/timeline, it will be re-initialized the next time it renders and its `vars` object will be re-parsed. The timing of the tween/timeline (duration, startTime, delay) will NOT be affected. Another example would be if you have a `TweenMax(mc, 1, {x:100, y:100})` that ran when mc.x and mc.y were initially at 0, but now mc.x and mc.y are 200 and you want them tween to 100 again, you could simply `invalidate()` the tween and `restart()` it. Without invalidating first, restarting it would cause the values jump back to 0 immediately (where they started when the tween originally began). When you invalidate a timeline, it automatically invalidates all of its children.

killTweensOf | () | method |

`public static function killTweensOf(target:Object, complete:Boolean = false, vars:Object = null):void`

Kills all the tweens (or certain tweening properties) of a particular object, optionally completing them first. If, for example, you want to kill all tweens of the "mc" object, you'd do:
`TweenLite.killTweensOf(mc);
` But if you only want to kill all the "alpha" and "x" portions of mc's tweens, you'd do:
`TweenLite.killTweensOf(mc, false, {alpha:true, x:true});
` `killTweensOf()` affects tweens that haven't begun yet too. If, for example, a tween of object "mc" has a delay of 5 seconds and `TweenLite.killTweensOf(mc)` is called 2 seconds after the tween was created, it will still be killed even though it hasn't started yet.

Parameters

| `target:Object` — Object whose tweens should be immediately killed
| `complete:Boolean` (default = `false`)`` — Indicates whether or not the tweens should be forced to completion before being killed.
| `vars:Object` (default = `null`)`` — An object defining which tweening properties should be killed (null causes all properties to be killed). For example, if you only want to kill "alpha" and "x" tweens of object "mc", you'd do `myTimeline.killTweensOf(mc, true, {alpha:true, x:true})`. If there are no tweening properties remaining in a tween after the indicated properties are killed, the entire tween is killed, meaning any onComplete, onUpdate, onStart, etc. won't fire.

killVars | () | method |

`public function killVars(vars:Object, permanent:Boolean = true):Boolean`

Allows particular properties of the tween to be killed. For example, if a tween is affecting the "x", "y", and "alpha" properties and you want to kill just the "x" and "y" parts of the tween, you'd do `myTween.killVars({x:true, y:true});`

Parameters

| `vars:Object` — An object containing a corresponding property for each one that should be killed. The values don't really matter. For example, to kill the x and y property tweens, do `myTween.killVars({x:true, y:true});`
| `permanent:Boolean` (default = `true`)`` — If true, the properties specified in the vars object will be permanently disallowed in the tween. Typically the only time false might be used is while the tween is in the process of initting and a plugin needs to make sure tweens of a particular property (or set of properties) is killed.

Returns

| `Boolean` — Boolean value indicating whether or not properties may have changed on the target when any of the vars were disabled. For example, when a motionBlur (plugin) is disabled, it swaps out a BitmapData for the target and may alter the alpha. We need to know this in order to determine whether or not a new tween that is overwriting this one should be re-initted() with the changed properties.

to | () | method |

`public static function to(target:Object, duration:Number, vars:Object):TweenLite`

Static method for creating a TweenLite instance. This can be more intuitive for some developers and shields them from potential garbage collection issues that could arise when assigning a tween instance to a variable that persists. The following lines of code produce exactly the same result:
`var myTween:TweenLite = new TweenLite(mc, 1, {x:100});
TweenLite.to(mc, 1, {x:100});
var myTween:TweenLite = TweenLite.to(mc, 1, {x:100});`

Parameters

| `target:Object` — Target object whose properties this tween affects. This can be ANY object, not just a DisplayObject.
| `duration:Number` — Duration in seconds (or in frames if the tween's timing mode is frames-based)
| `vars:Object` — An object containing the end values of the properties you're tweening. For example, to tween to x=100, y=100, you could pass {x:100, y:100}. It can also contain special properties like "onComplete", "ease", "delay", etc.

Returns

| `TweenLite` — TweenLite instance