animate()

Animate the specified properties of the object to the specified values.

Syntax animate(properties [, options])

Return Type displayObject

Description

Animate the specified properties of the object to the specified values. Only numeric values can be animated. As of version 2.4.0, nested properties can be animated (such as { start: { x: 50 } } for animating the x coordinate for the start point of a line).

Since version 2.2.0, there is a new syntax which is shown above. The old syntax is deprecated, and will be removed in version 3.0.0.

The old syntax in version 2.1.1 and previous looks like this:
animate(props [, duration [, easing [, newQueue [, callback ]]]])
animate(props, duration | easing | newQueue | callback [, callback])

In the old syntax, there are a few variations to make it easy to use in the way that you want. The first is just the normal syntax where you need to pass both the duration and easing to specify a callback. The newQueue argument is not needed to specify the callback. In the second variant you can pass any of those three as the second argument. If it is not a callback, you can specify a callback as the third argument. This means you can specify an animation pretty much any way you like. Any argument that is missing will get the default value.

Arguments

properties : Object
Contains the properties that should be animated. Property names are the properties and the values are the end values that the object will reach at the end of the animation.
options : Object (since version 2.2.0)
Options for the animation. The object can contain these properties (all have defaults):

duration : Number
The duration of the animation in milliseconds, or one of these keywords:
  • "short": 500 ms
  • "normal": 1000 ms
  • "long": 2000 ms

Default: "normal"
easing : String or Function
The easing function that should be used. Can be either a custom easing function or one of these easing names as a string: View demos of easing modes
  • linear
  • ease-in-quad
  • ease-out-quad
  • ease-in-out-quad
  • ease-in-cubic
  • ease-out-cubic
  • ease-in-out-cubic
  • ease-in-quart
  • ease-out-quart
  • ease-in-out-quart
  • ease-in-quint
  • ease-out-quint
  • ease-in-out-quint
  • ease-in-sine
  • ease-out-sine
  • ease-in-out-sine
  • ease-in-expo
  • ease-out-expo
  • ease-in-out-expo
  • ease-in-circ
  • ease-out-circ
  • ease-in-out-circ
  • ease-in-elastic
  • ease-out-elastic
  • ease-in-out-elastic
  • ease-in-back
  • ease-out-back
  • ease-in-out-back
  • ease-in-bounce
  • ease-out-bounce
  • ease-in-out-bounce

If a function is used, it will be called with four arguments: current time (in milliseconds), start value, change in value (from start to end) and total duration of the animation (in milliseconds). It should return the value to use for the current position.


Default: "ease-in-out-cubic"
queue : String
Name of the queue to add the animation to. If this is a new name, a queue with that name will be created. Animations in different queues will run simultaneously, while animations in the same queue run after each other. Default: "default".
callback : Function
A function that will be called when the animation has finished. Default: empty function.
duration : Number or String (deprecated in version 2.2.0)
The duration of the animation. Can be either the number of milliseconds or one of these predefined keywords:

  • "short": 500 ms
  • "normal": 1000 ms
  • "long": 2000 ms

Default: "normal"

easing : String or Function (deprecated in version 2.2.0)
The easing function that should be used. Can be either a custom easing function (a percentage value for the time, between 0 and 1, is passed to this function) or any of the predefined function names:

  • ease-in
  • ease-out
  • ease-in-out
  • linear

Default: "ease-in-out"

newQueue : Boolean (since version 2.0.0) (deprecated in version 2.2.0)
If set to true, the engine will create a new animation queue to play the animation in, which allows for multiple animations running at the same time on one object.
callback : Function (deprecated in version 2.2.0)
A function that will be called when the animation is complete.

Return Value

displayObject. Returns the display object itself.

Examples

Example 1

We create a new core instance and a rectangle that we add to the canvas. Then we bind an event handler to the rectangle, which will change the fill color to green when clicked. It will also start an animation, that will rotate the rectangle 360 degrees. With the callback we specify that the fill color should be red when the animation is complete.

View Example
Code 
var canvas = oCanvas.create({
	canvas: "#canvas",
	background: "#ccc",
	fps: 60
});

var rectangle = canvas.display.rectangle({
	x: 177,
	y: 200,
	origin: { x: "center", y: "center" },
	width: 200,
	height: 100,
	fill: "#000"
});

canvas.addChild(rectangle);

rectangle.bind("click tap", function () {
	this.fill = "#0f0";
	canvas.redraw();

	this.animate({
		rotation: this.rotation + 360
	}, {
		duration: "long",
		easing: "ease-in-out-cubic",
		callback: function () {
			this.fill = "#f00";
			canvas.redraw();
		}
	});
});
Output

Example 2

We create a new core instance and a rectangle that we add to the canvas. Then we bind an event handler to the rectangle, which will start two animations. The first animation will rotate the rectangle 360 degrees. The second animation will move the rectangle vertically. As no queue is specified here, they both use the default queue, which means the second animation (the movement) will be queued to start when the rotation has finished.

View Example
Code 
var canvas = oCanvas.create({
	canvas: "#canvas",
	background: "#ccc",
	fps: 60
});

var rectangle = canvas.display.rectangle({
	x: 177, y: 200,
	origin: { x: "center", y: "center" },
	width: 200, height: 100,
	fill: "#000",
	currentPosition: "top"
});

canvas.addChild(rectangle);

rectangle.bind("click tap", function () {

	// Stop any currently running animations
	this.stop();

	// Animate rotation, using default queue
	this.animate({
		rotation: this.currentPosition === "top" ? 360 : 0
	}, {
		easing: "ease-in-out-cubic"
	});

	// Animate movement, also using default queue, which means it queues the animation
	this.animate({
		y: this.currentPosition === "top" ? 400 : 200
	}, {
		easing: "ease-in-out-cubic"
	});

	// Toggle the position for next click
	this.currentPosition = this.currentPosition === "top" ? "bottom" : "top";
});
Output

Example 3

This example is the same as the previous example, except we now specify different queues for the animations. That means they will run simultaneously instead of sequentially. In this example both animations specify a queue, but the important part is really that animations that should run simultaneously should have different queues, which means one of the animations could use the default queue (by not specifying a queue).

View Example
Code 
var canvas = oCanvas.create({
	canvas: "#canvas",
	background: "#ccc",
	fps: 60
});

var rectangle = canvas.display.rectangle({
	x: 177, y: 200,
	origin: { x: "center", y: "center" },
	width: 200, height: 100,
	fill: "#000",
	currentPosition: "top"
});

canvas.addChild(rectangle);

rectangle.bind("click tap", function () {

	// Stop any currently running animations
	this.stop();

	// Animate rotation, using queue="rotation"
	this.animate({
		rotation: this.currentPosition === "top" ? 360 : 0
	}, {
		easing: "ease-in-out-cubic",
		queue: "rotation"
	});

	// Animate movement, using queue="move"
	this.animate({
		y: this.currentPosition === "top" ? 400 : 200
	}, {
		easing: "ease-in-out-cubic",
		queue: "move"
	});

	// Toggle the position for next click
	this.currentPosition = this.currentPosition === "top" ? "bottom" : "top";
});
Output