Jon's Ajax Animation Library

Settings (apply to 'Hello World' object only):

Source Code

GNU GPL Source Code is here.

Features

This animation library:

• Runs in FireFox and IE,

• Is lightweight and application neutral (very easy to interface with),

• Animates multiple properties/objects in parallel,

• Can animate multiple properties of a single object at different rates (some gotchas - see below),

• Behaves well if you specify a new animation on a property that is already being animated,

• Is "real time" - i.e. you specify animation length in milliseconds, not frames,

• Has an easy enable/disable switch to turn effects off (AnimationLibrary.enabled),

• Supports Perlin style "bias and gain" knobs for setting speed curves, including accelerate, slow-in-slow-out, etc.

• Behaves well if you specify a new animation on a property that is currently being animated,

• Has an onComplete callback for detecing when an animation is complete,

• Supports simple sequencing.

Interfacing with the library

This library was designed to be very easy to integrate into existing applications. It doesn't come with any dogma, and has hardly any expectations about the objects it animates.

AnimationLibrary places one demand on the objects you pass in to it - it expects them to follow the getValue/setValue pattern - i.e. they should have a method called setValue that take a property name and sets the value for the property, and another method called getValue that takes a property name and gets the current value.

i.e. to animate the property "foo" of an object obj, the library first calls:

    var value = obj.getValue("foo");

It expects the resulting value to be a number. The library calculates new values and then later calls:

    obj.setValue("foo", newValue);

to update the object.

For the demo on this page I wrote a simple wrapper on a a DOM Node that exposes "x", "y", "width" and "height" properties by digging into the DOM Node's stylesheet. Other applications probably have their own such wrappers, so I intentionally kept this code lightweight.

CSS Users: Note that if you try to animate properties of HTML elements, you should create a "style" tag on those elements which directly specifies the initial values for the properties. If you don't do this you may see unpleasant "pops" when the animation starts. The demo on this page shows this being done correctly.

Using the Library

To animate properties of an object, from their current values to the specified to-values, over a period of time (specified in milliseconds), the basic pattern is:

    AnimationLibrary.animate(<obj>, <timeMillis>, 
                 <pname1>, <val1>, 
                 <pname2>, <val2>, ...);

e.g.

   // First set object's x to 0. 
   // Then animate it to 100 over 1000 millis (1 second):
   //
   obj.setValue("x", 0);
   AnimationLibrary.animate(obj, 1000, "x", 100); 
       
   // Move to position 10, 10.
   // Then animate to 100, 200 over a second:
   //
   obj.setValue("x", 10);
   obj.setValue("y", 10);
   AnimationLibrary.animate(obj, 1000, "x", 100, "y", 200);

Bias and Gain

By default, animate uses a linear movement. You can create slow-in-slow out or fast-in-fast-out movements by specifying "bias" and "gain" properties for the animation. e.g.

     // Traditional Ease (slow-in-slow-out)
     AnimationLibrary.animate(obj, 1000, 
            "x", 100, 
            "gain", .9); 

     // Fast-in-fast-out (unusual):
     AnimationLibrary.animate(obj, 1000, 
            "x", 100, 
            "gain", .1); 
 
     // Whoosh (slow-in-fast-out)
     AnimationLibrary.animate(obj, 1000, 
            "x", 100, 
            "bias", .1); 
 
     // Pop (slows down at end):
     AnimationLibrary.animate(obj, 1000, 
            "x", 100, 
            "bias", .9); 
     

There is an onComplete attribute that, if provided, specifies a callback function which is called when the animation is completed:

   AnimationLibrary.animate(obj, 1000, 
        "x", 100, 
        "onComplete", function() { alert("DONE"); }); 

The onComplete function is not called if the animation is cancelled.

AnimationLibrary.animate returns an object that represents a handle to the animation. It can be used to clear the animation:

   var anim = AnimationLibrary.animate(obj, 1000, "x", 100);

   // Stop the animation   
   AnimationLibrary.stop(anim);

You can stop all animations running on an object by using:

    // Stop all animations registered against the object obj
    AnimationLibrary.stop(obj);

Simple Sequences

You can use the "then" method to create an animation sequence, i.e. to animate "x" to 100, and then animate "y" to 300 in sequence, use:

    // Sequence of animations
    AnimationLibrary.animate(obj, 
            1000, // millis
            "x", 100
       ).then(
            500, // millis
            "y", 300
       );

The "forever" function lets you create cycles:

    // Loop forever
    AnimationLibrary.animate(obj, 
            1000, // millis
            "x", 100
       ).then(
            500, // millis
            "x", 200
       ).forever();

Have fun!