Introduction
AnimationPackage helps you to create powerful, maintainable animations in an efficient and easy way. At the same time it keeps your file size down because many parts of it are reused and only the classes you need are imported to your project. AnimationPackage is an ActionScript 2.0 library and it is compatible to Flash Player 6 and above.
Credits
First of all, I want to thank the following people, whose ideas and code greatly influenced AnimationPackage. Without their contributions to the Flash community, AnimationPackage would not have been possible.
| Robert Penner | AS2 Easing Equations Color Toolkit cubic bezier drawing |
| Ric Ewing Eric Mueller Michael Hurwicz James W. Bennett |
Drawing methods |
| André Michelle | ImpulsDispatcher FrameBasedInterval |
| Grant Skinner | GDispatcher |
| Ivan Dembicki | com.sharedfonts.Path skew (class) |
| Joey Lott | ASCBLibrary |
| e2e4 i++ |
SuperShape Flash implementation |
| Marcel Fahle | Color Dodge methods |
| Ralf Bokelberg | MovieClip.blur |
| Colin Moock | combineRGB() |
| Fernando Flórez | MovieClip.getNextDepth |
| Nacho Rapallo Andres Sebastian Yañez Duran |
[flashAPI] skew.as |
| crazyl0rd @ EFnet | MovieClip.shake |
| Tanja Pislar | AS2DocGenerator |
| Manfred Hiel | Logo Design |
| Karl Friedrich Gauß | mathematical foundations for Easing Equations |
and the people who gave valuable feedback during the BETA stage, later on, and who helped spreading the news: Colin Moock, Ralf Bokelberg, André Michelle, Ralf Siegel, Martin Heidegger (as2lib), Matthias Kannengiesser, Ivan Dembicki, Marcel Fahle, Thomas Pfeiffer, Matt Freer, Steve Schwarz, Mike Chambers, Christoph Atteneder, NEUE DIGITALE, Ben Jackson and the Powerflashers. Did I forgot anybody?
Requirements
You need to have either Macromedia Flash MX 2004 or Macromedia Flex 1.0 or higher installed and the Flash Player 6 to view the results. Nevertheless, you can compile AnimationPackage with Motion-Twin ActionScript 2 Compiler.
Overview
Before reading the usage paragraph, I recommend taking a look at the step by step tutorial that shows you how simple it is to create animations with AnimationPackage. After reading the usage paragraph, check out the documentation for the class you are interested in. Each class that is provided for you, has its own documentation HTML file. Also, I recommend to look into the APCore, AnimationCore, and Shape class documentations which are base classes for many classes you might use.
Usage
Structure
Most classes in AnimationPackage that can animate, implement the IAnimatable interface. The IAnimatable interface makes sure that certain functionality is shared across all classes that support IAnimatable. In particular, IAnimatable classes in AnimationPackage directly implement either ISingleAnimatable or IMultiAnimatable which extend IAnimatable. IAnimatable extends IAnimationPackage. Take look into the interfaces to get an understanding what functionality AnimationPackage offers and see the HTML class documentation for further information about implmentation. Also note that empty parameter lists indicate that this method is overloaded and explained in the HTML class documentaion. If a method doesn't accept parameters, the parameter list is Void. All interfaces start with an "I".
For example there is also IDrawable for all shapes or IOutline for Drawer, Line, DashLine, QuadCurve, CurbicCurve, Curve etc.
At the moment only the source code tells which interfaces a class implements. Therefore, here is a list of all IAnimatable classes because I sometimes refer to them when talking about types of classes:
Animation, Sequence, Parallel, Move, MoveOnCubicCurve, MoveOnCurve, MoveOnPath, MoveOnQuadCurve, Scale, Rotation, Alpha, ColorTransform, ColorBrightness, ColorNegative, ColorDodge, MaskMoveFX, MaskScaleFX, Skew, Timeline, Volume, Drawer, Line, DashLine, QuadCurve, CurbicCurve, Curve, Arc, Spiral, SuperShape, Animator, SingleAnimator, Pause.
Also, sometimes I refer to composite classes. Those are collection classes that implement the Composite design pattern and IComposite marker interface to treat their children or other collections. Those classes are:
Animation, Sequence, Parallel, Drawer, MoveOnPath, ShapeComposite.
The IDrawable interface describes most shape classes.
Arc, Burst, Ellipse, Gear, Poly, Rectangle, RoundRectangle, ShapeComposite, Spiral, Star, Line, DashLine, QuadCurve, CurbicCurve, Curve.
IOutline classes are outlines that can be combinded in the composite Drawer class to draw, animate and fill drawings of arbitrary shape.
Drawer, Line, DashLine, QuadCurve, CurbicCurve, Curve.
Tween-engine
There are two different ways in Flash to create animations (tweening) with ActionScript. Either based on frames (onEnterFrame) or based on time (setInterval). In general, frame-based tweening is more accurate and faster than time-based tweening but forces you to specify frames for duration instead of time (i.e. milliseconds). For the latter AnimationPackage offers a workaround, though.
AnimationPackage can use both approaches, time-based tweening or frame-based tweening. By default, it uses Macromedia's standard tween-engine from mx.effects.Tween, which is time-based tweening. For frame-based tweening a tween-engine based on André Michelle's ImpulsDispatcher can be used, instead.
You can change the tween-engines at runtime and control frame based animations with milliseconds. For more information about the tween-engines in AnimationPackage, please take a look at the AnimationCore class documentation.
Default properties
The AnimationCore, Shape and most drawing classes have default properties. This means if you don't specify a property to the instance, the default property is used. You can make use of this if you have i.e. different classes that might want to share some properties. Then, you can overwrite the default property and don't specify anything to the instance, so that the instance retrieves your default property. All default properties belong to a class (they are static) and have the same name like their instance properties, except for the suffix "_def" for default. See the AnimationCore, Shape and drawing class documentations for information on what default properties are available and examples.
APCore class
Most classes in AnimationPackage subclass APCore. It implements listener functionality (AsBroadcaster and EventDispatcher/GDispatcher) and common used methods and creates the animationClip (apContainer_mc), by default to the _root timeline, which is a movieclip that contains everything made by AnimationPackage unless you explicitly prevent this. For example if you use the classes of de.alex_uhlmann.animationpackage.drawing you are able to specify a movieclip of any timeline that will be used to draw the shape. If you don't specify anything, a new movieclip, by default created in _root.apContainer_mc will be used to draw the shape. Furthermore, for better performance any frame-based tweening will run on the same onEnterFrame handler in apContainer_mc. See AnimationCore class documentation for more information.
You don't have to use a callback structure to handle events like I did in the tutorial. AnimationPackage supports com.gskinner.events.GDispatcher, which is an extension to the W3C standard orientated mx.events.EventDispatcher from Macromedia. You can use GDispatcher exactly like EventDispatcher but you have additional features in GDispatcher. Take a look at Grant Skinner's documentation on GDispacher for more information. Nevertheless, if you want to work with EventDispatcher instead of GDispatcher, take a look at the APCore class implementation comment at line 2 for how to switch. It's just swopping two lines of code. In the following, I'll call this event mechanism EventDispatcher, even if AnimationPackage uses GDispatcher by default. If GDispatcher specific features will be used, I'll say so.
Most classes have an "onStart" and "onEnd" event, and many classes have an "onUpdate" event, in addition. Take a look at the specific class documentation for more information about specific events of one class. In the following, I'll demonstrate the distinction between using the callback structure and using some different implementations of EventDispatcher / GDispatcher. The examples will always do the same. I'll decrease a rectangle, drawn with AnimationPackage.
Example 1: draw and animate a rectangle using the callback structure:
APCore.initialize();
var myListener:Object = new Object();
APCore.addListener(myListener);
var myRectangle:Rectangle = new Rectangle(275,200);
myRectangle.draw();
var myScale:Scale = new Scale(myRectangle.movieclip,50,50);
myScale.animationStyle(2000,Sine.easeInOut,"onCallback");
myListener.onCallback = function(source, value) {
trace(source+" finished at "+value);
};
myScale.animate(0,100);
There's another example using the callback structure in the APCore class documenation.
Example 2: do the same but use EventDispatcher. Note that we don't need the first two lines and the callback property of animationStyle() from example 1. We create the listener object obj, and subscribe it to the onEnd event of the myScale instance.
var myRectangle:Rectangle = new Rectangle(275,200);
myRectangle.draw();
var myScale:Scale = new Scale(myRectangle.movieclip,50,50);
myScale.animationStyle(2000,Sine.easeOut);
var obj:Object = new Object();
obj.onEnd = function(eventObject:Object) {
trace(eventObject.target+" finished at "+eventObject.value);
};
myScale.addEventListener("onEnd",obj);
myScale.animate(0,100);
Example 3: do the same as in example 2 but use the current timeline (this) for the subscriber object.
var myRectangle:Rectangle = new Rectangle(275,200);
myRectangle.draw();
var myScale:Scale = new Scale(myRectangle.movieclip,50,50);
myScale.animationStyle(2000,Sine.easeOut);
function onEnd(eventObject:Object) {
trace(eventObject.target+" finished at "+eventObject.value);
}
myScale.addEventListener("onEnd",this);
myScale.animate(0,100);
Example 4: do the same as in example 3 but send a GDispacher specific third parameter with addEventListener(). This third parameter is a handler method, I've defined in "this" timline.
var myRectangle:Rectangle = new Rectangle(275,200);
myRectangle.draw();
var myScale:Scale = new Scale(myRectangle.movieclip,50,50);
myScale.animationStyle(2000,Sine.easeOut);
function onRectangleReduction(eventObject:Object) {
trace(eventObject.target+" finished at "+eventObject.value);
}
myScale.addEventListener("onEnd",this,"onRectangleReduction");
myScale.animate(0,100);
The EventDispatcher always sends an event object to the subscriber object. The event object has at least two properties: "type", which specifies the event subscribed to, and "target", which specifies the event source. The event object can contain more properties like the "value" property, used in the examples above. To see what properties are sent to the subscriber object you can use a for in loop:
for(var p:String in eventObject) {
trace(p+" : "+eventObject[p])
}
Or take a look into the class documentation.
Easing equations can be used to customize your animations. You can use the provided easing equations from Robert Penner. You can build your own easing equation with the help of easing generators from Ladislav Zigo or Timothee Groleau. Those generators also make sure that your customized easing equations are compatible to the tween engines used by AnimationPackage. Nevertheless, every easing equation can have additional parameters. At this time, Robert Penner's Elastic and Back easing equations support additional parameters to further customize the Elastic and Back tweening. Here is one example of a rotation using AnimationPackage's Rotation class and Robert Penner's Back easing equation. The first example uses the default Back easing. The second example uses a customized Back easing that specifies the amount of overshoot. Also see the animationStyle documentations for more information.
default Back easing:
var myRotation1:Rotation = new Rotation(mc1);
myRotation1.animationStyle(2000,Back.easeOut);
myRotation1.run(360);
customized Back easing:
var myRotation2:Rotation = new Rotation(mc2);
myRotation2.animationStyle(2000,[Back.easeOut,4]);
myRotation2.run(360);
See it in aciton: Example .swf.
You can use AnimationPackage in Macromedia Flex. Currently, it's indended to use AnimationPackage in ActionScript 2.0 classes or the MXML Script tag.
AnimationPackage offers full controll over any IAnimatable instance. You can animate, animate only certain areas, animate backwards, stop, pause, resume, goto specific points withough animating, step forward, step backward etc. The following example is build to showcase the control that AnimationPackage offers over animations. For further information about usage please check the class documentation of the class you're interested in.
Controlling animations showcase
Thanks for following me. Have a better example? Found bugs? Let me know.
mailX@XalexX-uhlmann.de . Remove the X's.