Packagecom.greensock
Classpublic class TimelineMax
InheritanceTimelineMax Inheritance TimelineLite Inheritance SimpleTimeline Inheritance TweenCore
Implementsflash.events.IEventDispatcher

TimelineMax extends TimelineLite, offering exactly the same functionality plus useful (but non-essential) features like AS3 event dispatching, repeat, repeatDelay, yoyo, currentLabel, addCallback(), removeCallback(), tweenTo(), tweenFromTo(), getLabelAfter(), getLabelBefore(), and getActive() (and probably more in the future). It is the ultimate sequencing tool. Think of a TimelineMax instance like a virtual MovieClip timeline or a container where you place tweens (or other timelines) over the course of time. You can: EXAMPLE:

import com.greensock.*;

//create the timeline and add an onComplete call to myFunction when the timeline completes
var myTimeline:TimelineMax = new TimelineMax({onComplete:myFunction});

//add a tween
myTimeline.append(new TweenLite(mc, 1, {x:200, y:100}));

//add another tween at the end of the timeline (makes sequencing easy)
myTimeline.append(new TweenLite(mc, 0.5, {alpha:0}));

//repeat the entire timeline twice
myTimeline.repeat = 2;

//delay the repeat by 0.5 seconds each time.
myTimeline.repeatDelay = 0.5;

//pause the timeline (stop() works too)
myTimeline.pause();

//reverse it anytime...
myTimeline.reverse();

//Add a "spin" label 3-seconds into the timeline.
myTimeline.addLabel("spin", 3);

//insert a rotation tween at the "spin" label (you could also define the insert point as the time instead of a label)
myTimeline.insert(new TweenLite(mc, 2, {rotation:"360"}), "spin");

//go to the "spin" label and play the timeline from there...
myTimeline.gotoAndPlay("spin");

//call myCallbackwhen the "virtual playhead" travels past the 1.5-second point. myTimeline.addCallback(myCallback, 1.5); //add a tween to the beginning of the timeline, pushing all the other existing tweens back in time
myTimeline.prepend(new TweenMax(mc, 1, {tint:0xFF0000}));

//nest another TimelineMax inside your timeline...
var nestedTimeline:TimelineMax = new TimelineMax();
nestedTimeline.append(new TweenLite(mc2, 1, {x:200}));
myTimeline.append(nestedTimeline);

insertMultiple() and appendMultiple() provide some very powerful sequencing tools as well, allowing you to add an Array of tweens/timelines and optionally align them with SEQUENCE or START modes, and even stagger them if you want. For example, to insert 3 tweens into the timeline, aligning their start times but staggering them by 0.2 seconds,

myTimeline.insertMultiple([new TweenLite(mc, 1, {y:"100"}), new TweenLite(mc2, 1, {x:120}), new TweenLite(mc3, 1, {alpha:0.5})], 0, TweenAlign.START, 0.2);

You can use the constructor's vars object to do all the setup too, like:

var myTimeline:TimelineMax = new TimelineMax({tweens:[new TweenLite(mc1, 1, {y:"100"}), TweenMax.to(mc2, 1, {tint:0xFF0000})], align:TweenAlign.SEQUENCE, onComplete:myFunction, repeat:2, repeatDelay:1});

If that confuses you, don't worry. Just use the append(), insert(), and prepend() methods to build your sequence. But power users will likely appreciate the quick, compact way they can set up sequences now.

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



Public Properties
 PropertyDefined by
 InheritedautoRemoveChildren : Boolean
If a timeline's autoRemoveChildren is true, its children will be removed and made eligible for garbage collection as soon as they complete.
SimpleTimeline
  currentLabel : String
[read-only] The closest label that is at or before the current time.
TimelineMax
 InheritedcurrentProgress : Number
Value between 0 and 1 indicating the progress of the timeline according to its duration where 0 is at the beginning, 0.5 is halfway finished, and 1 is finished.
TimelineLite
 InheritedcurrentTime : Number
Most recently rendered time (or frame for frames-based tweens/timelines) according to its duration.
TweenCore
 Inheriteddata : *
Place to store any data you want.
TweenCore
 Inheriteddelay : Number
Length of time in seconds (or frames for frames-based tweens/timelines) before the tween should begin.
TweenCore
 Inheritedduration : Number
Duration of the timeline in seconds (or frames for frames-based timelines) not including any repeats or repeatDelays.
TimelineLite
 Inheritedpaused : Boolean
Indicates the paused state of the tween/timeline.
TweenCore
  repeat : int
Number of times that the timeline should repeat; -1 repeats indefinitely.
TimelineMax
  repeatDelay : Number
Amount of time in seconds (or frames for frames-based timelines) between repeats
TimelineMax
 Inheritedreversed : Boolean
Indicates the reversed state of the tween/timeline.
TweenCore
 InheritedstartTime : Number
Start time in seconds (or frames for frames-based tweens/timelines), according to its position on its parent timeline
TweenCore
 Inheritedtimeline : SimpleTimeline
The parent timeline on which the tween/timeline is placed.
TweenCore
 InheritedtimeScale : Number
Multiplier describing the speed of the timeline where 1 is normal speed, 0.5 is half-speed, 2 is double speed, etc.
TimelineLite
  totalDuration : Number
[read-only] Duration of the timeline in seconds (or frames for frames-based timelines) including any repeats or repeatDelays.
TimelineMax
  totalProgress : Number
Value between 0 and 1 indicating the overall progress of the timeline according to its totalDuration where 0 is at the beginning, 0.5 is halfway finished, and 1 is finished.
TimelineMax
 InheritedtotalTime : Number
Most recently rendered time (or frame for frames-based tweens/timelines) according to its totalDuration.
TweenCore
 InheriteduseFrames : Boolean
Indicates whether or not the timeline's timing mode is frames-based as opposed to time-based.
TimelineLite
 Inheritedvars : Object
Stores variables (things like alpha, y or whatever we're tweening as well as special properties like "onComplete").
TweenCore
  yoyo : Boolean
Works in conjunction with the repeat property, determining the behavior of each cycle; when yoyo is true, the timeline will go back and forth, appearing to reverse every other cycle (this has no affect on the reversed property though).
TimelineMax
Public Methods
 MethodDefined by
  
TimelineMax(vars:Object = null)
Constructor.
TimelineMax
  
addCallback(callback:Function, timeOrLabel:Array, params:* = null):TweenLite
If you want a function to be called at a particular time or label, use addCallback.
TimelineMax
 Inherited
addLabel(label:String, time:Number):void
Adds a label to the timeline, making it easy to mark important positions/times.
TimelineLite
 Inherited
append(tween:TweenCore, offset:Number = 0):TweenCore
Inserts a TweenLite, TweenMax, TimelineLite, or TimelineMax instance at the end of the timeline, optionally offsetting its insertion point by a certain amount (to make it overlap with the end of the timeline or leave a gap before its insertion point).
TimelineLite
 Inherited
appendMultiple(tweens:Array, offset:Number = 0, align:String = "normal", stagger:Number = 0):Array
Appends multiple tweens/timelines at the end of the timeline at once, optionally offsetting the insertion point by a certain amount, aligning them (as a sequence for example), and/or staggering their relative timing.
TimelineLite
 Inherited
clear(tweens:Array = null):void
Empties the timeline of all child tweens/timelines, or you can optionally pass an Array containing specific tweens/timelines to remove.
TimelineLite
  
complete(skipRender:Boolean = false, suppressEvents:Boolean = false):void
Forces the timeline to completion.
TimelineMax
  
getActive(nested:Boolean = true, tweens:Boolean = true, timelines:Boolean = false):Array
Returns the tweens/timelines that are currently active in the timeline.
TimelineMax
 Inherited
getChildren(nested:Boolean = true, tweens:Boolean = true, timelines:Boolean = true, ignoreBeforeTime:Number = -9999999999):Array
Provides an easy way to get all of the tweens and/or timelines nested in this timeline (as an Array).
TimelineLite
  
getLabelAfter(time:Number):String
Returns the next label (if any) that occurs AFTER the time parameter.
TimelineMax
  
getLabelBefore(time:Number):String
Returns the previous label (if any) that occurs BEFORE the time parameter.
TimelineMax
 Inherited
getLabelTime(label:String):Number
Returns the time associated with a particular label.
TimelineLite
 Inherited
getTweensOf(target:Object, nested:Boolean = true):Array
Returns the tweens of a particular object that are inside this timeline.
TimelineLite
 Inherited
goto(timeOrLabel:*, suppressEvents:Boolean = true):void
Skips to a particular time, frame, or label without changing the paused state of the timeline
TimelineLite
 Inherited
gotoAndPlay(timeOrLabel:*, suppressEvents:Boolean = true):void
Skips to a particular time, frame, or label and plays the timeline forwards from there (unpausing it)
TimelineLite
 Inherited
gotoAndStop(timeOrLabel:*, suppressEvents:Boolean = true):void
Skips to a particular time, frame, or label and stops the timeline (pausing it)
TimelineLite
 Inherited
insert(tween:TweenCore, timeOrLabel:* = 0):TweenCore
Inserts a TweenLite, TweenMax, TimelineLite, or TimelineMax instance into the timeline at a specific time, frame, or label.
TimelineLite
 Inherited
insertMultiple(tweens:Array, timeOrLabel:String = "0", align:Number = normal, stagger:* = 0):Array
Inserts multiple tweens/timelines into the timeline at once, optionally aligning them (as a sequence for example) and/or staggering the timing.
TimelineLite
  
invalidate():void
Clears any initialization data (like starting values in tweens) which can be useful if, for example, you want to restart it without reverting to any previously recorded starting values.
TimelineMax
 Inherited
kill():void
Kills the tween/timeline, stopping it immediately.
TweenCore
 Inherited
killTweensOf(target:Object, nested:Boolean = true, vars:Object = null):Boolean
Kills all the tweens (or certain tweening properties) of a particular object inside this TimelineLite, optionally completing them first.
TimelineLite
 Inherited
pause():void
Pauses the tween/timeline
TweenCore
 Inherited
play():void
Starts playing forward from the current position.
TweenCore
 Inherited
prepend(tween:TweenCore, adjustLabels:Boolean = false):TweenCore
Inserts a TweenLite, TweenMax, TimelineLite, or TimelineMax instance at the beginning of the timeline, pushing all existing tweens back in time to make room for the newly inserted one.
TimelineLite
 Inherited
prependMultiple(tweens:Array, align:String = "normal", stagger:Number = 0, adjustLabels:Boolean = false):Array
Prepends multiple tweens/timelines to the beginning of the timeline at once, moving all existing children back to make room, and optionally aligning the new children (as a sequence for example) and/or staggering the timing.

TimelineLite
 Inherited
remove(tween:TweenCore, skipDisable:Boolean = false):void
Removes a TweenLite, TweenMax, TimelineLite, or TimelineMax instance from the timeline.
TimelineLite
  
removeCallback(callback:Function, timeOrLabel:* = null):Boolean
Removes a callback from a particular time or label.
TimelineMax
 Inherited
removeLabel(label:String):Number
Removes a label from the timeline and returns the time of that label.
TimelineLite
 Inherited
restart(includeDelay:Boolean = false, suppressEvents:Boolean = true):void
Restarts and begins playing forward.
TweenCore
 Inherited
resume():void
Starts playing from the current position without altering direction (forward or reversed).
TweenCore
 Inherited
reverse(forceResume:Boolean = true):void
Reverses smoothly, adjusting the startTime to avoid any skipping.
TweenCore
 Inherited
shiftChildren(amount:Number, adjustLabels:Boolean = false, ignoreBeforeTime:Number = 0):void
Shifts the startTime of the timeline's children by a certain amount and optionally adjusts labels too.
TimelineLite
 Inherited
stop():void
Pauses the timeline (same as pause() - added stop() for consistency with Flash's MovieClip.stop() functionality)
TimelineLite
  
tweenFromTo(fromTimeOrLabel:*, toTimeOrLabel:Object, vars:* = null):TweenLite
Creates a linear tween that essentially scrubs the playhead from a particular time or label to another time or label and then stops.
TimelineMax
  
tweenTo(timeOrLabel:*, vars:Object = null):TweenLite
Creates a linear tween that essentially scrubs the playhead to a particular time or label and then stops.
TimelineMax
Property detail
currentLabelproperty
currentLabel:String  [read-only]

The closest label that is at or before the current time.

Implementation
    public function get currentLabel():String
repeatproperty 
repeat:int  [read-write]

Number of times that the timeline should repeat; -1 repeats indefinitely.

Implementation
    public function get repeat():int
    public function set repeat(value:int):void
repeatDelayproperty 
repeatDelay:Number  [read-write]

Amount of time in seconds (or frames for frames-based timelines) between repeats

Implementation
    public function get repeatDelay():Number
    public function set repeatDelay(value:Number):void
totalDurationproperty 
totalDuration:Number  [read-only]

Duration of the timeline in seconds (or frames for frames-based timelines) including any repeats or repeatDelays. "duration", by contrast, does NOT include repeats and repeatDelays.

Implementation
    public function get totalDuration():Number
totalProgressproperty 
totalProgress:Number  [read-write]

Value between 0 and 1 indicating the overall progress of the timeline according to its totalDuration where 0 is at the beginning, 0.5 is halfway finished, and 1 is finished. currentProgress, by contrast, describes the progress according to the timeline's duration which does not include repeats and repeatDelays. For example, if a TimelineMax instance is set to repeat once, at the end of the first cycle totalProgress would only be 0.5 whereas currentProgress would be 1. If you tracked both properties over the course of the tween, you'd see currentProgress go from 0 to 1 twice (once for each cycle) in the same time it takes the totalProgress property to go from 0 to 1 once.

Implementation
    public function get totalProgress():Number
    public function set totalProgress(value:Number):void
yoyoproperty 
public var yoyo:Boolean

Works in conjunction with the repeat property, determining the behavior of each cycle; when yoyo is true, the timeline will go back and forth, appearing to reverse every other cycle (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 repeat is 2 and yoyo is true, it will look like: start - 1 - 2 - 3 - 3 - 2 - 1 - 1 - 2 - 3 - end.

Constructor detail
TimelineMax()constructor
public function TimelineMax(vars:Object = null)

Constructor.

SPECIAL PROPERTIES
The following special properties may be passed in via the constructor's vars parameter, like new TimelineMax({paused:true, onComplete:myFunction, repeat:2, yoyo:true})

Parameters
vars:Object (default = null) — optionally pass in special properties like useFrames, onComplete, onCompleteParams, onUpdate, onUpdateParams, onStart, onStartParams, tweens, align, stagger, delay, autoRemoveChildren, onCompleteListener, onStartListener, onUpdateListener, repeat, repeatDelay, and/or yoyo.
Method detail
addCallback()method
public function addCallback(callback:Function, timeOrLabel:Array, params:* = null):TweenLite

If you want a function to be called at a particular time or label, use addCallback. When you add a callback, it is technically considered a zero-duration tween, so if you getChildren() there will be a tween returned for each callback. You can discern a callback from other tweens by the fact that their target is a function and the duration is zero.

Parameters
callback:Function — the function to be called
 
timeOrLabel:Array — the time in seconds (or frames for frames-based timelines) or label at which the callback should be inserted. For example, myTimeline.addCallback(myFunction, 3) would call myFunction() 3-seconds into the timeline, and myTimeline.addCallback(myFunction, "myLabel") would call it at the "myLabel" label.
 
params:* (default = null) — an Array of parameters to pass the callback

Returns
TweenLite — TweenLite instance
complete()method 
public override function complete(skipRender:Boolean = false, suppressEvents:Boolean = false):void

Forces the timeline to completion.

Parameters
skipRender:Boolean (default = false) — to skip rendering the final state of the timeline, set skipRender to true.
 
suppressEvents:Boolean (default = false) — If true, no events or callbacks will be triggered for this render (like onComplete, onUpdate, onReverseComplete, etc.)
getActive()method 
public function getActive(nested:Boolean = true, tweens:Boolean = true, timelines:Boolean = false):Array

Returns the tweens/timelines that are currently active in the timeline.

Parameters
nested:Boolean (default = true) — determines whether or not tweens and/or timelines that are inside nested timelines should be returned. If you only want the "top level" tweens/timelines, set this to false.
 
tweens:Boolean (default = true) — determines whether or not tweens (TweenLite and TweenMax instances) should be included in the results
 
timelines:Boolean (default = false) — determines whether or not timelines (TimelineLite and TimelineMax instances) should be included in the results

Returns
Array — an Array of active tweens/timelines
getLabelAfter()method 
public function getLabelAfter(time:Number):String

Returns the next label (if any) that occurs AFTER the time parameter. It makes no difference if the timeline is reversed. A label that is positioned exactly at the same time as the time parameter will be ignored.

Parameters
time:Number — Time after which the label is searched for. If you do not pass a time in, the currentTime will be used.

Returns
String — Name of the label that is after the time passed to getLabelAfter()
getLabelBefore()method 
public function getLabelBefore(time:Number):String

Returns the previous label (if any) that occurs BEFORE the time parameter. It makes no difference if the timeline is reversed. A label that is positioned exactly at the same time as the time parameter will be ignored.

Parameters
time:Number — Time before which the label is searched for. If you do not pass a time in, the currentTime will be used.

Returns
String — Name of the label that is before the time passed to getLabelBefore()
invalidate()method 
public override function invalidate():void

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

removeCallback()method 
public function removeCallback(callback:Function, timeOrLabel:* = null):Boolean

Removes a callback from a particular time or label. If timeOrLabel is null, all callbacks of that particular function are removed from the timeline.

Parameters
callback:Function — callback function to be removed
 
timeOrLabel:* (default = null) — the time in seconds (or frames for frames-based timelines) or label from which the callback should be removed. For example, myTimeline.removeCallback(myFunction, 3) would remove the callback from 3-seconds into the timeline, and myTimeline.removeCallback(myFunction, "myLabel") would remove it from the "myLabel" label, and myTimeline.removeCallback(myFunction, null) would remove ALL callbacks of that function regardless of where they are on the timeline.

Returns
Boolean — true if any callbacks were successfully found and removed. false otherwise.
tweenFromTo()method 
public function tweenFromTo(fromTimeOrLabel:*, toTimeOrLabel:Object, vars:* = null):TweenLite

Creates a linear tween that essentially scrubs the playhead from a particular time or label to another time or label and then stops. If you plan to sequence multiple playhead tweens one-after-the-other, tweenFromTo() is better to use than tweenTo() because it allows the duration to be determined immediately, ensuring that subsequent tweens that are appended to a sequence are positioned appropriately. For example, to make the TimelineMax play from the label "myLabel1" to the "myLabel2" label, and then from "myLabel2" back to the beginning (a time of 0), simply do:

var playheadTweens:TimelineMax = new TimelineMax();
playheadTweens.append( myTimeline.tweenFromTo("myLabel1", "myLabel2") );
playheadTweens.append( myTimeline.tweenFromTo("myLabel2", 0);

If you want advanced control over the tween, like adding an onComplete or changing the ease or adding a delay, just pass in a vars object with the appropriate properties. For example, to tween from the start (0) to the 5-second point on the timeline and then call a function named myFunction and pass in a parameter that's references this TimelineMax and use a Strong.easeOut ease, you'd do:

myTimeline.tweenFromTo(0, 5, {onComplete:myFunction, onCompleteParams:[myTimeline], ease:Strong.easeOut});

Remember, this method simply creates a TweenLite instance that tweens the currentTime property of your timeline. So you can store a reference to that tween if you want, and you can kill() it anytime. Also note that tweenFromTo() does NOT affect the timeline's reversed property. So if your timeline is oriented normally (not reversed) and you tween to a time/label that precedes the current time, it will appear to go backwards but the reversed property will not change to true. Also note that tweenFromTo() pauses the timeline immediately before tweening its currentTime property, and it stays paused after the tween completes. If you need to resume playback, you could always use an onComplete to call the resume() method.

Parameters
fromTimeOrLabel:* — The beginning time in seconds (or frame if the timeline is frames-based) or label from which the timeline should play. For example, myTimeline.tweenTo(0, 5) would play from 0 (the beginning) to the 5-second point whereas myTimeline.tweenFromTo("myLabel1", "myLabel2") would play from "myLabel1" to "myLabel2".
 
toTimeOrLabel:Object — The destination time in seconds (or frame if the timeline is frames-based) or label to which the timeline should play. For example, myTimeline.tweenTo(0, 5) would play from 0 (the beginning) to the 5-second point whereas myTimeline.tweenFromTo("myLabel1", "myLabel2") would play from "myLabel1" to "myLabel2".
 
vars:* (default = null) — An optional vars object that will be passed to the TweenLite instance. This allows you to define an onComplete, ease, delay, or any other TweenLite special property. onInit is the only special property that is not available (tweenFromTo() sets it internally)

Returns
TweenLite — TweenLite instance that handles tweening the timeline between the desired times/labels.

See also

tweenTo()method 
public function tweenTo(timeOrLabel:*, vars:Object = null):TweenLite

Creates a linear tween that essentially scrubs the playhead to a particular time or label and then stops. For example, to make the TimelineMax play to the "myLabel2" label, simply do:

myTimeline.tweenTo("myLabel2");

If you want advanced control over the tween, like adding an onComplete or changing the ease or adding a delay, just pass in a vars object with the appropriate properties. For example, to tween to the 5-second point on the timeline and then call a function named myFunction and pass in a parameter that's references this TimelineMax and use a Strong.easeOut ease, you'd do:

myTimeline.tweenTo(5, {onComplete:myFunction, onCompleteParams:[myTimeline], ease:Strong.easeOut});

Remember, this method simply creates a TweenLite instance that tweens the currentTime property of your timeline. So you can store a reference to that tween if you want, and you can kill() it anytime. Also note that tweenTo() does NOT affect the timeline's reversed property. So if your timeline is oriented normally (not reversed) and you tween to a time/label that precedes the current time, it will appear to go backwards but the reversed property will not change to true. Also note that tweenTo() pauses the timeline immediately before tweening its currentTime property, and it stays paused after the tween completes. If you need to resume playback, you could always use an onComplete to call the resume() method.

If you plan to sequence multiple playhead tweens one-after-the-other, it is typically better to use tweenFromTo() so that you can define the starting point and ending point, allowing the duration to be accurately determined immediately.

Parameters
timeOrLabel:* — The destination time in seconds (or frame if the timeline is frames-based) or label to which the timeline should play. For example, myTimeline.tweenTo(5) would play from wherever the timeline is currently to the 5-second point whereas myTimeline.tweenTo("myLabel") would play to wherever "myLabel" is on the timeline.
 
vars:Object (default = null) — An optional vars object that will be passed to the TweenLite instance. This allows you to define an onComplete, ease, delay, or any other TweenLite special property. onInit is the only special property that is not available (tweenTo() sets it internally)

Returns
TweenLite — TweenLite instance that handles tweening the timeline to the desired time/label.

See also