Animation

Bonsai provides an Animation class, a KeyframeAnimation class and a convenience animate method on all DisplayObject instances.

Animating a red square to be blue, for example, is as simple as:

Try it out:

new Rect(0, 0, 100, 100)
  .addTo(stage)
  .attr('fillColor', 'red')
  .animate('1s', {
    fillColor: 'blue'
  });

The animate method

The animate method is available on all DisplayObjects and acts as a shortcut. An animation utilising all available options might look like this:

myDisplayObject.animate('650ms', {
  x: 100,
  y: 900
}, {
  easing: 'bounceIn',
  delay: '200ms'
})

This’ll apply easing to the animation and a delay of 200 milliseconds before the animation begins.

Animation options

Options are passed as the third argument to new Animation, new KeyframeAnimation or DisplayObject#animate:

Acceptable duration/delay

Animation class

For even more control you can create an Animation instance yourself.

A simple animation:

var myAnimation = new Animation('1s', {
  x: 190 // animate `x` attribute to 190
});

myDisplayObject.animate(myAnimation); // apply myAnimation to `myDisplayObject`

Passing an Animation instance to DisplayObject.prototype.animate will automatically initiate it with that DisplayObject as the subject of the animation. An animation can have multiple subjects, and you can set them manually. For example:

var myShapeA = new Rect(0, 0, 50, 50).addTo(stage).attr('fillColor', 'red');
var myShapeB = new Rect(0, 50, 50, 50).addTo(stage).attr('fillColor', 'blue');
var myAnimation = new Animation('1s', {
  x: 100,
  fillColor: 'green'
});
myAnimation.addSubjects([myShapeA, myShapeB]);
myAnimation.play();

For convenience you can pass all subjects directly to the play method too:

myAnimation.play([myShapeA, myShapeB]);

Non numeric animations

Most values you animate will inevitably be single numeric values, like x or scaleY. For when you want to animate more unique values, such as a gradient or color, the Animation class will automatically translate these values and mutate the real attribute appropriately. The following unique attributes can be animated in bonsai:

If you try to animate a color, like this:

thing.animate('1s', { fillColor: 'red' });

The Animation class will grab the current fillColor attribute, and then will determine its R, G, B, and A values. It’ll then animate each of these values individually to reach the targetted R, G, B and A values in the color that you’re animating to (in this case: red).

Keyframe Animations

Bonsai has a KeyframeAnimation class which is designed to provide you with an easy way to set up a series of consecutive animations. For example, if I wanted to animate a shape from {0,0} to {100,100} and then back to {0,0}, without KeyframeAnimation, I would do this:

thing.attr({x:0, y:0}).animate('1s', {
  x: 100,
  y: 100
}, {
  onEnd: function() {
    thing.animate('1s', {
      x: 0,
      y: 0
    })
  }
});

Fortunately, though, bonsai does provide keyframe animations so you can simply do:

thing.animate(new KeyframeAnimation('2s', {
  '0%': { x: 0, y: 0 },
  '50%': { x: 100, y: 100 },
  '100%': { x: 0, y: 0 }
}));

The keywords, "from" and "start" are synonymous with 0%, and "to" and "end" are synonymous with 100% so the above could also be written as:

thing.animate(new KeyframeAnimation('2s', {
  from: { x: 0, y: 0 },
  '50%': { x: 100, y: 100 },
  to: { x: 0, y: 0 }
}));

The key part of the animation definitions (to, from, 50%, etc.) can be defined in a number of ways:

The KeyframeAnimation class will automatically fill any undefined properties at half-way points in your animation series. See the code below:

new KeyframeAnimation('1s', {
   '0s' : { x: 0, y: 0 },
  '.5s' : { x: 50, y: 50 },
   '1s' : { x: 150, y: 100 }
});

You can omit the y property in the .5s keyframe because KeyframeAnimation will automatically calculate the halfways point between its 0s value (0) and its 1s value (100):

new KeyframeAnimation('1.5s', {
   '0s' : { x: 0, y: 0 },
  '.5s' : { x: 50 },
   '1s' : { x: 150, y: 100 }
});