Dojo provides a powerful, event-based animation library for developers. I'll try and cover the basics here for anyone that wants to get started with making animations.

• !!What's an animation?
• Before getting too far, we need to define what an animation is in the context of Dojo. An animation is defined as: good definition here.
• !!Creating an animation

To create an animation object, you make the following call:

var anim = new dojo.animation.Animation(curve, duration, accel, repeatCount);

• curve - a special object detailed below used to give the animation points
• duration - the length of the animation in milliseconds?.
• accel - defines whether or not an animation accelerates (1 = max accel), decelerates (-1 = max decel), or moves at a constant speed (0 = no accel).
• repeatCount - if set to a number greater than 0, the animation will repeat that many times. If it is set to -1, the animation will repeat forever (or until paused/stopped).

Note: All these map directly to properties of the animation object. So, for the example above, you can change the duration by doing the following:

anim.duration = 1000; // change duration to be 1 second

It isn't advised to change these values during an animation as the behavior for such an action isn't defined.

Time-driven

All animations are time-driven. What that means is that you specify the duration of an animation and it runs in that time frame . The benefit of this system is that animations will look the same regardless of CPU speed.

Curve-based

All animations run off of curves. A curve is a special object whose only requirement is that is has a getValue(n) method, where n is a number between 0 and 1, that returns an array of numbers. Dojo has some pre-built curves available in dojo.math.curves. See Curves for details. As an example, the code for a Line curve is as follows:

function Line(start, end) {

    this.start = start;

    this.end = end;

    this.dimensions = start.length;

    //simple function to find point on an n-dimensional, straight line

    this.getValue = function(n) {

        var retVal = new Array(this.dimensions);

        for(var i=0;i<this.dimensions;i++)

            retVal[i] = ((this.end[i] - this.start[i]) * n) + this.start[i];

        return retVal;

    }

    return this;

}

Note, however, that by "line" we do not mean a physical line that you'd draw on a screen, but simply that we are moving from a starting point to an ending point linearly. Lines can be n-dimensional and are not limited to moving a node on the screen (as you'll see in the examples below).

Event-based

The Dojo animation library allows developers to hook into all parts of an animation which enables them to be able to make advanced animations in a simple and intuitive manner.

Event handlers

The following events are provided:

• onBegin - fired when animation is played (from the beginning)
• onAnimate - fired every iteration of the animation
• onEnd - fired when the animation has completed
• onPlay - fired when the animation is played (from any point, including beginning)
• onPause - fired whenever the animation is paused
• onStop - fired whenever the animation is stopped (by calling stop(), not be finishing)
• handler - catch-all for events. You could potentially just define one handler to handle all types of events. You'll have to look at the type property of the event object to see what kind of event has been fired.

AnimationEvent object

Whenever an event handler is called, it is passed a single event argument. The argument has the following properties:

Methods

• coordsAsInts() - return a copy of the coordinate array with values as integers.

Properties

• type - determines the type of event that has been fired. This is especially useful if you are using a single handler method to catch all events.
  • Possible values: animate, begin, end, play, pause, stop.
• coords - coordinate values for the animation. N-dimensional dependant on the curve used for the animation.
• x, y, z - quick access to coords[0], coords[1], and coords[2], respectively, for convenience.
• startTime - the time (as valueOf) the animation started.
• currentTime - now (as valueOf).
• endTime - the time the animation will end (as valueOf).
• duration - the running time of the entire animation, in milliseconds.
• percent - what percent of the animation has been completed. Value between 0 - 100.
• fps - frames per second of animation.

Methods

The following methods are available for animations:

• play(gotoStart) - plays an animation that is either stopped or paused. If gotoStart is true the animation will begin from the start of the animation.
• pause() - pause an animation. If the animation isn't playing, nothing happens (events aren't fired either).
• playPause() - used to toggle an animation from playing and paused states.
• gotoPercent(pct, andPlay) - jump to a certain percent of the animation. For example, to jump to the middle of the animation, you would call gotoPercent(50). If andPlay is set to true, the animation begins playing at the given percent.
• stop(gotoEnd) - stop an animation. If the animation isn't playing, nothing happens (events aren't fired either).
• status() - return the status of an animation.
  • Possible values: paused, playing, stopped.

Examples

API references are fine n' dandy, but everyone loves sample code. Here's some sample animations, most taken from dojo.graphics.htmlEffects...

Slide a node across the screen

Available as the pre-built animation, dojo.graphics.htmlEffects.slide with slideTo and slideBy variants.

var node = document.getElementById('animNode'); // with a suitable 'position'

var anim = new dojo.animation.Animation(

	new dojo.math.curves.Line([0,0], [400,200]), // linear points from (0,0) to (400,200)

 , // do it over a 3 second duration
 // with no acceleration

);

dojo.event.connect(anim, "onAnimate", function(e) {

	node.style.left = e.x + "px";

	node.style.top = e.y + "px";

});

dojo.event.connect(anim, "onBegin", function(e) {

	var div = document.createElement("div");

	div.appendChild(document.createTextNode("Animation started!"));

	document.body.appendChild(div);

});

dojo.event.connect(anim, "onEnd", function(e) {

	var div = document.createElement("div");

	div.appendChild(document.createTextNode("Animation done!"));

	document.body.appendChild(div);

});

anim.play();

Highlight a node

The ever-popular yellow fade animation. Simplified version of the pre-built animation, dojo.graphics.htmlEffects.highlight, colorFadeIn, and colorFadeFrom (not sure what the best name is). The pre-built version will get the background color of a node before hand and fade from your specified color to the background color. It is probably more ideal than the example below.

var anim = new dojo.animation.Animation(

	// linear points from (255, 255, 156) to (255, 255, 255)

	new dojo.math.curves.Line([255, 255, 156], [255, 255, 255]),

 , // do it over a 1 second duration
 // with no acceleration

);

dojo.event.connect(anim, "onAnimate", function(e) {

	// use the "coordinates" as RGB values. Since it is an array,

	// we can just join it with commas to get a nice rgb(r,g,b) CSS bg color

	document.getElementById("elmToHighlight").style.backgroundColor =

		"rgb(" + e.coordsAsInts().join(",") + ")";

});

dojo.event.connect(anim, "onEnd", function(e) {

	// "Kill" the background color instead of leaving it white

	// "transparent" would probably work, too.

	document.getElementById("elmToHighlight").style.backgroundColor = "inherit";

});

anim.play();

For more examples, see htmlEffects.js.

See Also: AnimationSequence?, Curves, HTMLEffects