Package | com.greensock |
Class | public class TweenMax |
Inheritance | TweenMax TweenLite Animation Object |
Like TweenLite, a TweenMax instance handles tweening one or more properties of any object (or array of objects) over time. TweenMax can be used on its own or 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?:
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.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.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:
TweenMax.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:
TweenMax.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:
TweenMax.to([obj1, obj2, obj3], 1, {css:{opacity:0.5, rotation:45}});
Notice that we want to tween css-related properties, so we're using the CSSPlugin in this tween. That's why we define the properties inside an object we call "css" (telling the engine 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.). More on that later...
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 TweenMax(myObject, 2, {width:200, height:150});
or even:
var tween = TweenMax.to(myObject, 2, {width:200, height:150});
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
. For best performance, use one of the GreenSock eases
(which are in the com.greensock.easing
package). TweenMax 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
easeonComplete
function. For example,
TweenMax.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"]
"this"
refers to inside that function).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
.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
.time
changes from 0 to some other value which can happen more than once if the
tween is restarted multiple times).onStart
function. For example,
TweenMax.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"]
"this"
refers to inside that function).onUpdate
function. For example,
TweenMax.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"]
"this"
refers to inside that function).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.onReverseComplete
function. For example,
TweenMax.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"]
"this"
refers to inside that function).true
, the tween will pause itself immediately upon creation."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.repeat
is 1, the tween will play a total of twice (the initial play
plus 1 repeat). To repeat indefinitely, use -1. repeat
should always be an integer.repeat
is 2 and repeatDelay
is 1, the tween will play initially,
then wait for 1 second before it repeats, then play again, then wait 1 second again before
doing its final repeat.true
, every other repeat
cycle will run in the opposite
direction so that the tween appears to go back and forth (forward then backward).
This has no affect on the "reversed
" property though. So if repeat
is 2 and yoyo
is false
, it will look like:
start - 1 - 2 - 3 - 1 - 2 - 3 - 1 - 2 - 3 - end. But if yoyo
is true
,
it will look like: start - 1 - 2 - 3 - 3 - 2 - 1 - 1 - 2 - 3 - end.TweenMax.to(mc, 1, {x:100, onRepeat:myFunction, onRepeatParams:[mc, "param2"]});
To self-reference the tween instance itself in one of the parameters, use "{self}"
,
like: onRepeatParams:["{self}", "param2"]
"this"
refers to inside that function).startAt
allows you to override that behavior. Simply pass an object
in with whatever properties you'd like to set just before the tween begins. For example,
if mc.x
is currently 100, and you'd like to tween it from 0 to 500, do
TweenMax.to(mc, 2, {x:500, startAt:{x:0}});
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):
TweenMax.to(element, 1, {css:{top:"100px", left:"50px", backgroundColor:"#ff0000", fontSize:"12px"}, delay:0.5});
If the CSSPlugin wasn't activated (loaded), TweenMax 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 TweenMax, activating a plugin is as simple as loading the associated .js file.
No extra activation code is necessary. And by default, the JavaScript version of TweenMax includes the CSSPlugin
and RoundPropsPlugin so you don't need to load those separately. 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]);
The following plugins are automatically activated by TweenMax:
TweenMax.to(myElement, 1, {css:{width:"50%", height:"300px", backgroundColor:"#ff0000"}, delay:1});
TweenMax.to(mc, 2, {x:300, y:200, alpha:0.5, roundProps:"x,y"});
EXAMPLES:
Please see http://www.greensock.com for examples, tutorials, and interactive demos.
NOTES / TIPS:TweenMax.to(mc, 2, {x:"-=20"});
it'll
tween mc.x
to the left 20 pixels. {x:"+=20"}
would move it to the right.TweenLite.defaultEase
static property.
The default is Power1.easeOut
.TweenMax.killTweensOf(myObject);
TweenMax.killDelayedCallsTo(myFunction)
or TweenMax.killTweensOf(myFunction);
TweenMax.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-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.
Property | Defined By | ||
---|---|---|---|
data : * A place to store any data you want (initially populated with vars.data if it exists). | Animation | ||
defaultEase : Ease [static] Provides An easy way to change the default easing equation. | TweenLite | ||
defaultOverwrite : String = auto [static] Provides An easy way to change the default overwrite mode. | TweenLite | ||
target : Object [READ-ONLY] Target object (or array of objects) whose properties the tween affects. | TweenLite | ||
ticker : Object [static]
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). | TweenMax | ||
timeline : SimpleTimeline [Read-only] Parent timeline. | Animation | ||
vars : Object The vars object passed into the constructor which stores configuration variables like onComplete, onUpdate, etc. | Animation |
Method | Defined By | ||
---|---|---|---|
TweenMax(target:Object, duration:Number, vars:Object)
Constructor
| TweenMax | ||
delay(value:Number):*
Gets or sets the animation's initial delay which is the length of time in seconds
(or frames for frames-based tweens) before the animation should begin. | Animation | ||
delayedCall(delay:Number, callback:Function, params:Array = null, scope:* = null, useFrames:Boolean = false):TweenMax [static]
Provides a simple way to call a function after a set amount of time (or frames). | TweenMax | ||
duration(value:Number):*
Gets or sets the animation's duration, not including any repeats or repeatDelays
(which are only available in TweenMax and TimelineMax). | Animation | ||
eventCallback(type:String, callback:Function = null, params:Array = null, scope:* = null):*
Gets or sets an event callback like "onComplete", "onUpdate", "onStart", "onReverseComplete"
or "onRepeat" (onRepeat only applies to TweenMax or TimelineMax instances)
along with any parameters that should be passed to that callback. | Animation | ||
[static]
Static method for creating a TweenMax 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. | TweenMax | ||
[static]
Static method for creating a TweenMax instance that allows you to define both the starting
and ending values (as opposed to to() and from() tweens which are
based on the target's current values at one end or the other). | TweenMax | ||
getAllTweens(includeTimelines:Boolean = false):Array [static]
Returns an array containing all tweens (and optionally timelines too, excluding the root timelines). | TweenMax | ||
getTweensOf(target:*):Array [static]
Returns an array containing all the tweens of a particular target (or group of targets) that have not
been released for garbage collection yet which typically happens within a few seconds after the tween completes. | TweenMax | ||
invalidate():* [override]
Clears any initialization data (like starting/ending values in tweens) which can be useful if, for example,
you want to restart a tween without reverting to any previously recorded starting values. | TweenMax | ||
isTweening(target:Object):Boolean [static]
Reports whether or not a particular object is actively tweening. | TweenMax | ||
kill(vars:Object = null, target:Object = null):*
Kills the animation entirely or in part depending on the parameters. | Animation | ||
killAll(complete:Boolean = false, tweens:Boolean = true, delayedCalls:Boolean = true, timelines:Boolean = true):void [static]
Kills all tweens and/or delayedCalls/callbacks, and/or timelines, optionally forcing them to
completion first. | TweenMax | ||
killChildTweensOf(parent:Object, complete:Boolean = false):void [static]
Kills all tweens of the children of a particular DOM element, optionally forcing them to completion first. | TweenMax | ||
killDelayedCallsTo(func:Function):void [static]
Immediately kills all of the delayedCalls to a particular function. | TweenMax | ||
killTweensOf(target:*, vars:Object = null):void [static]
Kills all the tweens (or specific tweening properties) of a particular object or
the delayedCalls to a particular function. | TweenMax | ||
pause(atTime:* = null, suppressEvents:Boolean = true):*
Pauses the instance, optionally jumping to a specific time. | Animation | ||
pauseAll(tweens:Boolean = true, delayedCalls:Boolean = true, timelines:Boolean = true):void [static]
[deprecated] Pauses all tweens and/or delayedCalls/callbacks and/or timelines. | TweenMax | ||
paused(value:Boolean = false):*
Gets or sets the animation's paused state which indicates whether or not the animation
is currently paused. | Animation | ||
play(from:* = null, suppressEvents:Boolean = true):*
Begins playing forward, optionally from a specific time (by default playback begins from
wherever the playhead currently is). | Animation | ||
progress(value:Number):*
Gets or sets the tween's progress which is a value between 0 and 1 indicating the position
of the virtual playhead (excluding repeats) where 0 is at the beginning, 0.5 is halfway complete,
and 1 is complete. | TweenMax | ||
repeat(value:int = 0):*
Gets or sets the number of times that the tween should repeat after its first iteration. | TweenMax | ||
repeatDelay(value:Number):*
Gets or sets the amount of time in seconds (or frames for frames-based tweens) between repeats. | TweenMax | ||
restart(includeDelay:Boolean = false, suppressEvents:Boolean = true):*
Restarts and begins playing forward from the beginning. | Animation | ||
resume(from:* = null, suppressEvents:Boolean = true):*
Resumes playing without altering direction (forward or reversed), optionally jumping to a specific time first. | Animation | ||
resumeAll(tweens:Boolean = true, delayedCalls:Boolean = true, timelines:Boolean = true):void [static]
[deprecated] Resumes all paused tweens and/or delayedCalls/callbacks and/or timelines. | TweenMax | ||
reverse(from:* = null, suppressEvents:Boolean = true):*
Reverses playback so that all aspects of the animation are oriented backwards including, for example,
a tween's ease. | Animation | ||
reversed(value:Boolean = false):*
Gets or sets the animation's reversed state which indicates whether or not the animation
should be played backwards. | Animation | ||
seek(time:*, suppressEvents:Boolean = true):*
Jumps to a specific time without affecting whether or not the instance is paused or reversed. | Animation | ||
[static]
Immediately sets properties of the target accordingly - essentially a zero-duration to() tween with a more
intuitive name. | TweenMax | ||
staggerFrom(targets:Array, duration:Number, vars:Object, stagger:Number = 0, onCompleteAll:Function = null, onCompleteAllParams:Array = null, onCompleteAllScope:* = null):Array [static]
Tweens an array of targets from a common set of destination values (using the current
values as the destination), but staggers their start times by a specified amount of time,
creating an evenly-spaced sequence with a surprisingly small amount of code. | TweenMax | ||
staggerFromTo(targets:Array, duration:Number, fromVars:Object, toVars:Object, stagger:Number = 0, onCompleteAll:Function = null, onCompleteAllParams:Array = null, onCompleteAllScope:* = null):Array [static]
Tweens an array of targets from and to a common set of values, but staggers their
start times by a specified amount of time, creating an evenly-spaced sequence with a
surprisingly small amount of code. | TweenMax | ||
staggerTo(targets:Array, duration:Number, vars:Object, stagger:Number = 0, onCompleteAll:Function = null, onCompleteAllParams:Array = null, onCompleteAllScope:* = null):Array [static]
Tweens an array of targets to a common set of destination values, but staggers their
start times by a specified amount of time, creating an evenly-spaced sequence with a
surprisingly small amount of code. | TweenMax | ||
startTime(value:Number):*
Gets or sets the time at which the animation begins on its parent timeline (after any delay
that was defined). | Animation | ||
time(value:Number, suppressEvents:Boolean = false):* [override]
Gets or sets the local position of the playhead (essentially the current time), not
including any repeats or repeatDelays. | TweenMax | ||
timeScale(value:Number):*
Factor that's used to scale time in the animation where 1 = normal speed (the default),
0.5 = half speed, 2 = double speed, etc. | Animation | ||
[static]
Static method for creating a TweenMax instance that animates to the specified destination values
(from the current values). | TweenMax | ||
totalDuration(value:Number):* [override]
Gets or sets the total duration of the tween in seconds (or frames for frames-based tweens)
including any repeats or repeatDelays. | TweenMax | ||
totalProgress(value:Number):*
Gets or sets the tween's totalProgress which is a value between 0 and 1 indicating the position
of the virtual playhead (including repeats) where 0 is at the beginning, 0.5 is halfway complete,
and 1 is complete. | TweenMax | ||
totalTime(time:Number, suppressEvents:Boolean = false):*
Gets or sets the position of the playhead according to the totalDuration
which includes any repeats and repeatDelays (only available
in TweenMax and TimelineMax). | Animation | ||
updateTo(vars:Object, resetDuration:Boolean = false):*
Updates tweening values on the fly so that they appear to seamlessly change course even if
the tween is in-progress. | TweenMax | ||
yoyo(value:Boolean = false):*
Gets or sets the tween's yoyo state, where true causes
the tween to go back and forth, alternating backward and forward on each
repeat. | TweenMax |
ticker | property |
public static var ticker:Object
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):
//add listener TweenMax.ticker.addEventListener("tick", myFunction); function myFunction(event) { //executes on every tick after the core engine updates } //to remove the listener later... TweenMax.ticker.removeEventListener("tick", myFunction);
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):
//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... TweenMax.ticker.addEventListener("tick", myFunction, this, true, 1); function myFunction(event) { //executes on every tick after the core engine updates } //to remove the listener later... TweenMax.ticker.removeEventListener("tick", myFunction);
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]:
import flash.events.Event; //add listener with weak reference (standard syntax - notice the 5th parameter is true) TweenMax.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... TweenMax.ticker.removeEventListener("tick", myFunction);
TweenMax | () | Constructor |
public function TweenMax(target:Object, duration:Number, vars:Object)
Constructor
Parameterstarget:Object — Target object (or array of objects) whose properties this tween affects
| |
duration:Number — Duration in seconds (or frames if useFrames:true is set in the vars parameter)
| |
vars:Object — 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 TweenMax(mc, 1, {x:100, y:200, onComplete:myFunction}) .
|
delayedCall | () | method |
public static function delayedCall(delay:Number, callback:Function, params:Array = null, scope:* = null, useFrames:Boolean = false):TweenMax
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, the JavaScript and AS2
versions accept a 4th parameter to [optionally] define the scope
, but it
is omitted in AS3:
TweenMax.delayedCall(delay, callback, params, scope, useFrames)
[JavaScript and AS2 only]
//calls myFunction after 1 second and passes 2 parameters: TweenMax.delayedCall(1, myFunction, ["param1", 2]); function myFunction(param1, param2) { //do stuff }
Parameters
delay:Number — Delay in seconds (or frames if useFrames is true ) before the function should be called
| |
callback:Function — Function to call
| |
params:Array (default = null ) — An Array of parameters to pass the function (optional).
| |
scope:* (default = null ) — The scope in which the callback should be called (basically, what "this" refers to in the function). NOTE: this parameter only pertains to the JavaScript and AS2 versions; it is omitted in AS3.
| |
useFrames:Boolean (default = false ) — If the delay should be measured in frames instead of seconds, set useFrames to true (default is false )
|
TweenMax — TweenMax instance
|
from | () | method |
public static function from(target:Object, duration:Number, vars:Object):TweenMax
Static method for creating a TweenMax 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 (often the desired behavior when inserting
into TimelineLite or TimelineMax instances). 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:
TweenMax.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:
TweenMax.from([mc1, mc2, mc3], 1.5, {alpha:0});
Even though 3 objects are animating, there is still only one tween that is created.
In order to stagger or offset the start times of each object animating, please see
the staggerFrom()
method (TimelineLite has one too).
For simple sequencing, you can use the delay
special property
(like TweenMax.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.
Parameters
target:Object — Target object (or array of objects) whose properties this tween affects.
| |
duration:Number — Duration in seconds (or frames if useFrames:true is set in the vars parameter)
| |
vars:Object — 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: TweenMax.from(mc, 1, {x:100, y:200, onComplete:myFunction});
|
TweenMax — TweenMax instance
|
See also
fromTo | () | method |
public static function fromTo(target:Object, duration:Number, fromVars:Object, toVars:Object):TweenMax
Static method for creating a TweenMax instance that allows you to define both the starting
and ending values (as opposed to to()
and from()
tweens which are
based on the target's current values at one end or the other).
NOTE: Only put starting values in the fromVars
parameter - all
special properties for the tween (like onComplete, onUpdate, delay, etc.) belong in the toVars
parameter.
Since the target
parameter can also be an array of objects, the following
code will tween the x property of mc1, mc2, and mc3 from 0 to 100 simultaneously:
TweenMax.fromTo([mc1, mc2, mc3], 1, {x:0}, {x:100});
Even though 3 objects are animating, there is still only one tween created.
In order to stagger or offset the start times of each object animating, please see
the staggerFromTo()
method (TimelineLite has one too).
For simple sequencing, you can use the delay
special property
(like TweenMax.fromTo(mc, 1, {x:0}, {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 fromTo()
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.
Parameters
target:Object — Target object (or array of objects) whose properties this tween affects.
| |
duration:Number — Duration in seconds (or frames if useFrames:true is set in the vars parameter)
| |
fromVars:Object — An object defining the starting value for each property that should be tweened. For example, to tween mc.x from 100 and mc.y from 200, fromVars would look like this: {x:100, y:200} .
| |
toVars:Object — 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 from 0 to 100 and mc.y from 0 to 200 and then call myFunction , do this: TweenMax.fromTo(mc, 1, {x:0, y:0}, {x:100, y:200, onComplete:myFunction});
|
TweenMax — TweenMax instance
|
See also
getAllTweens | () | method |
public static function getAllTweens(includeTimelines:Boolean = false):Array
Returns an array containing all tweens (and optionally timelines too, excluding the root timelines).
If your goal is to affect all of the tweens/timelines/delayedCalls (like to pause()
them
or reverse()
or alter their timeScale
), you might want to consider using the
static TimelineLite.exportRoot()
method instead because it provides a single instance
that you can use to control everything.
Parameters
includeTimelines:Boolean (default = false ) — If true , TimelineLite and TimelineMax instances will also be included.
|
Array — Array of tweens/timelines
|
See also
getTweensOf | () | method |
public static function getTweensOf(target:*):Array
Returns an array containing all the tweens of a particular target (or group of targets) that have not
been released for garbage collection yet which typically happens within a few seconds after the tween completes.
For example, TweenMax.getTweensOf(myObject)
returns an array of all tweens
of myObject
, even tweens that haven't begun yet. TweenMax.getTweensOf([myObject1, myObject2]);
will return a condensed array of the tweens of myObject1
plus all the tweens
of myObject2
combined into one array with duplicates removed.
Since the method only finds tweens that haven't been released for garbage collection, if you create a tween
and then let it finish and then a while later try to find it with getTweensOf()
, it may not be found
because it was released by the engine for garbage collection. Remember, one of the best parts of GSAP is that it
saves you from the headache of managing gc. Otherwise, you'd need to manually dispose each tween you create, making
things much more cumbersome.
TweenMax.to(myObject1, 1, {x:100}); TweenMax.to(myObject2, 1, {x:100}); TweenMax.to([myObject1, myObject2], 1, {alpha:0}); var a1 = TweenMax.getTweensOf(myObject1); //finds 2 tweens var a2 = TweenMax.getTweensOf([myObject1, myObject2]); //finds 3 tweens
Parameters
target:* — The target whose tweens should be returned, or an array of such targets
|
Array — An array of tweens
|
invalidate | () | method |
override public function invalidate():*
Clears any initialization data (like starting/ending values in tweens) which can be useful if, for example,
you want to restart a tween without reverting to any previously recorded starting values. When you invalidate()
an animation, it will be re-initialized the next time it renders and its vars
object will be re-parsed.
The timing of the animation (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 TimelineLite/TimelineMax, it automatically invalidates all of its children.
* — self (makes chaining easier)
|
isTweening | () | method |
public static function isTweening(target:Object):Boolean
Reports whether or not a particular object is actively tweening. If a tween is paused, is completed, or hasn't started yet, it isn't considered active.
Parameters
target:Object — Target object whose tweens you're checking
|
Boolean — Boolean value indicating whether or not any active tweens were found
|
killAll | () | method |
public static function killAll(complete:Boolean = false, tweens:Boolean = true, delayedCalls:Boolean = true, timelines:Boolean = true):void
Kills all tweens and/or delayedCalls/callbacks, and/or timelines, optionally forcing them to completion first. The various parameters provide a way to specify exactly which types you want to kill
//kill everything TweenMax.killAll(); //kill only tweens, but not delayedCalls or timelines TweenMax.killAll(false, true, false, false); //kill only delayedCalls TweenMax.killAll(false, false, true, false);
Parameters
complete:Boolean (default = false ) — Determines whether or not the tweens/delayedCalls/timelines should be forced to completion before being killed.
| |
tweens:Boolean (default = true ) — If true , all tweens will be killed (TweenLite and TweenMax instances)
| |
delayedCalls:Boolean (default = true ) — If true , all delayedCalls will be killed. TimelineMax callbacks are treated the same as delayedCalls.
| |
timelines:Boolean (default = true ) — If true , all TimelineLite and TimelineMax instances will be killed.
|
killChildTweensOf | () | method |
public static function killChildTweensOf(parent:Object, complete:Boolean = false):void
Kills all tweens of the children of a particular DOM element, optionally forcing them to completion first. For example, if you have the following HTML:
<div id="d1"> <div id="d2"> <img src="photo.jpg" id="image" /> </div> </div> <div id="d3"></div>
TweenMax.killChildTweensOf( document.getElementById("d1") )
.
TweenMax.to( document.getElementById("d2"), 1, {css:{left:100}}); TweenMax.to( document.getElementById("image"), 1, {css:{left:100}}); TweenMax.to( document.getElementById("d3"), 1, {css:{left:100}}); //only kills the first 2 tweens because those targets are child elements of the "d1" DOM element. TweenMax.killChildTweensOf( document.getElementById("d1") );
Parameters
parent:Object — The parent DOM element whose children's tweens should be killed.
| |
complete:Boolean (default = false ) — If true , the tweens will be forced to completion before being killed.
|
killDelayedCallsTo | () | method |
public static function killDelayedCallsTo(func:Function):void
Immediately kills all of the delayedCalls to a particular function. If, for example,
you want to kill all delayedCalls to myFunction
, you'd do this:
TweenMax.killDelayedCallsTo(myFunction);
Since a delayedCall is just a tween that uses the function/callback as both its target
and its onComplete
, TweenMax.killTweensOf(myFunction)
produces exactly the
same result as TweenMax.killDelayedCallsTo(myFunction)
.
This method affects all delayedCalls that were created using TweenLite.delayedCall()
or TweenMax.delayedCall()
or the call()
or addCallback()
methods
of TimelineLite or TimelineMax. Basically, any tween whose target is the function you supply will
be killed.
Parameters
func:Function — The function for which all delayedCalls should be killed/cancelled.
|
killTweensOf | () | method |
public static function killTweensOf(target:*, vars:Object = null):void
Kills all the tweens (or specific tweening properties) 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:
TweenMax.killTweensOf(myObject);
To kill only particular tweening properties of the object, use the second parameter.
For example, if you only want to kill all the tweens of myObject.alpha
and
myObject.x
, you'd do this:
TweenMax.killTweensOf(myObject, {alpha:true, x:true});
To kill all the delayedCalls (like ones created using TweenMax.delayedCall(5, myFunction);
),
you can simply call TweenMax.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
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 whose tweens should be killed immediately
| |
vars:Object (default = null ) — To kill only specific properties, use a generic object containing enumerable properties corresponding to the ones that should be killed like {x:true, y:true} . The values assigned to each property of the object don't matter - the sole purpose of the object is for iteration over the named properties (in this case, x and y ). If no object (or null ) is defined, all matched tweens will be killed in their entirety.
|
pauseAll | () | method |
public static function pauseAll(tweens:Boolean = true, delayedCalls:Boolean = true, timelines:Boolean = true):void
[deprecated] Pauses all tweens and/or delayedCalls/callbacks and/or timelines. This literally
changes the paused
state of all affected tweens/delayedCalls/timelines, but a
more flexible way to globally control things is to use the TimelineLite.exportRoot()
method
which essentially wraps all of the tweens/timelines/delayedCalls on the root timeline into a
TimelineLite instance so that you can pause(), resume()
, or even reverse()
or alter the timeScale
without affecting animations that you create after the export.
This also avoids having to alter the paused
state of every individual
tween/delayedCall/timeline - controlling the TimelineLite that contains the exported animations
delivers the same effect visually, but does so in a more elegant and flexible way.
Parameters
tweens:Boolean (default = true ) — If true , all tweens will be paused.
| |
delayedCalls:Boolean (default = true ) — If true , all delayedCalls will be paused. timeline callbacks are treated the same as delayedCalls.
| |
timelines:Boolean (default = true ) — If true , all TimelineLite and TimelineMax instances will be paused (at least the ones who haven't finished and been removed from their parent timeline)
|
See also
progress | () | method |
public function progress(value:Number):*
Gets or sets the tween's progress which is a value between 0 and 1 indicating the position
of the virtual playhead (excluding repeats) where 0 is at the beginning, 0.5 is halfway complete,
and 1 is complete. If the tween has a non-zero repeat
defined, progress
and totalProgress
will be different because progress
doesn't include any
repeats or repeatDelays whereas totalProgress
does. For example, if a TweenMax instance
is set to repeat once, at the end of the first cycle totalProgress
would only be 0.5
whereas progress
would be 1. If you watched both properties over the course of the entire
animation, you'd see progress
go from 0 to 1 twice (once for each cycle) in the
same time it takes the totalProgress
to go from 0 to 1 once.
This method serves as both a getter and setter. Omitting the parameter returns the current
value (getter), whereas defining the parameter sets the value (setter) and returns the instance
itself for easier chaining, like myTween.progress(0.5).play();
var progress = myTween.progress(); //gets current progress myTween.progress( 0.25 ); //sets progress to one quarter finished
Parameters
value:Number (default = NaN ) — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
* — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
See also
repeat | () | method |
public function repeat(value:int = 0):*
Gets or sets the number of times that the tween should repeat after its first iteration. For example,
if repeat
is 1, the tween will play a total of twice (the initial play
plus 1 repeat). To repeat indefinitely, use -1. repeat
should always be an integer.
To cause the repeats to alternate between forward and backward, set yoyo
to
true
. To add a time gap between repeats, use repeatDelay
. You can
set the initial repeat
value via the vars
parameter, like:
TweenMax.to(mc, 1, {x:100, repeat:2});
This method serves as both a getter and setter. Omitting the parameter returns the current
value (getter), whereas defining the parameter sets the value (setter) and returns the instance
itself for easier chaining, like myTween.repeat(2).yoyo(true).play();
var repeat = myTween.repeat(); //gets current repeat value myTween.repeat(2); //sets repeat to 2
Parameters
value:int (default = 0 ) — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
* — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
See also
repeatDelay | () | method |
public function repeatDelay(value:Number):*
Gets or sets the amount of time in seconds (or frames for frames-based tweens) between repeats.
For example, if repeat
is 2 and repeatDelay
is 1, the tween will
play initially, then wait for 1 second before it repeats, then play again, then wait 1 second
again before doing its final repeat. You can set the initial repeatDelay
value
via the vars
parameter, like:
TweenMax.to(mc, 1, {x:100, repeat:2, repeatDelay:1});
This method serves as both a getter and setter. Omitting the parameter returns the current
value (getter), whereas defining the parameter sets the value (setter) and returns the instance
itself for easier chaining, like myTween.repeat(2).yoyo(true).repeatDelay(0.5).play();
var repeatDelay = myTween.repeatDelay(); //gets current repeatDelay value myTween.repeatDelay(2); //sets repeatDelay to 2
Parameters
value:Number (default = NaN ) — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
* — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
See also
resumeAll | () | method |
public static function resumeAll(tweens:Boolean = true, delayedCalls:Boolean = true, timelines:Boolean = true):void
[deprecated] Resumes all paused tweens and/or delayedCalls/callbacks and/or timelines. This literally
changes the paused
state of all affected tweens/delayedCalls/timelines, but a
more flexible way to globally control things is to use the TimelineLite.exportRoot()
method
which essentially wraps all of the tweens/timelines/delayedCalls on the root timeline into a
TimelineLite instance so that you can pause(), resume()
, or even reverse()
or alter the timeScale
without affecting animations that you create after the export.
This also avoids having to alter the paused
state of every individual
tween/delayedCall/timeline - controlling the TimelineLite that contains the exported animations
delivers the same effect visually, but does so in a more elegant and flexible way.
Parameters
tweens:Boolean (default = true ) — If true , all tweens will be resumed.
| |
delayedCalls:Boolean (default = true ) — If true , all delayedCalls will be resumed. timeline callbacks are treated the same as delayedCalls.
| |
timelines:Boolean (default = true ) — If true , all TimelineLite and TimelineMax instances will be resumed (at least the ones who haven't finished and been removed from their parent timeline)
|
See also
set | () | method |
public static function set(target:Object, vars:Object):TweenMax
Immediately sets properties of the target accordingly - essentially a zero-duration to()
tween with a more
intuitive name. So the following lines produce identical results:
TweenMax.set(myObject, {x:100, y:50, alpha:0}); TweenMax.to(myObject, 0, {x:100, y:50, alpha:0});
And of course you can use an array to set the properties of multiple targets at the same time, like:
TweenMax.set([obj1, obj2, obj3], {x:100, y:50, alpha:0});
Parameters
target:Object — Target object (or array of objects) whose properties will be affected.
| |
vars:Object — An object defining the value for each property that should be set. For example, to set mc.x to 100 and mc.y to 200, do this: TweenMax.set(mc, {x:100, y:200});
|
TweenMax — A TweenMax instance (with a duration of 0) which can optionally be inserted into a TimelineLite/Max instance (although it's typically more concise to just use the timeline's set() method).
|
staggerFrom | () | method |
public static function staggerFrom(targets:Array, duration:Number, vars:Object, stagger:Number = 0, onCompleteAll:Function = null, onCompleteAllParams:Array = null, onCompleteAllScope:* = null):Array
Tweens an array of targets from a common set of destination values (using the current values as the destination), but staggers their start times by a specified amount of time, creating an evenly-spaced sequence with a surprisingly small amount of code. For example, let's say you have an array containing references to a bunch of text fields that you'd like to drop into place while fading in, all in a staggered fashion with 0.2 seconds between each tween's start time:
var textFields = [tf1, tf2, tf3, tf4, tf5]; TweenMax.staggerFrom(textFields, 1, {y:"+150"}, 0.2);
staggerFrom()
simply loops through the targets
array and creates
a from()
tween for each object and then returns an array containing all of
the resulting tweens (one for each object).
If you can afford the slight increase in file size, it is usually better to use
TimelineLite's staggerFrom()
method because it wraps the tweens in a
TimelineLite instead of an array which makes controlling the group as a whole much
easier. That way you could pause(), resume(), reverse(), restart() or change the timeScale
of everything at once.
Note that if you define an onComplete
(or any callback for that matter)
in the vars
parameter, it will be called for each tween rather than the whole
sequence. This can be very useful, but if you want to call a function after the entire
sequence of tweens has completed, use the onCompleteAll
parameter (the 5th parameter).
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.
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 accept a 7th parameter for onCompleteAllScope
, but that parameter
is omitted in the AS3 version.
Parameters
targets:Array — An array of target objects whose properties should be affected
| |
duration:Number — Duration in seconds (or frames if useFrames:true is defined in the vars parameter)
| |
vars:Object — An object defining the end value for each property that should be tweened as well as any special properties like ease . For example, to tween x to 100 and y to 200 for mc1, mc2, and mc3, staggering their start time by 0.25 seconds and then call myFunction when they last one has finished, do this: TweenMax.staggerTo([mc1, mc2, mc3], 1, {x:100, y:200}, 0.25, myFunction}) .
| |
stagger:Number (default = 0 ) — Amount of time in seconds (or frames for frames-based tweens) to stagger the start time of each tween. For example, you might want to have 5 objects move down 100 pixels while fading out, and stagger the start times by 0.2 seconds - you could do: TweenMax.staggerTo([mc1, mc2, mc3, mc4, mc5], 1, {y:"+100", alpha:0}, 0.2) .
| |
onCompleteAll:Function (default = null ) — A function to call as soon as the entire sequence of tweens has completed
| |
onCompleteAllParams:Array (default = null ) — An array of parameters to pass the onCompleteAll method.
| |
onCompleteAllScope:* (default = null ) — The scope in which the onCompleteAll callback should be called (basically, what "this" refers to in the function). NOTE: this parameter only pertains to the JavaScript and AS2 versions; it is omitted in AS3.
|
Array — An array of TweenMax instances (one for each object in the targets array)
|
See also
staggerFromTo | () | method |
public static function staggerFromTo(targets:Array, duration:Number, fromVars:Object, toVars:Object, stagger:Number = 0, onCompleteAll:Function = null, onCompleteAllParams:Array = null, onCompleteAllScope:* = null):Array
Tweens an array of targets from and to a common set of values, but staggers their start times by a specified amount of time, creating an evenly-spaced sequence with a surprisingly small amount of code. For example, let's say you have an array containing references to a bunch of text fields that you'd like to fade from alpha:1 to alpha:0 in a staggered fashion with 0.2 seconds between each tween's start time:
var textFields = [tf1, tf2, tf3, tf4, tf5]; TweenMax.staggerFromTo(textFields, 1, {alpha:1}, {alpha:0}, 0.2);
staggerFromTo()
simply loops through the targets
array and creates
a fromTo()
tween for each object and then returns an array containing all of
the resulting tweens (one for each object).
If you can afford the slight increase in file size, it is usually better to use
TimelineLite's staggerFromTo()
method because it wraps the tweens in a
TimelineLite instead of an array which makes controlling the group as a whole much
easier. That way you could pause(), resume(), reverse(), restart() or change the timeScale
of everything at once.
Note that if you define an onComplete
(or any callback for that matter)
in the vars
parameter, it will be called for each tween rather than the whole
sequence. This can be very useful, but if you want to call a function after the entire
sequence of tweens has completed, use the onCompleteAll
parameter (the 6th parameter).
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 accept an 8th parameter for onCompleteAllScope
, but that parameter
is omitted in the AS3 version.
Parameters
targets:Array — An array of target objects whose properties should be affected
| |
duration:Number — Duration in seconds (or frames if useFrames:true is defined in the vars parameter)
| |
fromVars:Object — An object defining the starting value for each property that should be tweened. For example, to tween x from 100 and y from 200, fromVars would look like this: {x:100, y:200} .
| |
toVars:Object — An object defining the end value for each property that should be tweened as well as any special properties like ease . For example, to tween x from 0 to 100 and y from 0 to 200, staggering the start times by 0.2 seconds and then call myFunction when they all complete, do this: TweenMax.staggerFromTo([mc1, mc2, mc3], 1, {x:0, y:0}, {x:100, y:200}, 0.2, myFunction});
| |
stagger:Number (default = 0 ) — Amount of time in seconds (or frames if the timeline is frames-based) to stagger the start time of each tween. For example, you might want to have 5 objects move down 100 pixels while fading out, and stagger the start times by 0.2 seconds - you could do: TweenMax.staggerTo([mc1, mc2, mc3, mc4, mc5], 1, {y:"+100", alpha:0}, 0.2) .
| |
onCompleteAll:Function (default = null ) — A function to call as soon as the entire sequence of tweens has completed
| |
onCompleteAllParams:Array (default = null ) — An array of parameters to pass the onCompleteAll method.
| |
onCompleteAllScope:* (default = null ) — The scope in which the onCompleteAll callback should be called (basically, what "this" refers to in the function). NOTE: this parameter only pertains to the JavaScript and AS2 versions; it is omitted in AS3.
|
Array — An array of TweenMax instances (one for each object in the targets array)
|
See also
staggerTo | () | method |
public static function staggerTo(targets:Array, duration:Number, vars:Object, stagger:Number = 0, onCompleteAll:Function = null, onCompleteAllParams:Array = null, onCompleteAllScope:* = null):Array
Tweens an array of targets to a common set of destination values, but staggers their start times by a specified amount of time, creating an evenly-spaced sequence with a surprisingly small amount of code. For example, let's say you have an array containing references to a bunch of text fields that you'd like to fall away and fade out in a staggered fashion with 0.2 seconds between each tween's start time:
var textFields = [tf1, tf2, tf3, tf4, tf5]; TweenMax.staggerTo(textFields, 1, {y:"+150", ease:CubicIn.ease}, 0.2);
staggerTo()
simply loops through the targets
array and creates
a to()
tween for each object and then returns an array containing all of
the resulting tweens (one for each object).
If you can afford the slight increase in file size, it is usually better to use
TimelineLite's staggerTo()
method because it wraps the tweens in a
TimelineLite instead of an array which makes controlling the group as a whole much
easier. That way you could pause(), resume(), reverse(), restart() or change the timeScale
of everything at once.
Note that if you define an onComplete
(or any callback for that matter)
in the vars
parameter, it will be called for each tween rather than the whole
sequence. This can be very useful, but if you want to call a function after the entire
sequence of tweens has completed, use the onCompleteAll
parameter (the 5th parameter).
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 accept a 7th parameter for onCompleteAllScope
, but that parameter
is omitted in the AS3 version.
Parameters
targets:Array — An array of target objects whose properties should be affected
| |
duration:Number — Duration in seconds (or frames if useFrames:true is defined in the vars parameter)
| |
vars:Object — An object defining the end value for each property that should be tweened as well as any special properties like ease . For example, to tween x to 100 and y to 200 for mc1, mc2, and mc3, staggering their start time by 0.25 seconds and then call myFunction when they last one has finished, do this: TweenMax.staggerTo([mc1, mc2, mc3], 1, {x:100, y:200}, 0.25, myFunction}) .
| |
stagger:Number (default = 0 ) — Amount of time in seconds (or frames for frames-based tweens) to stagger the start time of each tween. For example, you might want to have 5 objects move down 100 pixels while fading out, and stagger the start times by 0.2 seconds - you could do: TweenMax.staggerTo([mc1, mc2, mc3, mc4, mc5], 1, {y:"+100", alpha:0}, 0.2) .
| |
onCompleteAll:Function (default = null ) — A function to call as soon as the entire sequence of tweens has completed.
| |
onCompleteAllParams:Array (default = null ) — An array of parameters to pass the onCompleteAll method.
| |
onCompleteAllScope:* (default = null ) — The scope in which the onCompleteAll callback should be called (basically, what "this" refers to in the function). NOTE: this parameter only pertains to the JavaScript and AS2 versions; it is omitted in AS3.
|
Array — Array of TweenMax tweens (one for each object in the targets array)
|
See also
time | () | method |
override public function time(value:Number, suppressEvents:Boolean = false):*
Gets or sets the local position of the playhead (essentially the current time), not
including any repeats or repeatDelays. If the tween has a non-zero repeat
, its time
goes back to zero upon repeating even though the totalTime
continues forward linearly
(or if yoyo
is true
, the time
alternates between moving forward
and backward). time
never exceeds the duration whereas the totalTime
reflects
the overall time including any repeats and repeatDelays.
For example, if a TweenMax instance has a duration
of 2 and a repeat of 3,
totalTime
will go from 0 to 8 during the course of the tween (plays once then
repeats 3 times, making 4 total cycles) whereas time
would go from 0 to 2 a
total of 4 times.
This method serves as both a getter and setter. Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
var currentTime = myTween.time(); //gets current time myTween.time(2); //sets time, jumping to new value just like seek().
Parameters
value:Number (default = NaN ) — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining. Negative values will be interpreted from the END of the animation.
| |
suppressEvents:Boolean (default = false ) — If true , no events or callbacks will be triggered when the playhead moves to the new position defined in the value parameter.
|
* — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
See also
to | () | method |
public static function to(target:Object, duration:Number, vars:Object):TweenMax
Static method for creating a TweenMax instance that animates to the specified destination values (from the current values). This static method 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 persistent variable. The following lines of code produce identical results:
TweenMax.to(mc, 1, {x:100}); var myTween = new TweenMax(mc, 1, {x:100}); var myTween = TweenMax.to(mc, 1, {x:100});
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 TweenMax.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:
TweenMax.to([mc1, mc2, mc3], 1, {x:100});
Even though 3 objects are animating, there is still only one tween created.
In order to stagger or offset the start times of each object animating, please see
the staggerTo()
method (TimelineLite has one too).
For simple sequencing, you can use the delay
special property
(like TweenMax.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.
Parameters
target:Object — Target object (or array of objects) whose properties this tween affects.
| |
duration:Number — Duration in seconds (or frames if useFrames:true is set in the vars parameter)
| |
vars:Object — 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: TweenMax.to(mc, 1, {x:100, y:200, onComplete:myFunction});
|
TweenMax — TweenMax instance
|
See also
totalDuration | () | method |
override public function totalDuration(value:Number):*
Gets or sets the total duration of the tween in seconds (or frames for frames-based tweens)
including any repeats or repeatDelays. duration
, by contrast, does
NOT include repeats and repeatDelays. For example, if the tween has a
duration
of 10, a repeat
of 1 and a repeatDelay
of 2,
the totalDuration
would be 22.
This method serves as both a getter and setter. Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
var total = myTween.totalDuration(); //gets total duration myTween.totalDuration(10); //sets the total duration
Parameters
value:Number (default = NaN ) — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining. Negative values will be interpreted from the END of the animation.
|
* — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
See also
totalProgress | () | method |
public function totalProgress(value:Number):*
Gets or sets the tween's totalProgress which is a value between 0 and 1 indicating the position
of the virtual playhead (including repeats) where 0 is at the beginning, 0.5 is halfway complete,
and 1 is complete. If the tween has a non-zero repeat
defined, progress
and totalProgress
will be different because progress
doesn't include
any repeats or repeatDelays whereas totalProgress
does. For example, if a TweenMax
instance is set to repeat once, at the end of the first cycle totalProgress
would
only be 0.5 whereas progress
would be 1. If you watched both properties over the
course of the entire animation, you'd see progress
go from 0 to 1 twice (once for
each cycle) in the same time it takes the totalProgress
to go from 0 to 1 once.
This method serves as both a getter and setter. Omitting the parameter returns the current
value (getter), whereas defining the parameter sets the value (setter) and returns the instance
itself for easier chaining, like myTween.totalProgress(0.5).play();
var progress = myTween.totalProgress(); //gets total progress myTween.totalProgress( 0.25 ); //sets total progress to one quarter finished
Parameters
value:Number (default = NaN ) — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
* — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
See also
updateTo | () | method |
public function updateTo(vars:Object, resetDuration:Boolean = false):*
Updates tweening values on the fly so that they appear to seamlessly change course even if
the tween is in-progress. Think of it like dynamically updating the vars
object
that was passed in to the tween when it was originally created. You do NOT
need to redefine all of the vars
properties/values - only the ones that you want
to update. You can even define new properties that you didn't define in the original vars
object.
If the resetDuration
parameter is true
and the tween has already
started (or finished), updateTo()
will restart the tween. Otherwise, the tween's
timing will be honored. And if resetDuration
is false
and the tween
is in-progress, the starting values of each property will be adjusted so that the tween appears
to seamlessly redirect to the new destination values. This is typically not advisable if you
plan to reverse the tween later on or jump to a previous point because the starting values would
have been adjusted.
updateTo()
is only meant for non-plugin values. It's much more complicated to
dynamically update values that are being handled inside plugins - that is not what this method
is intended to do.
Note: If you plan to constantly update values, please look into using the DynamicPropsPlugin
.
//create the tween var tween:TweenMax = new TweenMax(mc, 2, {x:100, y:200, alpha:0.5}); //then later, update the destination x and y values, restarting the tween tween.updateTo({x:300, y:0}, true); //or to update the values mid-tween without restarting, do this: tween.updateTo({x:300, y:0}, false);
Parameters
vars:Object — Object containing properties with the destination values that should be udpated. You do NOT need to redefine all of the original vars values - only the ones that should be updated (although if you change a plugin value, you will need to fully define it). For example, to update the destination x value to 300 and the destination y value to 500, pass: {x:300, y:500} .
| |
resetDuration:Boolean (default = false ) — If the tween has already started (or finished) and resetDuration is true , the tween will restart. If resetDuration is false , the tween's timing will be honored (no restart) and each tweening property's starting value will be adjusted so that it appears to seamlessly redirect to the new destination value.
|
* — self (makes chaining easier)
|
yoyo | () | method |
public function yoyo(value:Boolean = false):*
Gets or sets the tween's yoyo
state, where true
causes
the tween to go back and forth, alternating backward and forward on each
repeat
. yoyo
works in conjunction with repeat
,
where repeat
controls how many times the tween repeats, and yoyo
controls whether or not each repeat alternates direction. So in order to make a tween yoyo,
you must set its repeat
to a non-zero value.
Yoyo-ing, has no affect on the tween's "reversed
" property. For example,
if repeat
is 2 and yoyo
is false
, it will look like:
start - 1 - 2 - 3 - 1 - 2 - 3 - 1 - 2 - 3 - end. But if yoyo
is true
,
it will look like: start - 1 - 2 - 3 - 3 - 2 - 1 - 1 - 2 - 3 - end.
You can set the yoyo
property initially by passing yoyo:true
in the vars
parameter, like: TweenMax.to(mc, 1, {x:100, repeat:1, yoyo:true});
This method serves as both a getter and setter. Omitting the parameter returns the current
value (getter), whereas defining the parameter sets the value (setter) and returns the instance
itself for easier chaining, like myAnimation.yoyo(true).repeat(3).timeScale(2).play(0.5);
var yoyo = myAnimation.yoyo(); //gets current yoyo state myAnimation.yoyo( true ); //sets yoyo to true
Parameters
value:Boolean (default = false ) — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
* — Omitting the parameter returns the current value (getter), whereas defining the parameter sets the value (setter) and returns the instance itself for easier chaining.
|
See also