kapi( canvas, params, events )
This is a reference to your canvas on the DOM.
Optional parameters you may pass to the kapi instance. You can pass:
canvas.canvas is cleared out after each frame is rendered. This is true by default..clear() automatically after .stop() is called. This is false by default..clear() automatically after an .iterate() or repeat() sequence completes. This is false by default.An object containing events that can be set on this instance of Kapi. Supply event handlers as functions. Available events:
kapiInstance.getVersion()
kapiInstance.getContext()
canvas that Kapi is controlling.kapiInstance.isPlaying()
kapiInstance.play()
Starts the animation if it was not running before, or resumes the animation if it was not running previously.
kapiInstance.pause()
Freeze the animation at its current state. Resuming from the paused state does not start the animation from the beginning, the state of the animation is maintained.
kapiInstance.stop()
Stops the animation. When the animation is started again with play(), it starts from the beginning of the loop. Note: The canvas will be cleared out automatically for you if the clearOnStop option is set to true. This option is set to false by default.
kapiInstance.repeat( repetitions, callback )
Play the animation for a set amount of repetitions. After starting over the specified amount of times, the animation will call stop(). Note: The canvas will be cleared out automatically for you if the clearOnComplete option is set to true. This option is set to false by default.
A number. The number of times to start over.
A Function. An optional callback function that will be invoked when the repeat() sequence completes.
kapiInstance.iterate( iterations, callback )
Play the animation and let it run for a set amount of iterations. After running for the specified amount of times, the animation will call stop(). This is extremely similar to the functionality of kapiInstance.repeat(), but the parameter controls how many times the animation runs for, not how many times it starts over. Note: The canvas will be cleared out automatically for you if the clearOnComplete option is set to true. This option is set to false by default.
A number. The number of times to run for.
A Function. An optional callback function that will be invoked when the iterate() sequence completes.
kapiInstance.clear()
Clears out the canvas and sets it to its default color.
kapiInstance.redraw()
Forces a redraw of the current actors' states. Handy if used in tandem with .clear().
kapiInstance.add( actor, initialState, setupParams )
Add an actor to the animation. Importantly, this method returns a reference to the actor that it added to the Kapi instance.
A function or object. This is an actor template.
If you are passing a function: Logically, this function should draw something to the canvas. All actor functions access their state properties with the this JavaScript keyword. Actor functions get a reference to the canvas's context as the first parameter, a reference to the kapi instance as the second, and the actor object as the third. This means that all public Kapi APIs are available from within any actor's draw method. Handy note: A reference to the canvas element can be be retrieved from the context like so: ctx.canvas Here's an example of an actor:
function circle(ctx, kapiInst, actorInst){
ctx.beginPath();
ctx.arc(
this.x || 0,
this.y || 0,
this.radius || 0,
0,
Math.PI*2,
true
);
ctx.fillStyle = this.color || '#f0f';
ctx.fill();
ctx.closePath();
return this;
}
If you are passing an Object: You can pass an object with any number of the following properties:
kapi.add(), so the same rules apply.kapi.removeActor()). This method receives the actor's name as a string for the first parameter, and the Kapi instance as the second parameter.Here's a example of an actor similar to the previous example, but as an object with setup and teardown methods:
var circle = {
setup: function (kapiInst, actorInst, params) {
if (console) {
console.log('Setting up ', this)
}
},
draw: function (ctx, kapiInst, actorInst){
ctx.beginPath();
ctx.arc(
this.x || 0,
this.y || 0,
this.radius || 0,
0,
Math.PI*2,
true
);
ctx.fillStyle = this.color || '#f0f';
ctx.fill();
ctx.closePath();
return this;
},
teardown: function (actorName, kapiInst) {
if (console) {
console.log('Tearing down ', this);
}
}
}
An object defining the initial state for the actor. If an actor uses a property in any of its keyframes, it must be present in this Object. There is a special data parameter you can add here. It simply stores arbitrary data on the actor, and can be updated and accessed at any time with actor.data(). This data property is not present on any of the keyframes. Note: If the name property is not provided, it is added automatically as a random string.
This can be anything - but it's probably best to make it an Object. Whatever you specify for this parameter, it will be passed along to the actor's setup parameter as the third parameter (see example above).
Here's an example of how to call kapiInstance.add():
myKapi = kapi(document.getElementsByTagName('canvas')[0]);
myCircle = myKapi.add(circle, {
name: myCircle,
x: 70,
y: 70,
radius: 50,
color: '#00ffaa',
easing: 'easeInOutQuint',
data: {
val: 'You can store whatever data you please here and access it later with myCircle.data().'
}
}, {
setupParam1: "Hello! I am a setup parameter! I get passed into the actor's `setup` function!"
});
kapiInstance.removeActor( actorName )
Completely removes an actor from the animation. This also removes all keyframes for the removed actor. This method calls the actor's teardown method, if one was defined when the actor was added.
A string. The name of the actor to be removed.
kapiInstance.removeAllKeyframes()
Remove all of the keyframes for all of the actors in the animation. Aside from the fact that added actors are still available in the Kapi instance, this effectively resets the state of Kapi.
kapiInstance.gotoFrame( frame )
Go to a specific frame in the animation. You can go to any frame, it doesn't have to be a keyframe.
A keyframe identifier (integer, {number}s or {number}ms) specifying which frame to go to and render. Specify an integer if you know exactly what frame you want to go to. If you want to go to a frame that exists at a specific amount of time into the animation, pass a string in the {number}s or {number}ms formats. {number}s is seconds, "{number}ms" is milliseconds.
myKapi.gotoFrame('1.5s');
This will go to and render the frame that exists 1.5 seconds into the animation.
kapiInstance.gotoAndPlay( frame )
Works exactly like gotoFrame(), but has the added benefit of also .play()ing the animation.
kapiInstance.getState()
Gets the current state of all of the actors in the animation as an object.
kapiInstance.getNumberOfLayers()
Gets the number of layers currently in the Kapi instance. Note: This is also the same as the number of actors in the animation.
kapiInstance.getActor( actorName )
Get a specific actor object.
A string representing the name of the actor to fetch.
kapiInstance.getActorList()
Returns a list of all the actors currently registered with this Kapi instance.
kapi.getActor().kapiInstance.framerate( newFramerate )
Gets or sets the framerate that Kapi updates at. The current framerate is always returned, but if an argument is specified, Kapi's framerate is set to that number.
The new framerate to set.
newFramerate is an integer and greater than 0, this number is the same as newFramerate.kapiInstance.bind( eventName, handler )
Bind an event handler to a Kapi event. Throughout the course of its execution, Kapi fires events at verious key points. You can attach an event handler that gets invoked when these events fire. You can attach as many event handlers to an event as you'd like; event handlers are invoked in the order they are attached.
Event handlers are invoked in the context of the Kapi instance. This means the this keyword is a reference to the Kapi object.
You can bind event handlers to the following events:
enterFrame: Fires at the beginning of every frame.loopStart: Fires once per loop, at the beginning of the loop.loopComplete: Fires once per loop, at the end of the loop.A string. The name of the event to bind an event handler to.
A function. The event handler to attach.
function myHandler () {
console.log('Hello there.');
}
var demo = kapi(document.getElementById('myCanvas'));
demo.bind('enterFrame', myHandler);
kapiInstance.unbind( eventName, handler )
Remove an event handler from the Kapi instance. You can either remove a specific handler from the event, or all of them - this is determined by the presence of the handler parameter. If present, this method will only unbind the specified event handler. If the handler parameter is omitted, all of the event handlers for this event are unbound. Valid event names are the same as those listed in .bind().
A string. The name of the event to unbind an event handler from.
A function. A reference to the handler function to unbind.
function myHandler () {
console.log('Hello there.');
}
var demo = kapi(document.getElementById('myCanvas'));
demo
.bind('enterFrame', myHandler)
.unbind('enterFrame', myHandler);