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})

• delay : Number - Amount of delay in seconds (or frames for frames-based tweens) before the timeline should begin.
• paused : Boolean - If true, the timeline will pause itself immediately upon creation (by default, timelines automatically begin playing immediately). If you plan to create a TimelineMax and then populate it later (after one or more frames elapse), it is typically best to set paused:true and then play() after you populate it.
• onComplete : Function - A function that should be called when the timeline has completed
• onCompleteParams : Array - An Array of parameters to pass the onComplete function. For example, new TimelineMax({onComplete:myFunction, onCompleteParams:["param1", "param2"]});
• useFrames : Boolean - If useFrames is true, the timelines'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.
• tweens : Array - To immediately insert several tweens into the timeline, use the tweens special property to pass in an Array of TweenLite/TweenMax/TimelineLite/TimelineMax instances. You can use this in conjunction with the align and stagger special properties to set up complex sequences with minimal code. These values simply get passed to the add() method.
• align : String - Only used in conjunction with the tweens special property when multiple tweens are to be inserted immediately. The value simply gets passed to the add() method. The default is "normal". Options are:
  • "sequence": aligns the tweens one-after-the-other in a sequence
  • "start": aligns the start times of all of the tweens (ignores delays)
  • "normal": aligns the start times of all the tweens (honors delays)
  The align special property does not force all child tweens/timelines to maintain relative positioning, so for example, if you use "sequence" and then later change the duration of one of the nested tweens, it does not force all subsequent timelines to change their position. The align special property only affects the alignment of the tweens that are initially placed into the timeline through the tweens special property of the vars object.
• stagger : Number - Only used in conjunction with the tweens special property when multiple tweens are to be inserted immediately. It staggers the tweens by a set amount of time in seconds (or in frames if useFrames is true). For example, if the stagger value is 0.5 and the "align" property is set to "start", the second tween will start 0.5 seconds after the first one starts, then 0.5 seconds later the third one will start, etc. If the align property is "sequence", there would be 0.5 seconds added between each tween. This value simply gets passed to the add() method. Default is 0.
• onStart : Function - A function that should be called when the timeline begins (when its time changes from 0 to some other value which can happen more than once if the timeline is restarted multiple times).
• onStartParams : Array - An Array of parameters to pass the onStart function. For example, new TimelineMax({onStart:myFunction, onStartParams:["param1", "param2"]});
• onUpdate : Function - A function that should be called every time the timeline updates (on every frame while the timeline is active)
• onUpdateParams : Array - An Array of parameters to pass the onUpdate function. For example, new TimelineMax({onUpdate:myFunction, onUpdateParams:["param1", "param2"]});
• onReverseComplete : Function - A function that should be called when the timeline has reached its beginning again from the reverse direction. For example, if reverse() is called, the timeline will move back towards its beginning and when its time reaches 0, onReverseComplete will be called. This can also happen if the timeline is placed in a TimelineLite or TimelineMax instance that gets reversed and plays the timeline backwards to (or past) the beginning.
• onReverseCompleteParams : Array - An Array of parameters to pass the onReverseComplete function. For example, new TimelineMax({onReverseComplete:myFunction, onReverseCompleteParams:["param1", "param2"]});
• autoRemoveChildren : Boolean - If autoRemoveChildren is set to true, as soon as child tweens/timelines complete, they will automatically get killed/removed. This is normally undesireable because it prevents going backwards in time (like if you want to reverse() or set the progress lower, etc.). It can, however, improve speed and memory management. The root timelines use autoRemoveChildren:true.
• smoothChildTiming : Boolean - Controls whether or not child tweens/timelines are repositioned automatically (changing their startTime) in order to maintain smooth playback when properties are changed on-the-fly. For example, imagine that the timeline's playhead is on a child tween that is 75% complete, moving mc.x from 0 to 100 and then that tween's reverse() method is called. If smoothChildTiming is false (the default except for the root timelines), the tween would flip in place, keeping its startTime consistent. Therefore the playhead of the timeline would now be at the tween's 25% completion point instead of 75%. Remember, the timeline's playhead position and direction are unaffected by child tween/timeline changes. mc.x would jump from 75 to 25, but the tween's position in the timeline would remain consistent. However, if smoothChildTiming is true, that child tween's startTime would be adjusted so that the timeline's playhead intersects with the same spot on the tween (75% complete) as it had immediately before reverse() was called, thus playback appears perfectly smooth. mc.x would still be 75 and it would continue from there as the playhead moves on, but since the tween is reversed now mc.x will travel back towards 0 instead of 100. Ultimately it's a decision between prioritizing smooth on-the-fly playback (true) or consistent position(s) of child tweens/timelines (false). Some examples of on-the-fly changes to child tweens/timelines that could cause their startTime to change when smoothChildTiming is true are: reversed, timeScale, progress, totalProgress, time, totalTime, delay, pause, resume, duration, and totalDuration.
• repeat : Number - Number of times that the timeline should repeat after its first iteration. For example, if repeat is 1, the timeline will play a total of twice (the initial play plus 1 repeat). To repeat indefinitely, use -1. repeat should always be an integer.
• repeatDelay : Number - Amount of time in seconds (or frames for frames-based timelines) between repeats. For example, if repeat is 2 and repeatDelay is 1, the timeline will play initially, then wait for 1 second before it repeats, then play again, then wait 1 second again before doing its final repeat.
• yoyo : Boolean - If true, every other repeat cycle will run in the opposite direction so that the timeline 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.
• onRepeat : Function - A function that should be called each time the timeline repeats
• onRepeatParams : Array - An Array of parameters to pass the onRepeat function. For example, new TimelineMax({repeat:3, onRepeat:myFunction, onRepeatParams:[mc, "param2"]});
• onStartListener : Function - A function that should be called (and passed an event parameter) when the timeline begins (when its totalTime changes from 0 to some other value which can happen more than once if the timeline is restarted multiple times). Identical to onStart except that the function will always be passed an event parameter whose target property points to the timeline. It's the same as doing myTimeline.addEventListener("start", myFunction);. Unless you need the event parameter, it's better/faster to use onStart.
• onUpdateListener : Function - A function that should be called (and passed an event parameter) each time the timeline updates (on every frame while the timeline is active). Identical to onUpdate except that the function will always be passed an event parameter whose target property points to the timeline. It's the same as doing myTimeline.addEventListener("update", myFunction);. Unless you need the event parameter, it's better/faster to use onUpdate.
• onCompleteListener : Function - A function that should be called (and passed an event parameter) each time the timeline completes. Identical to onComplete except that the function will always be passed an event parameter whose target property points to the timeline. It's the same as doing myTimeline.addEventListener("complete", myFunction);. Unless you need the event parameter, it's better/faster to use onComplete.
• onReverseCompleteListener : Function - A function that should be called (and passed an event parameter) each time the timeline has reached its beginning again from the reverse direction. For example, if reverse() is called the timeline will move back towards its beginning and when its totalTime reaches 0, onReverseCompleteListener will be called. This can also happen if the timeline is placed in another TimelineLite or TimelineMax instance that gets reversed and plays the timeline backwards to (or past) the beginning. Identical to onReverseComplete except that the function will always be passed an event parameter whose target property points to the timeline. It's the same as doing myTimeline.addEventListener("reverseComplete", myFunction);. Unless you need the event parameter, it's better/faster to use onReverseComplete.
• onRepeatListener : Function - A function that should be called (and passed an event parameter) each time the timeline repeats. Identical to onRepeat except that the function will always be passed an event parameter whose target property points to the timeline. It's the same as doing myTimeline.addEventListener("repeat", myFunction);. Unless you need the event parameter, it's better/faster to use onRepeat.

Inserts a callback at a particular position. The callback 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 its target is a function matching its vars.onComplete and its duration is zero.

If your goal is to append the callback to the end of the timeline, it would be easier (more concise) to use the call() method. Technically the add() method can accommodate adding a callback too (like myTimeline.add(myFunction, 2) or myTimeline.add(myFunction, "+=2")) but add() doesn't accommodate parameters.

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 extra (4th) parameter for scope.

Parameters

See also

(AS3 only) Registers a function that should be called each time a particular type of event occurs, like "complete" or "update". The function will be passed a single "event" parameter whose "target" property refers to the timeline. Typically it is more efficient to use callbacks like onComplete, onUpdate, onStart, onReverseComplete, and onRepeat unless you need the event parameter or if you need to register more than one listener for the same type of event. If you no longer need an event listener, remove it by calling removeEventListener(), or memory problems could result. Event listeners are not automatically removed from memory because the garbage collector does not remove the listener as long as the dispatching object exists (unless the useWeakReference parameter is set to true).

Parameters

See also

Gets the closest label that is at or before the current time, or jumps to a provided label (behavior depends on whether or not you pass a parameter to the method).

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.

Parameters

See also

Returns the tweens/timelines that are currently active in the timeline, meaning the timeline's playhead is positioned on the child tween/timeline and the child isn't paused.

Parameters

Returns the next label (if any) that occurs after the time parameter. It makes no difference if the timeline is reversed ("after" means later in the timeline's local time zone). A label that is positioned exactly at the same time as the time parameter will be ignored.

You could use getLabelAfter() in conjunction with tweenTo() to make the timeline tween to the next label like this:

myTimeline.tweenTo( myTimeline.getLabelAfter() );

Parameters

See also

Returns the previous label (if any) that occurs before the time parameter. It makes no difference if the timeline is reversed ("before" means earlier in the timeline's local time zone). A label that is positioned exactly at the same time as the time parameter will be ignored.

You could use getLabelBefore() in conjunction with tweenTo() to make the timeline tween back to the previous label like this:

myTimeline.tweenTo( myTimeline.getLabelBefore() );

Parameters

See also

Returns an Array of label objects, each with a "time" and "name" property, in the order that they occur in the timeline. For example, to loop through all the labels in order and trace() them to the screen (or console.log() in JavaScript):

var labels = myTimeline.getLabelsArray();
for (var i = 0; i < labels.length; i++) {
    trace("label name: " + labels[i].name + ", time: " + labels[i].time); //or in JS, console.log("label name: " + labels[i].name + ", time: " + labels[i].time);
}

Note: changing the values in this array will have no effect on the actual labels inside the TimelineMax. To add/remove labels, use the corresponding methods (addLabel(), removeLabel()).

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.

Gets or sets the timeline'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 timeline 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 TimelineMax 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 myTimeline.progress(0.5).play();

var progress = myTimeline.progress(); //gets current progress
myTimeline.progress( 0.25 ); //sets progress to one quarter finished

Parameters

See also

Removes a callback. If the position parameter is null, all callbacks of that function are removed from the timeline.

Parameters

See also

(AS3 only) Removes a listener from the EventDispatcher object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.

Parameters

Gets or sets the number of times that the timeline should repeat after its first iteration. For example, if repeat is 1, the timeline 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:

var tl = new TimelineMax({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 myTimeline.repeat(2).yoyo(true).play();

var repeat = myTimeline.repeat(); //gets current repeat value
myTimeline.repeat(2); //sets repeat to 2

Parameters

See also

Gets or sets the amount of time in seconds (or frames for frames-based timelines) between repeats. For example, if repeat is 2 and repeatDelay is 1, the timeline 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:

var tl = new TimelineMax({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 myTimeline.repeat(2).yoyo(true).repeatDelay(0.5).play();

var repeatDelay = myTimeline.repeatDelay(); //gets current repeatDelay value
myTimeline.repeatDelay(2); //sets repeatDelay to 2

Parameters

See also

Gets or sets the local position of the playhead (essentially the current time), not including any repeats or repeatDelays. If the timeline 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 TimelineMax instance has a duration of 2 and a repeat of 3, totalTime will go from 0 to 8 during the course of the timeline (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 = myTimeline.time(); //gets current time
myTimeline.time(2); //sets time, jumping to new value just like seek().
         

Parameters

See also

Gets or sets the total 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. For example, if the timeline 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 = myTimeline.totalDuration(); //gets total duration
myTimeline.totalDuration(10); //sets the total duration
         

Parameters

See also

Gets or sets the timeline's total progress 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 at the halfway point, and 1 is at the end (complete). If the timeline has a non-zero repeat defined, progress() and totalProgress() will be different because progress() doesn't include the repeat or repeatDelay whereas totalProgress() does. 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 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 myAnimation.totalProgress(0.5).play();

var progress = myAnimation.totalProgress(); //gets total progress
myAnimation.totalProgress(0.25); //sets total progress to one quarter finished
         

Parameters

See also

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 tl:TimelineMax = new TimelineMax(); 
tl.add( myTimeline.tweenFromTo("myLabel1", "myLabel2") );
tl.add( 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 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 time() 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 time(), and it does not automatically resume after the tween completes. If you need to resume playback, you can always use an onComplete to call the resume() method.

Like all from-type methods in GSAP, immediateRender is true by default, meaning the timeline will immediately jump to the "from" time/label unless you set immediateRender:false

Parameters

See also

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 pauses the timeline and then tweens the time() of the 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 state. 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 state will not change to true. Also note that tweenTo() pauses the timeline immediately before tweening its time(), and it does not automatically resume after the tween completes. If you need to resume playback, you could always use an onComplete to call the timeline's 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

See also

Gets or sets the timeline's yoyo state, where true causes the timeline 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 timeline repeats, and yoyo controls whether or not each repeat alternates direction. So in order to make a timeline yoyo, you must set its repeat to a non-zero value. Yoyo-ing, has no affect on the timeline'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: new TimelineMax({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 myTimeline.yoyo(true).repeat(3).timeScale(2).play(0.5);

var yoyo = myTimeline.yoyo(); //gets current yoyo state
myTimeline.yoyo( true ); //sets yoyo to true

Parameters

See also

//create the timeline that repeats 3 times with 1 second between each repeat and then calls myFunction() when it completes
var tl = new TimelineMax({repeat:3, repeatDelay:1, onComplete:myFunction});
//add a tween
tl.add( new TweenLite(mc, 1, {x:200, y:100}) );
        
//add another tween at the end of the timeline (makes sequencing easy)
tl.add( new TweenLite(mc, 0.5, {alpha:0}) );
 
//append a tween using the convenience method (shorter syntax) and offset it by 0.5 seconds
tl.to(mc, 1, {rotation:30}, "+=0.5");
         
//reverse anytime
tl.reverse();
//Add a "spin" label 3-seconds into the timeline
tl.addLabel("spin", 3);
//insert a rotation tween at the "spin" label (you could also define the insertion point as the time instead of a label)
tl.add( new TweenLite(mc, 2, {rotation:"360"}), "spin");
    
//go to the "spin" label and play the timeline from there
tl.play("spin");
//nest another TimelineMax inside your timeline...
var nested = new TimelineMax();
nested.to(mc2, 1, {x:200}));
tl.add(nested);

How do timelines work? What are the mechanics like?

Every animation (tween and timeline) is placed on a parent timeline (except the 2 root timelines - there's one for normal tweens and another for "useFrames" ones). In a sense, they all have their own playheads (that's what its "time" refers to, or "totalTime" which is identical except that it includes repeats and repeatDelays) but generally they're not independent because they're sitting on a timeline whose playhead moves. When the parent's playhead moves to a new position, it updates the childrens' too.

When a timeline renders at a particular time, it loops through its children and says "okay, you should render as if your playhead is at ____" and if that child is a timeline with children, it does the same to its children, right on down the line.

The only exception is when the tween/timeline is paused in which case its internal playhead acts like it's "locked". So in that case, it's possible (likely in fact) that the child's playhead would not be synced with the parent's. When you unpause it (resume()), it essentially picks it up and moves it so that its internal playhead is synchronized with wherever the parent's playhead is at that moment, thus things play perfectly smoothly. That is, unless the timeline's smoothChildTiming is to false in which case it won't move - its startTime will remain locked to where it was.

So basically, when smoothChildTiming is true, the engine will rearrange things on the fly to ensure the playheads line up so that playback is seamless and smooth. The same thing happens when you reverse() or alter the timeScale, etc. But sometimes you might not want that behavior - you prefer to have tight control over exactly where your tweens line up in the timeline - that's when smoothChildTiming:false is handy.

One more example: let's say you've got a 10-second tween that's just sitting on the root timeline and you're 2-seconds into the tween. Let's assume it started at exactly 0 on the root to make this easy, and then when it's at 2-seconds, you do tween.seek(5). The playhead of the root isn't affected - it keeps going exactly as it always did, but in order to make that tween jump to 5 seconds and play appropriately, the tween's startTime gets changed to -3. That way, the tween's playhead and the root playhead are perfectly aligned.

Copyright 2008-2013, 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.