Timeline Documentation
Author: Ralf Bokelberg, Alex Uhlmann
Last Modified: 10/05/05 14:21:27
Summary
Timeline class:
Timeline Properties:
Timeline Methods:
version: Documentation not provided.
description:
There are two different ways to use Timeline for. One way is to animate existing movieclip timeline(s) with AnimationPackage's tween engine. This way you can apply easing equations to a movieclip timeline. If choosing the default time-based tweening, the animation is independend from the current frame rate of your movieclip timeline(s). See example number 1 and 2 for more information.
The other way is to control existing movieclip timelines with the API of AnimationPackage. See example number 3 for more information about this opportunity.
Example 1: (Example .swf) (Example .fla) Animate a single movieclip timeline via AnimationPackage's tween engine. Animation of a movieclip that contains 50 frames of a shape tween. It starts with a rectangle and ends with a polygon drawn with the Flash MX 2004 IDE. It is a usual linear tween with a stop() action in the first frame. With Timeline we apply a Bounce easing equation to the linear shape tween animation inside movieclip mc.
You could have usedvar myTimeline:Timeline = new Timeline(mc,0,50); myTimeline.animationStyle(2000,Bounce.easeOut); myTimeline.animate(0,100);
AnimationCore.setTweenModes(AnimationCore.FRAMES); and
a duration property of 50 to emulate a movieclip timeline animation with the same speed.
Example 2: (Example .swf) (Example .fla) Animate multiple movieclip timelines via AnimationPackage's tween engine. All Movieclips have the same structure than in the example above with 50 frames and a stop() action in the first frame. Just the shape tween animation itself is different in some movieclips.
var mcs:Array = new Array(top1_mc,top2_mc,top3_mc,bottom1_mc,bottom2_mc,bottom3_mc);
//Two movieclips start at frame 30. This shall demonstrate
//Timeline's consideration of different start values
top1_mc.gotoAndStop(30);
bottom1_mc.gotoAndStop(30);
var myTimeline:Timeline = new Timeline(mcs,50);
myTimeline.animationStyle(2500,Bounce.easeOut);
myTimeline.addEventListener("onEnd",this);
myTimeline.animate(0,100);
function onEnd(e:Object) {
trace("source: "+e.target+" event: "+e.type+" frame: "+e.value);
new Text().setText("source: "+e.target+" event: "+e.type+" frame: "+e.value);
}
//pause and resume the animation in turns with each mouse click.
function onMouseDown() {
if(myTimeline.isTweening()){
myTimeline.pause();
} else {
myTimeline.resume();
}
}
Example 3: (Example .swf) (Example .fla) Another use of Timeline is to control movieclip timelines. Same movieclips like in example 2. Notice that we don't use the animationStyle method here, because we don't want to apply an easing equation to the movieclip timelines specified in the Array mcs. We play every movieclip timeline by its own and get all informations, including events, about them via the known API of AnimationPackage. The .swf plays at 31 fps.
//some textfields for logging event informations.
var myStartText:Text = new Text();
myStartText.setText("",0,0);
var myUpdateText:Text = new Text();
myUpdateText.setText("",0,15);
var myEndText:Text = new Text();
myEndText.setText("",0,30);
var mcs:Array = new Array(top1_mc,top2_mc,top3_mc,bottom1_mc,bottom2_mc,bottom3_mc);
var myTimeline:Timeline = new Timeline(mcs);
myTimeline.addEventListener("onStart",this);
myTimeline.addEventListener("onUpdate",this);
myTimeline.addEventListener("onEnd",this);
//internally, this method invokes the play() method on each movieclip instance.
//you could i.e. also use stop(), gotoAndStop(), gotoAndPlay(), nextFrame(),
//and prevFrame() via Timeline.
myTimeline.play();
function onStart(e:Object) {
myStartText.updateText("source: "+e.target+" event: "+e.type+" frame: "+e.value+"\n");
}
function onUpdate(e:Object) {
myUpdateText.updateText("source: "+e.target+" event: "+e.type+" frame: "+e.value+"\n");
}
function onEnd(e:Object) {
myEndText.updateText("source: "+e.target+" event: "+e.type+" frame: "+e.value+"\n");
myTimeline.stop();
}
//even if not animated via AnimationPackage's own tween engine, you're still able to stop and pause
//the movieclip timeline(s) as you would expect with every IAnimatable instance.
function onMouseDown() {
if(myTimeline.isTweening()){
myTimeline.pause();
} else {
myTimeline.resume();
}
}
There are many ways to use this class. One way is to specify the duration, easing equation and callback properties outside the current method, either with setting the properies directly or with the animationStyle() method like it is used in de.alex_uhlmann.animationpackage.drawing.
Example 4:
Example 5: The alternative way is shorter. The same like above in one line.var myTimeline:Timeline = new Timeline(mc); myTimeline.animationStyle(2000,Circ.easeIn,"onCallback"); myTimeline.run(50);
Example 6: You can also specify the properties via the constructor. This might come in handy if you're using the Sequence or Parallel class. Take a look at their class documentations for more information. The animate() method and its start and end percentage parameters might also be useful.new Timeline(mc).run(50,2000,Circ.easeInOut,"onCallback");
Example 7: By default, the start value of your animation is the current value of your sound instance retrieved from getTimeline(). You can explicitly define the start values either via the setStartValue or run method or via the constructor. Here is one example for the constructor solution. This also might come in handy using composite classes, like Sequence.var myTimeline:Timeline = new Timeline(mc,0,2000,Circ.easeInOut); myTimeline.animate(50,100);
var myTimeline:Timeline = new Timeline(mc,[50,0],2000,Circ.easeIn); myTimeline.run();
usage:
var myTimeline:Timeline = new Timeline(mcs);
var myTimeline:Timeline = new Timeline(mcs, amount, duration, callback);
var myTimeline:Timeline = new Timeline(mcs, amount, duration, easing, callback);
var myTimeline:Timeline = new Timeline(mcs, values);
var myTimeline:Timeline = new Timeline(mcs, values, duration, callback);
var myTimeline:Timeline = new Timeline(mcs, values, duration, easing, callback);
var myTimeline:Timeline = new Timeline(mc);
var myTimeline:Timeline = new Timeline(mc, amount, duration, callback);
var myTimeline:Timeline = new Timeline(mc, amount, duration, easing, callback);
var myTimeline:Timeline = new Timeline(mc, values);
var myTimeline:Timeline = new Timeline(mc, values, duration, callback);
var myTimeline:Timeline = new Timeline(mc, values, duration, easing, callback);
parameters:
(MovieClip) Movieclip to animate.
(Array) Array of Movieclips to animate.
(Number) Duration of animation in milliseconds or frames. Default is milliseconds.
(Object) Easing equation in Robert Penner style. Default equation is Linear.easeNone. www.robertpenner.com/easing/
(String) Function to invoke after animation. See AnimationCore class.
description: Notice that this method only makes sense if Timeline is used for animating and not only for controling movieclip timelines. See class documentation.
usage:
myInstance.run();
myInstance.run(amount);
myInstance.run(amount, duration);
myInstance.run(amount, duration, callback);
myInstance.run(amount, duration, easing, callback);
myInstance.run(values, duration);
myInstance.run(values, duration, callback);
myInstance.run(values, duration, easing, callback);
parameters:
returns: void
description: similar to the run() method. Offers start and end parameters. Notice that this method only makes sense if Timeline is used for animating and not only for controling movieclip timelines. See class documentation.
usage:
myInstance.animate(start, end);
parameters:
returns: void
description: jumps to a specific step of the animation and stays there. Notice that this method only makes sense if Timeline is used for animating and not only for controling movieclip timelines. See class documentation.
usage:
instance.goto(percentage);
parameters:
returns: void
description: set the animation style properties for your animation. Notice that if your easing equation supports additional parameters you can send those parameters with the easing parameter in animationStyle. You have to send an Array as easing parameter. The first element has to be the easing equation in Robert Penner style. The following parameters can be your additional parameters. i.e.:
See also "Customizable easing equations" in readme for more information. Notice that this method only makes sense if Timeline is used for animating and not only for controling movieclip timelines. See class documentation.var myRotation:Rotation = new Rotation(mc); myRotation.animationStyle(2000,[Back.easeOut,4]); myRotation.run(360);
usage:
myInstance.animationStyle(duration);
myInstance.animationStyle(duration, callback);
myInstance.animationStyle(duration, easing, callback);
parameters:
returns: Void.
description: invokes gotoAndPlay on movieclip timeline(s).
usage:
myInstance.gotoAndPlay(frame);
parameters:
returns: void
description: invokes gotoAndStop on movieclip timeline(s).
usage:
myInstance.gotoAndStop(frame);
parameters:
returns: void
description: invokes play on movieclip timeline(s).
usage:
myInstance.play();
returns: void
description: invokes nextFrame on movieclip timeline(s).
usage:
myInstance.nextFrame();
returns: void
description: invokes prevFrame on movieclip timeline(s).
usage:
myInstance.prevFrame();
returns: void
description: asked the timeline movieclip mc for its _currentframe property. In case an Array of movieclips was specified, only the first element will be asked.
usage:
myInstance.getCurrentFrame();
returns: Number, number of frames that mc contains.
description: asked the timeline movieclip mc for its _totalframes property. In case an Array of movieclips was specified, only the first element will be asked.
usage:
myInstance.getTotalFrames();
returns: Number, number of frames that mc contains.
description: Flash does not guaranteed that time-based tweening will reach the end value(s) of your animation. By default AnimationPackage guarantees that the end value(s) will be reached. The forceEnd method allows you to disable this guarantee and only accept the values from your easing equation. In certain situations this can lead to a smoother ending of the animation. Notice that in frame-based tweening the end value(s) will always be reached.
usage:
myInstance.forceEnd(forceEndVal);
parameters:
true or false.returns: Void.
description: returns the optimization mode. See setOptimizationMode for more information.
usage: getOptimizationMode();
returns: Boolean
description:
Allows to explicitly remove parts of the animation that don't change during
the animation.
This can add additional performance to your animation. Note that
setting this method to true has side effects. If all start and end values match,
the animation won't start and will immediatly invoke an onEnd event.
The order of values returned by getStartValue(s), getCurrentValue(s),
getEndValue(s) and the value property of the eventObject returned
by EventDispatcher might change if you set this method to true. You can
still retrieve the parts of the animation that are actually animated
if you access the Animator instance of your animation class via
myAnimator. Ask myInstance.myAnimator.setter to retrieve
all currently animated parts of the animation. See Animator
documentation. Of cource, if you know your input values you would
probably look at them.
Note that the AnimationCore class offers a static setOptimizationModes method (note the last "s" at the end) that allows you to remove parts of 'all' your animations that don't change during the animation.
usage:
myInstance.setOptimizationMode(optimize);
parameters:
returns: Void.
description: returns the current tween mode used by the instance. Please check with AnimationCore.setTweenModes for more information.
usage: getTweenMode();
returns: String that specifies the tween mode. Either AnimationCore.INTERVAL or AnimationCore.FRAMES.
description: sets the current tween mode used by the instance. Please check with AnimationCore.setTweenModes for more information.
usage: setTweenMode();
parameters:
returns: true if setting tween mode was successful,
false if not successful.
description: returns the current duration mode used by the instance. Please check with AnimationCore.setTweenModes for more information.
usage: getDurationMode();
returns: String that specifies the duration mode. Either AnimationCore.MS or AnimationCore.FRAMES.
description: sets the current duration mode used by the instance. Please check with AnimationCore.setTweenModes for more information.
usage: setDurationMode();
parameters:
returns: true if setting duration mode was successful,
false if not successful.
description: stops the animation if not locked.
usage: myInstance.stop();
returns: true if instance was successfully stopped.
false if instance could not be stopped, because it was locked.
description: pauses the animation if not locked. Call resume() to continue animation.
usage: myInstance.pause();
parameters:
returns: true if instance was successfully paused.
false if instance could not be paused, because it was locked.
description: continues the animation if not locked.
usage: myInstance.resume();
returns: true if instance was successfully resumed.
false if instance could not be resumed, because it was locked.
description: locks the animation to prevent pausing, resuming and stopping. Default is unlocked.
usage: myInstance.lock();
returns: Void.
description: unlocks the animation to allow pausing, resuming and stopping. Default is unlocked.
usage: myInstance.unlock();
returns: Void.
description: checks if the instance is currently animated.
usage: myInstance.isTweening();
returns: true if instance is tweening,
false if instance is not tweening.
description: returns the original, starting value of the current tween.
usage: myInstance.getStartValue();
returns: Number
description: sets the original, starting value of the current tween.
usage: myInstance.setStartValue(startValue);
parameters:
returns: Boolean, indicates if the assignment was performed.
description: returns the targeted value of the current tween.
usage: myInstance.getEndValue();
returns: Number
description: sets the targeted value of the current tween.
usage: myInstance.setEndValue(endValue);
parameters:
returns: Boolean, indicates if the assignment was performed.
description: returns the current value of the current tween.
usage: myInstance.getCurrentValue();
returns: Number
description: returns the current state of the animation in percentage. Especially usefull in combination with goto().
usage: myInstance.getCurrentPercentage();
returns: Number
description: returns the elapsed time or frames since the current tween started tweening.
usage: myInstance.getDurationElapsed();
returns: Number
description: returns the remaining time or frames since the current tween started tweening.
usage: myInstance.getDurationRemaining();
returns: Number
description: Subscribe to a predefined event. The following standard EventDispatcher events are broadcasted
onStart, broadcasted when animation starts.
onUpdate, broadcasted when animation updates.
onEnd, broadcasted when animation ends.
The even object returned, contains the following properties:
type (String) event broadcasted.
target (Object) event source.
value (Number) value to animate.
usage:
myInstance.addEventListener(event, listener);
myInstance.addEventListener(event, listener, handler);
parameters:
returns: Void.
description: Removes a listener from a subscribed event.
usage:
myInstance.removeEventListener(event, listener);
myInstance.removeEventListener(event, listener, handler);
parameters:
returns: Void.
description: GDispatcher specific feature. Removes all listeners for a specific event, or for all events.
usage:
myInstance.removeAllEventListeners();
myInstance.removeAllEventListeners(event);
parameters:
returns: Void.
description: GDispatcher specific feature. Checks if a listener is already subscribed to a certain event.
usage:
myInstance.eventListenerExists(event, listener);
myInstance.eventListenerExists(event, listener, handler);
parameters:
returns: true if event exists on listener.
false if event doesn't exist on listener.
description: returns a unique ID of the instance. Usefull for associative arrays.
usage: myInstance.getID();
returns: Number
description: returns the name of the class.
usage: myInstance.toString();
returns: String