Package	com.greensock
Class	public class TweenLite
Inheritance	TweenLite Animation Object
Subclasses	TweenMax

TweenLite is an extremely fast, lightweight, and flexible animation tool that serves as the foundation of the GreenSock Animation Platform (GSAP), available in AS2, AS3, and JavaScript. A TweenLite instance handles tweening one or more properties of any object (or array of objects) over time. TweenLite can be used on its own to accomplish most animation chores with minimal file size or it can be use in conjuction with advanced sequencing tools like TimelineLite or TimelineMax to make complex tasks much simpler. With scores of other animation frameworks to choose from, why consider the GreenSock Animation Platform?:

• SPEED - The platform has been highly optimized for maximum performance. See some speed comparisons yourself at http://www.greensock.com/js/speed.html
• Freakishly robust feature set - In addition to tweening any numeric property of any object, TweenLite has plugins that give it the ability to tween hex colors, beziers, css, plus LOTS more. It can round values, use relative values, smoothly reverse() on the fly, automatically detect and accommodate getter/setter functions, employ virtually any easing equation, pause()/resume() anytime, and intelligently manage conflicting tweens of the same object with various overwrite modes. TweenMax extends TweenLite and adds even more capabilities like repeat, yoyo, repeatDelay, on-the-fly destination value updates and more.
• 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 time or progress to fastforward or rewind the entire timeline. Add labels, change the timeline's timeScale, nest timelines within timelines, and much more. This can revolutionize your animation workflow, making it more modular and concise.
• AS3, AS2, and JavaScript - Most other engines are only developed for one language, but the GreenSock Animation Platform allows you to use a consistent API across all your Flash and HTML5 projects.
• Ease of use - Designers and Developers alike rave about how intuitive the platform is.
• Support and reliability - With frequent updates, dedicated forums, committed authorship, a solid track record, a proven funding mechansim, and a thriving community of users, the platform is a safe long-term bet (unlike many open source projects).
• Expandability - With its plugin architecture, you can activate as many (or as few) extra features as your project requires. Write your own plugin to handle particular special properties in custom ways. Minimize bloat and maximize performance.

USAGE

To get up and running quickly, check out the Jump Start tour which covers the basics in a fun, interactive way.

The most common type of tween is a to() tween which allows you to define the destination values:

TweenLite.to(document.getElementById("photo"), 2, {width:200, height:150});

The above code will tween the width and height properties of the <img> DOM element with an id of "photo" from whatever the current values are to 200 and 150 respectively over the course of 2 seconds. Notice the width and height values are defined inside a generic object (between curly braces). Put as many properties there as you want. Also note that <img> elements are one of the few DOM elements that have width and height properties whereas most others (like <div> elements) require css properties to be applied in order to control their width/height (among other properties). To animate those css properties, you'll need to use the CSSPlugin. The CSSPlugin contains special code for deciphering css-related properties and handling them in unique ways, like recognizing colors, transforms, etc. and managing the necessary suffixes ("px", "%", etc.). Once you load the CSSPlugin JavaScript file, you can animate css-related properties by wrapping them in a generic object that you name "css" like this:

TweenLite.to(document.getElementById("div1"), 2, {css:{backgroundColor:"#ff0000", width:"50%", top:"100px"}, ease:Power2.easeInOut});

Just tuck all the css-related properties inside the "css" object. The other special properties like ease, delay, onComplete, etc. stay outside the css object (we'll discuss special properties later).

By default, tweens begin immediately, although you can delay them using the delay special property or pause them initially using the paused special property (see below).

The target can also be an array of objects. For example, the following tween will tween the opacity css property to 0.5 and the rotation transform property to 45 for obj1, obj2, and obj3:

TweenLite.to([obj1, obj2, obj3], 1, {css:{opacity:0.5, rotation:45}});

You can also use a from() tween if you want to define the starting values instead of the ending values so that the target tweens from the defined values to wherever they currently are. Or a fromTo() lets you define both starting and ending values.

Although the to(), from(), and fromTo() static methods are popular because they're quick and can avoid some garbage collection hassles, you can also use the more object-oriented syntax like this:

var tween = new TweenLite(myObject, 2, {width:200, height:150});

or even:

var tween = TweenLite.to(myObject, 2, {width:200, height:150});

SPECIAL PROPERTIES (no plugins required):

Typically the vars parameter is used to define ending values for tweening properties of the target (or beginning values for from() tweens) like {x:100, y:200, alpha:0}, but the following optional special properties serve other purposes:

• delay : Number - Amount of delay in seconds (or frames for frames-based tweens) before the tween should begin.
• ease : Ease (or Function) - You can choose from various eases to control the rate of change during the animation, giving it a specific "feel". For example, ElasticOut.ease or StrongInOut.ease. For best performance, use one of the GreenSock eases (which are in the com.greensock.easing package). TweenLite also works with any standard easing equation that uses the typical 4 parameters (time, start, change, duration) like Adobe's fl.motion.easing eases. The default is Power1.easeOut. For linear animation, use the GreenSock Linear.ease ease
• onComplete : Function - A function that should be called when the tween has completed
• onCompleteParams : Array - An Array of parameters to pass the onComplete function. For example, TweenLite.to(mc, 1, {x:100, onComplete:myFunction, onCompleteParams:[mc, "param2"]}); To self-reference the tween instance itself in one of the parameters, use "{self}", like: onCompleteParams:["{self}", "param2"]
• onCompleteScope : Object - Defines the scope of the onComplete function (what "this" refers to inside that function).
• useFrames : Boolean - If useFrames is true, the tweens's timing will be based on frames instead of seconds because it is intially added to the root frames-based timeline. This causes both its duration and delay to be based on frames. An animations's timing mode is always determined by its parent timeline.
• immediateRender : Boolean - Normally when you create a tween, it begins rendering on the very next frame (update cycle) unless you specify a delay. However, if you prefer to force the tween to render immediately when it is created, set immediateRender to true. Or to prevent a from() from rendering immediately, set immediateRender to false. By default, from() tweens set immediateRender to true.
• onStart : Function - A function that should be called when the tween begins (when its time changes from 0 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. For example, TweenLite.to(mc, 1, {x:100, delay:1, onStart:myFunction, onStartParams:[mc, "param2"]}); To self-reference the tween instance itself in one of the parameters, use "{self}", like: onStartParams:["{self}", "param2"]
• onStartScope : Object - Defines the scope of the onStart function (what "this" refers to inside that function).
• onUpdate : Function - A function that should be called every time the tween updates (on every frame while the tween is active)
• onUpdateParams : Array - An Array of parameters to pass the onUpdate function. For example, TweenLite.to(mc, 1, {x:100, onUpdate:myFunction, onUpdateParams:[mc, "param2"]}); To self-reference the tween instance itself in one of the parameters, use "{self}", like: onUpdateParams:["{self}", "param2"]
• onUpdateScope : Object - Defines the scope of the onUpdate function (what "this" refers to inside that function).
• onReverseComplete : Function - A function that should be called when the tween has reached its beginning again from the reverse direction. For example, if reverse() is called the tween will move back towards its beginning and when its time reaches 0, onReverseComplete will be called. This can also happen if the tween is placed in a TimelineLite or TimelineMax instance that gets reversed and plays the tween backwards to (or past) the beginning.
• onReverseCompleteParams : Array - An Array of parameters to pass the onReverseComplete function. For example, TweenLite.to(mc, 1, {x:100, onReverseComplete:myFunction, onReverseCompleteParams:[mc, "param2"]}); To self-reference the tween instance itself in one of the parameters, use "{self}", like: onReverseCompleteParams:["{self}", "param2"]
• onReverseCompleteScope : Object - Defines the scope of the onReverseComplete function (what "this" refers to inside that function).
• paused : Boolean - If true, the tween will pause itself immediately upon creation.
• overwrite : String (or integer) - Controls how (and if) other tweens of the same target are overwritten. There are several modes to choose from, but "auto" is the default (although you can change the default mode using the TweenLite.defaultOverwrite property):
  • "none" (0) (or false) - no overwriting will occur.
  • "all" (1) (or true) - immediately overwrites all existing tweens of the same target even if they haven't started yet or don't have conflicting properties.
  • "auto" (2) - when the tween renders for the first time, it will analyze tweens of the same target that are currently active/running and only overwrite individual tweening properties that overlap/conflict. Tweens that haven't begun yet are ignored. For example, if another active tween is found that is tweening 3 properties, only 1 of which it shares in common with the new tween, the other 2 properties will be left alone. Only the conflicting property gets overwritten/killed. This is the default mode and typically the most intuitive for developers.
  • "concurrent" (3) - when the tween renders for the first time, it kills only the active (in-progress) tweens of the same target regardless of whether or not they contain conflicting properties. Like a mix of "all" and "auto". Good for situations where you only want one tween controling the target at a time.
  • "allOnStart" (4) - Identical to "all" but waits to run the overwrite logic until the tween begins (after any delay). Kills tweens of the same target even if they don't contain conflicting properties or haven't started yet.
  • "preexisting" (5) - when the tween renders for the first time, it kills only the tweens of the same target that existed BEFORE this tween was created regardless of their scheduled start times. So, for example, if you create a tween with a delay of 10 and then a tween with a delay of 1 and then a tween with a delay of 2 (all of the same target), the 2nd tween would overwrite the first but not the second even though scheduling might seem to dictate otherwise. "preexisting" only cares about the order in which the instances were actually created. This can be useful when the order in which your code runs plays a critical role.

PLUGINS:

Think of plugins like special properties that are dynamically added, delivering extra abilities without forcing them to be baked into the core engine, keeping it relatively lean and mean. Each plugin is associated with a property name and it takes responsibility for handling that property. For example, the CSSPlugin is associated with the "css" property name so if it is activated it will intercept the "css" property in the following tween and manage it in a special way so that the tweens affect the element's style object (for manipulating DOM elements):

TweenLite.to(element, 1, {css:{top:"100px", left:"50px", backgroundColor:"#ff0000", fontSize:"12px"}, delay:0.5});

If the CSSPlugin wasn't activated (loaded), TweenLite would act as though you were trying to literally tween the element.css property (and there is no such thing).

In the JavaScript version of TweenLite, activating a plugin is as simple as loading the associated .js file. No extra activation code is necessary. In the ActionScript version, activating a plugin requires a single line of code and you only need to do it once, so it's pretty easy. Simply pass an Array containing the names of all the plugins you'd like to activate to the TweenPlugin.activate() method, like this:

TweenPlugin.activate([FrameLabelPlugin, ColorTransformPlugin, TintPlugin]);

To make it even easier, there is a Plugin Explorer which writes the code for you. All you need to do is select the plugins and copy/paste the code from the bottom of the tool. It also displays interactive examples of each plugin and the assocaited code so that it’s easy to see the correct syntax.

EXAMPLES:

Please see http://www.greensock.com for examples, tutorials, and interactive demos.

NOTES / TIPS:

• Passing values as Strings and a preceding "+=" or "-=" will make the tween relative to the current value. For example, if you do TweenLite.to(mc, 2, {x:"-=20"}); it'll tween mc.x to the left 20 pixels. {x:"+=20"} would move it to the right.
• You can change the TweenLite.defaultEase if you prefer something other than Power1.easeOut.
• Kill all tweens of a particular object anytime with TweenLite.killTweensOf(myObject);
• You can kill all delayedCalls to a particular function using TweenLite.killDelayedCallsTo(myFunction); or TweenLite.killTweensOf(myFunction);
• 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 2006-2012, GreenSock. All rights reserved. This work is subject to the terms in http://www.greensock.com/terms_of_use.html or for Club GreenSock members, the software agreement that was issued with the membership.

---

 //add listener
 TweenLite.ticker.addEventListener("tick", myFunction);
 
 function myFunction(event) {
     //executes on every tick after the core engine updates
 }
 
 //to remove the listener later...
 TweenLite.ticker.removeEventListener("tick", myFunction);
         

 //add listener that requests an event object parameter, binds scope to the current scope (this), and sets priority to 1 so that it is called before any other listeners that had a priority lower than 1...
 TweenLite.ticker.addEventListener("tick", myFunction, this, true, 1);
 
 function myFunction(event) {
     //executes on every tick after the core engine updates
 }
 
 //to remove the listener later...
 TweenLite.ticker.removeEventListener("tick", myFunction);
         

 import flash.events.Event;
 
 //add listener with weak reference (standard syntax - notice the 5th parameter is true)
 TweenLite.ticker.addEventListener("tick", myFunction, false, 0, true);
 
 function myFunction(event:Event):void {
     //executes on every tick after the core engine updates
 }
 
 //to remove the listener later...
 TweenLite.ticker.removeEventListener("tick", myFunction);
         

//calls myFunction after 1 second and passes 2 parameters:
TweenLite.delayedCall(1, myFunction, ["param1", 2]);
 
function myFunction(param1, param2) {
    //do stuff
}

TweenLite.from([mc1, mc2, mc3], 1.5, {alpha:0});

TweenLite.fromTo([mc1, mc2, mc3], 1, {x:0}, {x:100});

TweenLite.to(myObject1, 1, {x:100});
TweenLite.to(myObject2, 1, {x:100});
TweenLite.to([myObject1, myObject2], 1, {alpha:0});

var a1 = TweenLite.getTweensOf(myObject1); //finds 2 tweens
var a2 = TweenLite.getTweensOf([myObject1, myObject2]); //finds 3 tweens

TweenLite.set(myObject, {x:100, y:50, alpha:0});
TweenLite.to(myObject, 0, {x:100, y:50, alpha:0});

TweenLite.set([obj1, obj2, obj3], {x:100, y:50, alpha:0});

TweenLite.to(mc, 1, {x:100});
var myTween = new TweenLite(mc, 1, {x:100});
var myTween = TweenLite.to(mc, 1, {x:100});

TweenLite.to([mc1, mc2, mc3], 1, {x:100});