Jump to content
GreenSock

TimelineMax.exportRoot()

TimelineMax.exportRoot( vars:Object, omitDelayedCalls:Boolean ) : TimelineLite

[static] Seamlessly transfers all tweens, timelines, and [optionally] delayed calls from the root timeline into a new TimelineLite so that you can perform advanced tasks on a seemingly global basis without affecting tweens/timelines that you create after the export.

Parameters

vars: Object

(default = null) — The vars parameter that’s passed to the TimelineLite’s constructor which allows you to define things like onUpdate, onComplete, etc. TheuseFrames special property determines which root timeline gets exported. There are two distinct root timelines – one for frames-based animations (useFrames:true) and one for time-based ones. By default, the time-based timeline is exported.

omitDelayedCalls: Boolean

(default = true) — If true (the default), delayed calls will be left on the root rather than wrapped into the new TimelineLite. That way, if youpause() or alter the timeScale, or reverse(), they won’t be affected. However, in some situations it might be very useful to have them included.

Returns : TimelineLite

A new TimelineLite instance containing the root tweens/timelines

Details

Seamlessly transfers all tweens, timelines, and [optionally] delayed calls from the root timeline into a new TimelineLite so that you can perform advanced tasks on a seemingly global basis without affecting tweens/timelines that you create after the export. For example, imagine a game that uses the GSAP for all of its animations and at some point during the game, you want to slow everything down to a stop (tweening the timeScale) while at the same time animating a new popup window into place:

var tl = TimelineLite.exportRoot();
TweenLite.to(tl, 0.5, {timeScale:0});
 
//this tween isn't affected because it's created after the export.
TweenLite.fromTo(myWindow, 1, {scaleX:0, scaleY:0}, {scaleX:1, scaleY:1});

You could then re-animate things when you're ready by tweening the timeScale back to 1. Or you could use exportRoot() to collect all the animations and pause() them and then animate the popup screen (or whatever). Then resume() that instance or even reverse().

You can exportRoot() as many times as you want; all it does is wrap all the loose tweens/timelines/delayedCalls into a TimelineLite which itself gets placed onto the root, so if youexportRoot() again, that TimelineLite would get wrapped into another one, etc. Things can be nested as deeply as you want. However, if you plan to call exportRoot() a lot (hundreds or thousands of times), it'd be wise to de-nest things from the previous export first to avoid a situation where the browser thinks there's a recursion error (maximum callstack). You could do so like this (assumes we previously declared a variable named "allAnimations" to store the exported root): 

//De-nest things from the "allAnimations" exported root if one exists...
if (allAnimations) {
    var animations = allAnimations.getChildren(),
        startTime = allAnimations.startTime(),
        root = allAnimations.timeline,
        l = animations.length,
        i;
    for (i = 0; i < l; i++) {
        root.add(animations[i], animations[i].startTime() - animations[i].delay() + startTime);
    }
    allAnimations.kill();
}
//now do the export
allAnimations = TimelineLite.exportRoot();

Note: completed tweens/timelines are removed from the root (for automatic garbage collection), so if you exportRoot() after a particular tween completes, it won't be included in the export. The only way around that is to set autoRemoveChildren property of the Animation._rootTimeline and Animation._rootFramesTimeline to false, but that is NOT recommended because you'd need to manually kill() your tweens/timelines manually to make them eligible for garbage collection.


Copyright 2017, GreenSock. All rights reserved. This work is subject to theterms of useor for Club GreenSock members, the software agreement that was issued with the membership.
×