overwrite:"all" in the vars parameter to have it kill
* all tweens of the same target immediately. TweenLite, however, offers much more robust overwrite
* management, recognizing advanced modes like "auto" (which only overwrites individual
* tweening properties that overlap), "concurrent", "allOnStart",
* and "preexisting". See TweenLite's documentation for details.pause(), resume(), reverse(), seek(), restart(), etc.
* The essentials are covered, though, like to(), from(), delayedCall(), killTweensOf(),
* and kill().USAGE
*The most common type of tween is a to() tween which allows you * to define the destination values:
* *
* TweenNano.to(myObject, 2, {x:100, y:200});
*
The above code will tween myObject.x from whatever it currently is to 100 and
* myObject.y property to 200 over the course of 2 seconds. Notice the x and y values are
* defined inside a generic object (between curly braces). Put as many properties there as you want.
Tweens begin immediately.
* *The target can also be an array of objects. For example, the following tween will
* tween the alpha property to 0.5 and y property to 100 for obj1, obj2, and obj3:
* TweenNano.to([obj1, obj2, obj3], 1, {alpha:0.5, y:100});
*
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.
* *Although the to() and from() 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 TweenNano(myObject, 2, {x:100, y:200});
*
or even:
* *
* var tween = TweenNano.to(myObject, 2, {x:100, y:200});
*
EXAMPLES:
* *Please see http://www.greensock.com/tweennano/ for examples, tutorials, and interactive demos.
* * *SPECIAL PROPERTIES:
*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:
ElasticOut.ease
* or StrongInOut.ease. TweenNano works with not only the easing equations
* in the com.greensock.easing package, but also standard easing equation that uses the
* typical 4 parameters (time, start, change, duration) like Adobe's
* fl.motion.easing eases. The default is QuadOut.ease.
* For linear animation, use the GreenSock Linear.ease ease.onComplete function. For example,
* TweenNano.to(mc, 1, {x:100, onComplete:myFunction, onCompleteParams:[mc, "param2"]});useFrames is true, the tweens's timing will be
* based on frames instead of seconds. This causes both its duration
* and delay to be based on frames.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.onUpdate function. For example,
* TweenNano.to(mc, 1, {x:100, onUpdate:myFunction, onUpdateParams:[mc, "param2"]});overwrite:"all"TweenNano.to(mc, 2, {x:"-=20"}); it'll
* tween mc.x to the left 20 pixels. {x:"+=20"} would move it to the right.TweenNano.defaultEase if you prefer something other
* than QuadOut.ease.TweenNano.killTweensOf(myObject);TweenNano.killTweensOf(myFunction);TweenNano.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).Copyright 2008-2014, 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.
* * @author Jack Doyle, jack@greensock.com */ public class TweenNano { /** @private **/ protected static var _time:Number; /** @private **/ protected static var _frame:uint; /** * The object that dispatches a"tick" event each time the engine updates, making it easy for
* you to add your own listener(s) to run custom logic after each update (great for game developers).
* Add as many listeners as you want. The basic syntax is the same for all versions (AS2, AS3, and Javascript):
*
* Basic example (AS2, AS3, and Javascript):
Due to differences in the core languages (and to maximize efficiency), the advanced syntax is slightly different * for the AS3 version compared to AS2 and Javascript. The parameters beyond the first 2 in the addEventListener() * method are outlined below:
* *Javascript and AS2
*addEventListener(type, callback, scope, useParam, priority)
Parameters: *
"tick"this" refers to in your function). This can be very useful in Javascript and AS2 because scope isn't generally maintained. true, an event object will be generated and fed to the callback each time the event occurs. The event is a generic object and has two properties: type (always "tick") and target which refers to the ticker instance. The default for useParam is false because it improves performance.Advanced example (Javascript and AS2):
AS3
*The AS3 version uses the standard EventDispatcher.addEventListener() syntax which
* basically allows you to define a priority and whether or not to use weak references (see Adobe's
* docs for details).
Advanced example [AS3 only]:
com.greensock.easing package or any standard easing function like the ones in Adobe's fl.motion.easing package. @default QuadOut.ease **/
public static var defaultEase:Object = function (t:Number, b:Number, c:Number, d:Number):Number {
return -1 * (t /= d) * (t - 2);
}
/** @private **/
protected static var _reservedProps:Object;
/** @private **/
protected static var _tickEvent:Event = new Event("tick");
/** @private **/
protected static var _first:TweenNano;
/** @private **/
protected static var _last:TweenNano;
/** @private Duration of the tween in seconds (or in frames if "useFrames" is true). **/
public var _duration:Number;
/** Stores variables (things like "alpha", "y" or whatever we're tweening, as well as special properties like "onComplete"). **/
public var vars:Object;
/** @private Start time in seconds (or frames for frames-based tweens) **/
public var _startTime:Number;
/** Target object whose properties this tween affects. This can be ANY object or even an array. **/
public var target:Object;
/** @private Flagged for garbage collection **/
public var _gc:Boolean;
/** @private Indicates that frames should be used instead of seconds for timing purposes. So if useFrames is true and the tween's duration is 10, it would mean that the tween should take 10 frames to complete, not 10 seconds. **/
public var _useFrames:Boolean;
/** @private result of _ease(this.time, 0, 1, this.duration). Usually between 0 and 1, but not always (like with Elastic.easeOut). **/
public var ratio:Number = 0;
/** @private Easing method to use which determines how the values animate over time. Examples are Elastic.easeOut and Strong.easeIn. Many are found in the fl.motion.easing package or com.greensock.easing. **/
protected var _ease:Function;
/** @private **/
protected var _rawEase:Object;
/** @private Indicates whether or not init() has been called (where all the tween property start/end value information is recorded) **/
protected var _initted:Boolean;
/** @private **/
protected var _firstPT:Object;
/** @private **/
public var _next:TweenNano;
/** @private **/
public var _prev:TweenNano;
/** @private **/
public var _targets:Array;
/**
* Constructor
*
* @param target Target object (or array of objects) whose properties this tween affects
* @param duration Duration in seconds (or frames if useFrames:true is set in the vars parameter)
* @param vars An object defining the end value for each property that should be tweened as well as any special properties like onComplete, ease, etc. For example, to tween mc.x to 100 and mc.y to 200 and then call myFunction, do this: new TweenNano(mc, 1, {x:100, y:200, onComplete:myFunction}).
*/
public function TweenNano(target:Object, duration:Number, vars:Object) {
if (!_reservedProps) {
_reservedProps = {ease:1, delay:1, useFrames:1, overwrite:1, onComplete:1, onCompleteParams:1, runBackwards:1, immediateRender:1, onUpdate:1, onUpdateParams:1, startAt:1};
_time = getTimer() / 1000;
_frame = 0;
ticker.addEventListener(Event.ENTER_FRAME, _updateRoot, false, 0, true);
}
this.vars = vars;
_duration = duration;
this.target = target;
if (target is Array && typeof(target[0]) === "object") {
_targets = target.concat();
}
_rawEase = this.vars.ease || defaultEase;
_ease = (typeof(_rawEase) == "function") ? _rawEase as Function : _rawEase.getRatio;
_useFrames = Boolean(vars.useFrames == true);
_startTime = (_useFrames ? _frame : _time) + (this.vars.delay || 0);
if (this.vars.overwrite == "all" || int(this.vars.overwrite) == 1) {
killTweensOf(this.target);
}
_prev = _last;
if (_last) {
_last._next = this;
} else {
_first = this;
}
_last = this;
if (this.vars.immediateRender == true || (duration == 0 && this.vars.delay == 0 && this.vars.immediateRender != false)) {
_render(0);
}
}
/** @private Initializes the property tweens, determining their start values and amount of change. **/
public function _init():void {
if (vars.startAt) {
vars.startAt.immediateRender = true;
TweenNano.to(target, 0, vars.startAt);
}
var i:int, pt:Object;
if (_targets != null) {
i = _targets.length;
while (--i > -1) {
_initProps(_targets[i]);
}
} else {
_initProps(target);
}
if (vars.runBackwards) {
pt = _firstPT;
while (pt) {
pt.s += pt.c;
pt.c = -pt.c;
pt = pt._next;
}
}
_initted = true;
}
/** @private **/
protected function _initProps(target:*):void {
if (target != null) {
for (var p:String in vars) {
if (!(p in _reservedProps)) {
_firstPT = {_next:_firstPT, t:target, p:p, f:(typeof(target[p]) === "function")};
_firstPT.s = (!_firstPT.f) ? Number(target[p]) : target[ ((p.indexOf("set") || typeof(target["get" + p.substr(3)]) !== "function") ? p : "get" + p.substr(3)) ]();
_firstPT.c = (typeof(vars[p]) === "number") ? Number(vars[p]) - _firstPT.s : (typeof(vars[p]) === "string" && vars[p].charAt(1) === "=") ? int(vars[p].charAt(0)+"1") * Number(vars[p].substr(2)) : Number(vars[p]) || 0;
if (_firstPT._next) {
_firstPT._next._prev = _firstPT;
}
}
}
}
}
/**
* @private
* Renders the tween at a particular time (or frame number for frames-based tweens)
* WITHOUT changing its _startTime, meaning if the tween is in progress when you call
* _render(), it will not adjust the tween's timing to continue from the new time.
* The time is based simply on the overall duration. For example, if a tween's duration
* is 3, _render(1.5) would render it at the halfway finished point.
*
* @param time time (or frame number for frames-based tweens) to render.
*/
public function _render(time:Number):void {
if (!_initted) {
_init();
}
if (time >= _duration) {
time = _duration;
this.ratio = (_ease != _rawEase && _rawEase._calcEnd) ? _ease.call(_rawEase, 1) : 1;
} else if (time <= 0) {
this.ratio = (_ease != _rawEase && _rawEase._calcEnd) ? _ease.call(_rawEase, 0) : 0;
} else {
this.ratio = (_ease == _rawEase) ? _ease(time, 0, 1, _duration) : _ease.call(_rawEase, time / _duration);
}
var pt:Object = _firstPT;
while (pt) {
if (pt.f) {
pt.t[pt.p](pt.c * ratio + pt.s);
} else {
pt.t[pt.p] = pt.c * ratio + pt.s;
}
pt = pt._next;
}
if (vars.onUpdate) {
vars.onUpdate.apply(null, vars.onUpdateParams);
}
if (time == _duration) {
kill();
if (vars.onComplete) {
vars.onComplete.apply(null, vars.onCompleteParams);
}
}
}
/**
* Kills the tween, stopping it immediately. You can optionally define a particular target
* to isolate (or an array of targets) which is only useful in tweens whose target is
* an array. For example, let's say we have a tween like this:
*
*
* var tween = TweenNan.to([mc1, mc2, mc3], 2, {x:100});
*
Later, we could kill only the mc2 portion of the tween like this:
* *
* tween.kill(mc2);
*
To kill the entire tween, simply omit the target parameter, like tween.kill()
myObject, do kill(myObject) or to kill only parts having to do with myObject1 and myObject2, do kill([myObject1, myObject2]). If no target is defined, ALL targets will be affected.
**/
public function kill(target:*=null):void {
var i:int, pt:Object = _firstPT;
target = target || _targets || this.target;
if (target is Array && typeof(target[0]) === "object") {
i = target.length;
while (--i > -1) {
kill(target[i]);
}
return;
} else if (_targets != null) {
i = _targets.length;
while (--i > -1) {
if (target == _targets[i]) {
_targets.splice(i, 1);
}
}
while (pt) {
if (pt.t == target) {
if (pt._next) {
pt._next._prev = pt._prev;
}
if (pt._prev) {
pt._prev._next = pt._next;
} else {
_firstPT = pt._next;
}
}
pt = pt._next;
}
}
if (_targets == null || _targets.length == 0) {
_gc = true;
if (_prev) {
_prev._next = _next;
} else if (this == _first) {
_first = _next;
}
if (_next) {
_next._prev = _prev;
} else if (this == _last) {
_last = _prev;
}
_next = _prev = null;
}
}
//---- STATIC FUNCTIONS -------------------------------------------------------------------------
/**
* Static method for creating a TweenNano instance that animates to the specified destination values
* (from the current values). The following lines of code all produce identical results:
*
* Each line above will tween the "x" property of the mc object
* to a value of 100 over the coarse of 1 second. They each use a slightly different syntax,
* all of which are valid. If you don't need to store a reference of the tween, just use the
* static TweenNano.to( ) call.
Since the target parameter can also be an array of objects, the following
* code will tween the x property of mc1, mc2, and mc3 to a value of 100 simultaneously:
Even though 3 objects are animating, there is still only one tween created.
* *For simple sequencing, you can use the delay special property
* (like TweenNano.to(mc, 1, {x:100, delay:0.5})),
* but it is highly recommended that you consider using TimelineLite (or TimelineMax)
* for all but the simplest sequencing tasks. It has an identical to() method
* that allows you to append tweens one-after-the-other and then control the entire sequence
* as a whole. You can even have the tweens overlap as much as you want.
useFrames:true is set in the vars parameter)
* @param vars An object defining the end value for each property that should be tweened as well as any special properties like onComplete, ease, etc. For example, to tween mc.x to 100 and mc.y to 200 and then call myFunction, do this: TweenNano.to(mc, 1, {x:100, y:200, onComplete:myFunction});
* @return TweenNano instance
* @see com.greensock.TimelineLite#to()
* @see #from()
*/
public static function to(target:Object, duration:Number, vars:Object):TweenNano {
return new TweenNano(target, duration, vars);
}
/**
* Static method for creating a TweenNano instance that tweens backwards -
* you define the BEGINNING values and the current values are used
* as the destination values which is great for doing things like animating objects
* onto the screen because you can set them up initially the way you want them to look
* at the end of the tween and then animate in from elsewhere.
*
* 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 parameter so that it will
* wait to render until the tween actually begins. 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:
* TweenNano.from(mc, 1.5, {alpha:0, delay:2});
*
Since the target parameter can also be an array of objects, the following
* code will tween the alpha property of mc1, mc2, and mc3 from a value of 0 simultaneously:
Even though 3 objects are animating, there is still only one tween created.
* *For simple sequencing, you can use the delay special property
* (like TweenNano.from(mc, 1, {alpha:0, delay:0.5})),
* but it is highly recommended that you consider using TimelineLite (or TimelineMax)
* for all but the simplest sequencing tasks. It has an identical from() method
* that allows you to append tweens one-after-the-other and then control the entire sequence
* as a whole. You can even have the tweens overlap as much as you want.
useFrames:true is set in the vars parameter)
* @param vars An object defining the starting value for each property that should be tweened as well as any special properties like onComplete, ease, etc. For example, to tween mc.x from 100 and mc.y from 200 and then call myFunction, do this: TweenNano.from(mc, 1, {x:100, y:200, onComplete:myFunction});
* @return TweenNano instance
* @see #to()
* @see com.greensock.TimelineLite#from()
* @see com.greensock.TimelineLite#staggerFrom()
*/
public static function from(target:Object, duration:Number, vars:Object):TweenNano {
vars.runBackwards = true;
if (!("immediateRender" in vars)) {
vars.immediateRender = true;
}
return new TweenNano(target, duration, vars);
}
/**
* 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.
*
* Javascript and AS2 note: - Due to the way Javascript and AS2 don't
* maintain scope (what "this" refers to, or the context) in function calls,
* it can be useful to define the scope specifically. Therefore, in the Javascript and AS2
* versions the 4th parameter is scope, bumping useFrames
* back to the 5th parameter:
TweenNano.delayedCall(delay, callback, params, scope, useFrames) [Javascript and AS2 only]
useFrames is true) before the function should be called
* @param callback Function to call
* @param params An Array of parameters to pass the function (optional).
* @param useFrames If the delay should be measured in frames instead of seconds, set useFrames to true (default is false)
* @return TweenNano instance
* @see com.greensock.TimelineLite#call()
*/
public static function delayedCall(delay:Number, callback:Function, params:Array=null, useFrames:Boolean=false):TweenNano {
return new TweenNano(callback, 0, {delay:delay, onComplete:callback, onCompleteParams:params, useFrames:useFrames});
}
/**
* @private
* Updates active tweens and inits those whose startTime precedes the current _time/_frame.
*
* @param e ENTER_FRAME Event
*/
public static function _updateRoot(e:Event=null):void {
_frame += 1;
_time = getTimer() * 0.001;
var tween:TweenNano = _first,
next:TweenNano,
t:Number;
while (tween) {
next = tween._next;
t = (tween._useFrames) ? _frame : _time;
if (t >= tween._startTime && !tween._gc) {
tween._render(t - tween._startTime);
}
tween = next;
}
ticker.dispatchEvent(_tickEvent);
}
/**
* Kills all the tweens of a particular object or the delayedCalls to a particular function.
* If, for example, you want to kill all tweens of myObject, you'd do this:
*
*
* TweenNano.killTweensOf(myObject);
*
To kill all the delayedCalls that were created like TweenNano.delayedCall(5, myFunction);,
* you can simply call TweenNano.killTweensOf(myFunction); because delayedCalls
* are simply tweens that have their target and onComplete set to
* the same function (as well as a delay of course).
killTweensOf() affects tweens that haven't begun yet too. If, for example,
* a tween of myObject has a delay of 5 seconds and
* TweenNano.killTweensOf(mc) is called 2 seconds after the tween was created,
* it will still be killed even though it hasn't started yet.