Copyright 2008-2014, 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.
* * @author Jack Doyle, jack@greensock.com */ public class SimpleTimeline extends Animation { /** Iftrue, child tweens/timelines will be removed as soon as they complete. (false by default except on the root timeline(s)) **/
public var autoRemoveChildren: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.
startTime when inserted (improves rendering accuracy in certain situations) **/
public var _sortChildren:Boolean;
/** @private first child in the linked list **/
public var _first:Animation;
/** @private last child in the linked list **/
public var _last:Animation;
/**
* Constructor
*
* @param vars Object containing configuration variables like onComplete, onUpdate, onStart, data, etc.
*/
public function SimpleTimeline(vars:Object=null) {
super(0, vars);
this.autoRemoveChildren = this.smoothChildTiming = true;
}
/**
* @private
* [Deprecated in favor of add()]
* Inserts a TweenLite, TweenMax, TimelineLite, or TimelineMax instance into the timeline at a specific time.
* In classes like TimelineLite and TimelineMax that override this method, it allows things like callbacks,
* labels, and arrays of tweens/timelines/callbacks/labels to be inserted too. They also allow the time to
* be defined in terms of either a numeric time or a label (String).
*
* @param child TweenLite, TweenMax, TimelineLite, or TimelineMax instance to insert
* @param position The time in seconds (or frames for frames-based timelines) at which the tween/timeline should be inserted. For example, myTimeline.insert(myTween, 3) would insert myTween 3 seconds into the timeline.
* @return this timeline instance (useful for chaining like myTimeline.insert(...).insert(...))
*/
public function insert(child:*, position:*=0):* {
return add(child, position || 0);
}
/**
* Adds a TweenLite, TweenMax, TimelineLite, or TimelineMax instance to the timeline at a specific time.
* In classes like TimelineLite and TimelineMax that override this method, it allows things like callbacks,
* labels, and arrays of tweens/timelines/callbacks/labels to be inserted too. They also allow the position to
* be defined in terms of either a numeric time or a label (String).
*
* @param child TweenLite, TweenMax, TimelineLite, or TimelineMax instance to insert
* @param position The position at which the tween/timeline should be inserted which can be expressed as a number (for an absolute time as seconds or frames for frames-based timelines) or a string, using "+=" or "-=" prefix to indicate a relative value (relative to the END of the timeline). For example, myTimeline.insert(myTween, 3) would insert myTween 3 seconds into the timeline.
* @param align Determines how the tweens/timelines/callbacks/labels will be aligned in relation to each other before getting inserted. Options are: "sequence" (aligns them one-after-the-other in a sequence), "start" (aligns the start times of all of the objects (ignoring delays)), and "normal" (aligns the start times of all the tweens (honoring delays)). The default is "normal".
* @param stagger Staggers the inserted objects by a set amount of time (in seconds) (or in frames for frames-based timelines). For example, if the stagger value is 0.5 and the "align" parameter is set to "start", the second one 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. Default is 0.
* @return this timeline instance (useful for chaining like myTimeline.add(...).add(...))
*/
public function add(child:*, position:*="+=0", align:String="normal", stagger:Number=0):* {
child._startTime = Number(position || 0) + child._delay;
if (child._paused) if (this != child._timeline) { //we only adjust the _pauseTime if it wasn't in this timeline already. Remember, sometimes a tween will be inserted again into the same timeline when its startTime is changed so that the tweens in the TimelineLite/Max are re-ordered properly in the linked list (so everything renders in the proper order).
child._pauseTime = child._startTime + ((rawTime() - child._startTime) / child._timeScale);
}
if (child.timeline) {
child.timeline._remove(child, true); //removes from existing timeline so that it can be properly added to this one.
}
child.timeline = child._timeline = this;
if (child._gc) {
child._enabled(true, true);
}
var prevTween:Animation = _last;
if (_sortChildren) {
var st:Number = child._startTime;
while (prevTween && prevTween._startTime > st) {
prevTween = prevTween._prev;
}
}
if (prevTween) {
child._next = prevTween._next;
prevTween._next = Animation(child);
} else {
child._next = _first;
_first = Animation(child);
}
if (child._next) {
child._next._prev = child;
} else {
_last = Animation(child);
}
child._prev = prevTween;
if (_timeline) {
_uncache(true);
}
return this;
}
/** @private **/
public function _remove(tween:Animation, skipDisable:Boolean=false):* {
if (tween.timeline == this) {
if (!skipDisable) {
tween._enabled(false, true);
}
if (tween._prev) {
tween._prev._next = tween._next;
} else if (_first === tween) {
_first = tween._next;
}
if (tween._next) {
tween._next._prev = tween._prev;
} else if (_last === tween) {
_last = tween._prev;
}
tween._next = tween._prev = tween.timeline = null;
if (_timeline) {
_uncache(true);
}
}
return this;
}
/** @inheretDoc **/
override public function render(time:Number, suppressEvents:Boolean=false, force:Boolean=false):void {
var tween:Animation = _first, next:Animation;
_totalTime = _time = _rawPrevTime = time;
while (tween) {
next = tween._next; //record it here because the value could change after rendering...
if (tween._active || (time >= tween._startTime && !tween._paused)) {
if (!tween._reversed) {
tween.render((time - tween._startTime) * tween._timeScale, suppressEvents, force);
} else {
tween.render(((!tween._dirty) ? tween._totalDuration : tween.totalDuration()) - ((time - tween._startTime) * tween._timeScale), suppressEvents, force);
}
}
tween = next;
}
}
//---- GETTERS / SETTERS ------------------------------------------------------------------------------
/**
* @private
* Reports the totalTime of the timeline without capping the number at the totalDuration (max) and zero (minimum)
* which can be useful when unpausing tweens/timelines. Imagine a case where a paused tween is in a timeline that has already
* reached the end, but then the tween gets unpaused - it needs a way to place itself accurately in time AFTER what was
* previously the timeline's end time. In a SimpleTimeline, rawTime is always the same as _totalTime,
* but in TimelineLite and TimelineMax, it can be different.
*
* @return The totalTime of the timeline without capping the number at the totalDuration (max) and zero (minimum)
*/
public function rawTime():Number {
return _totalTime;
}
}
}