TimelineMax – Sequence/Group Multiple Tweens, Control Them as a Whole
- Version: 1.381, Updated 2010-05-25
- File size added to compressed SWF: about 4.9k (base), 10.4k with OverwriteManager and TweenLite
Watch a video that explains the basics of working with TimelineLite and TimelineMax.
Description
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 position tweens (or other timelines) over the course of time. You can:
- build sequences easily by adding tweens with the append(), prepend(), insert(), appendMultiple(), prependMultiple(), and insertMultiple() methods. Tweens can overlap as much as you want and you have complete control over where they get placed on the timeline.
- add labels, play(), stop(), gotoAndPlay(), gotoAndStop(), restart(), tweenTo() and even reverse()!
- nest timelines within timelines as deeply as you want.
- set the progress of the timeline using its currentProgress property. For example, to skip to the halfway point, set myTimeline.currentProgress = 0.5;
- tween the currentTime, totalTime, currentProgress, or totalProgress property to fastforward/rewind the timeline. You could even attach a slider to one of these properties to give the user the ability to drag forwards/backwards through the whole timeline.
- add onStart, onUpdate, onComplete, onReverseComplete, and/or onRepeat callbacks using the constructor's vars object.
- speed up or slow down the entire timeline with its timeScale property. You can even tween this property to gradually speed up or slow down the timeline.
- use the insertMultiple(), appendMultiple(), or prependMultiple() methods to create complex sequences including various alignment modes and staggering capabilities. Works great in conjunction with TweenMax.allTo() too.
- base the timing on frames instead of seconds if you prefer. Please note, however, that the timeline's timing mode dictates its childrens' timing mode as well.
- kill the tweens of a particular object inside the timeline with killTweensOf() or get the tweens of an object with getTweensOf() or get all the tweens/timelines in the timeline with getChildren()
- set the timeline to repeat any number of times or indefinitely. You can even set a delay between each repeat cycle and/or cause the repeat cycles to yoyo, appearing to reverse every other cycle.
- listen for START, UPDATE, REPEAT, REVERSE_COMPLETE, and COMPLETE events.
- get the active tweens in the timeline with getActive().
- add callbacks (function calls) anywhere in the timeline that call a function of your choosing when the "virtual playhead" passes a particular spot.
- Get the currentLabel or find labels at various positions in the timeline using getLabelAfter() and getLabelBefore()
Interactive example
Sample AS3 code
-
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 myCallback when 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 capabilities, allowing you to add an Array of tweens (using TweenLite/Max instances or the new shorthand syntax, like [mc, 1, {x:100}]) 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 virtually all the setup too, like this sequence:
-
var myTimeline:TimelineMax = new TimelineMax({tweens:[new TweenLite(mc1, 1, {y:"100"}), TweenMax.to(mc2, 1, {tint:0xFF0000})], align:TweenAlign.SEQUENCE, onComplete:myFunction});
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.
Watch a video that explains the basics of working with TimelineLite and TimelineMax.
Documentation
Please view full ASDoc documentation here.
FAQ
- Does TimelineMax only work with TweenMax instances? Can I use TweenLite too?
You can put ANY (or all) of the following into a TimelineMax: TweenLite tweens, TweenMax tweens, TimelineLite timelines or other TimelineMax timelines. It's an integrated suite. Go crazy mixing and matching. The only part of the platform that doesn't work with TimelineLite/Max is the freakishly tiny TweenNano class. - Do the AS2 and AS3 versions work exactly the same?
Yes. To accommodate scope issues that are inherent in AS2, however, the AS2 version of TimelineMax also recognizes the following special properties to define the scope of callbacks: onStartScope, onUpdateScope, onRepeatScope, onCompleteScope, and onReverseCompleteScope. These are not necessary in AS3. Obviously the AS2 version doesn't offer AS3 event dispatching either. - How can I make a TimelineMax repeat infinitely?
Just set its "repeat" property to -1. - If I reverse() a TimelineMax right after I create it, nothing happens. Why?
reverse() simply causes the timeline to change direction and go back towards its starting point, but if it is already there (if it never got past its starting point), there's nowhere for it to go. There's nothing wrong with reversing a timeline when it's at its starting point, but keep in mind that doing so doesn't force it to jump all the way to the end. You can easily do that with myTimeline.progress = 1 though. - How do I install the class? Do I have to import it on every frame?
Just make sure the "com" folder from the download is in the same folder as your FLA file. Keep the directory structure in the "com" folder, though (the class files are inside a "greensock" folder that belongs inside the "com" folder). That's it. And, yes, just like any class, you need to import TimelineMax at the top of any frame that contains code referencing it. This does NOT add extra kb to your file size every time you import it. Flash is smart enough to embed it once and all the other import statements just act as a "pointer" to the embedded class. - Can I put the same tween in multiple timelines?
No. Every tween and timeline has one (and only one) parent timeline. Think of them like DisplayObjects/MovieClips - they cannot exist in two places at once. They can only have one parent. - What's the difference between TimelineLite and TimelineMax? Don't they do pretty much the same thing?
TimelineLite contains all the essentials, but TimelineMax extends it and adds more features (just like TweenLite and TweenMax). So TimelineMax can do EVERYTHING TimelineLite does plus more, like AS3 event dispatching, repeat, repeatDelay, yoyo, addCallback(), getActive(), tweenTo(), tweenFromTo(), getLabelBefore(), getLabelAfter(), currentLabel, etc. If you don't need any of those features, stick with TimelineLite. - Do I have to purchase a license to use this code? Can I use it for commercial purposes?
You may use the code at no charge in commercial or non-commercial web sites, games, components, applications, and other software as long as end users are not charged a fee of any kind to use your product or gain access to it. If your client pays you a one-time fee to create the site/product, that's perfectly fine and qualifies under the "no charge" license. If multiple end users are charged a usage/access/license fee of any kind, please simply sign up for a corporate Club GreenSock membership which comes with a special commercial license granting you permission to do so. See http://www.greensock.com/club/ for details. Club GreenSock members get several nifty bonus plugins, classes, update notifications, SVN access, and more. Your donations keep this project going. Please see the licensing page for details on licensing.
Need help?
Feel free to post your question on the forums. You'll increase your chances of getting a prompt answer if you provide a brief explanation and include a simplified FLA file (and any class files) that clearly demonstrates the problem.
Comments (12)
is it possible to use this Sample AS3 code in AS2 ? thanks
Sure, Vasya, you can use the same code for the AS2 version – the only exception is that some of the tween properties would be slightly different (like “x” in AS3 is “_x” in AS2, and same for “y”/”_y”, “alpha”/”_alpha”, etc.). The TimelineMax code itself uses exactly the same syntax in AS2 and AS3.
Is it possible to tween the timeScale of a single timeline within a master timeline?
Sure, Tony, you can tween the timeScale of a nested TimelineLite/Max.
Just wanted to thank you guys for a great package. Transitioning between scenes in my away3d project just became a lot easier and logical thanks to the addCallback() and reverse() functions.
Got my site up and running: http://www.savagelook.com
Thanks again for TweenMax/TimelineMax, they helped a ton!
Hi, great work, very helpful thanks a lot !
Just one or two questions, does the reverse calculate again the position at each frame, or does it use a cached array of positions of the ‘normal’ tween and read it from the end to the beginning?
And is it possible to get this array (if it exists) and reuse it somewhere else without recalculate all the positions, scales, rotations etc ? Or do I need to create it by myself with the “onUpdate” parameter or something like this?
I hope my question is clear. Thanks
Karim, the great thing about ActionScript-driven animation (at least the way the GreenSock system works) is that it is very dynamic and has no fixed “resolution” meaning that there isn’t a precalculated set of frames/values. The resolution is unlimited. You can render a tween or timeline at ANY time value (1 second in, 1.1, 1.00005, etc.) and it will figure out the precise values. That makes it silky smooth if, for example, you play the tween in slow motion (lower its timeScale). Traditional MovieClip timeline tweens that are built in the Flash IDE, however, have a fixed resolution which can start to look very choppy if you slow them down. Their duration will completely change if you alter the frame rate of your swf too. The GreenSock system, however, will adjust on the fly (although you can set useFrames:true and it will ensure that animations base their timing on frames instead of seconds if you prefer).
So to answer your question, no, there is not an array tucked away inside each tween with precalculated values. That’s a good thing 
Fantastic,a great product for AS 3.0 so, many things can be
developed out of this
Hi! I just found this library which seems very cool but quickly a question haunted me : how to say I want a pause between each TweenMax’s step of the TimeLineMax:
timeline.append(step1); timeline.append(step2); etc… ?
By the way, great job !
Anto, it depends on what kind of “pause” you want. If you just mean that you want there to be a gap in time between your tweens (like tween1 runs…then waits 5 seconds…then tween2 runs), then it’s as simple as using the “offset” parameter of the append() method (or use a “delay” in your tween2 – either way works). Like myTimeline.append(tween2, 5);
If, however, you truly want to pause() the timeline after a certain tween, you can use an onComplete in that tween to call a function that calls the timeline’s pause() method. Should be pretty straightforward. Or you could addCallback() on the timeline itself to do the same sort of thing.
myTimeline.addCallback(myFunction, 5);
function myFunction():void {
myTimeline.pause();
//do other stuff…
}
As usual, there are lots of options
So many possibilities ! It’s super, you’re genius ! Thanks