Skip to content

Latest commit

 

History

History
420 lines (293 loc) · 8.71 KB

api.kapi.md

File metadata and controls

420 lines (293 loc) · 8.71 KB
Raw

Kapi

Kapi

/**
 * @param {HTMLCanvas|HTMLElement|Object} canvas
 * @param {Object=} opt_config
 * @constructor
 */
Kapi (canvas, opt_config)

Create a Kapi instance. canvas is (typically) an HTML 5 <canvas> from the DOM. This <canvas> is where the animation is drawn. canvas can also be an HTMLElement, please see dom.md for documentation of DOM animations.

Functional properties of opt_config:

  • fps: The frames per second at which the animation updates.
  • height: The height to set upon canvas.
  • width: The width to set upon canvas.

addActor

/**
 * @param {Kapi.Actor} actor
 * @returns {Kapi}
 */
Kapi.prototype.addActor (actor)

Add a Kapi.Actor to a Kapi instance.

getActor

/**
 * @param {number} actorId
 * @returns {Kapi.Actor}
 */
Kapi.prototype.getActor (actorId)

Retrieve an Actor from the Kapi instance by its ID. All Actor's have an id property.

getAllActors

/**
 * @returns {Kapi.Actor}
 */
Kapi.prototype.getAllActors ()

Retrieve all Actors in a Kapi instance as an Object.

getActorIds

/**
 * @returns {Array}
 */
Kapi.prototype.getActorIds ()

Retrieve the IDs of all Actors in a Kapi instance as an Array.

removeActor

/**
 * @param {Kapi.Actor} actor
 * @returns {Kapi}
 */
Kapi.prototype.removeActor (actor)

Remove actor from the animation. This does not destroy actor, it only removes the link between actor and the Kapi instance.

play

/**
 * @param {number=} opt_howManyTimes
 * @returns {Kapi}
 */
Kapi.prototype.play (opt_howManyTimes)

Play the animation on a loop, either a set amount of times or infinitely. If opt_howManyTimes is omitted, the animation will loop infinitely.

playFrom

/**
 * @param {number} millisecond
 * @param {number=} opt_howManyTimes
 * @returns {Kapi}
 */
Kapi.prototype.playFrom (millisecond, opt_howManyTimes)

Move to a specific millisecond on the timeline and play from there. opt_howManyTimes works as it does in play().

playFromCurrent

/**
 * @param {number=} opt_howManyTimes
 * @returns {Kapi}
 */
Kapi.prototype.playFrom (opt_howManyTimes)

Play from the last frame that was drawn with render(). opt_howManyTimes works as it does in play().

pause

/**
 * @returns {Kapi}
 */
Kapi.prototype.pause ()

Pause the animation. A "paused" animation can be resumed from where it left off with play().

stop

/**
 * @param {boolean} alsoClear
 * @returns {Kapi}
 */
Kapi.prototype.stop (alsoClear)

Stop the animation. A "stopped" animation will start from the beginning if play() is called upon it again. If alsoClear is true, the contents of the canvas will be cleared. It is false by default.

isPlaying

/**
 * @returns {boolean}
 */
Kapi.prototype.isPlaying ()

Return whether or not the animation is playing (meaning not paused or stopped).

animationLength

/**
 * @returns {number}
 */
Kapi.prototype.animationLength ()

Return the length of the animation, in milliseconds.

actorCount

/**
 * @returns {number}
 */
Kapi.prototype.actorCount ()

Return the number of Actors in the animation.

framerate

/**
 * @param {number=} opt_newFramerate
 * @returns {number}
 */
Kapi.prototype.framerate (opt_newFramerate)

Get and optionally set the framerate of the animation. There's generally no point in going above 60.

render

/**
 * @param {number} millisecond
 * @returns {Kapi}
 */
Kapi.prototype.render (millisecond)

Calculate the positions for all Actors at millisecond, and then draw them. You can define any millisecond in the animation to render, so long as it is less than the length of the animation (see animationLength).

draw

/**
 * @returns {Kapi}
 */
Kapi.prototype.draw ()

Draw all the Actors at whatever position they are currently in.

redraw

/**
 * @returns {Kapi}
 */
Kapi.prototype.redraw ()

Re-render() the last frame that was render()ed.

calculateActorPositions

/**
 * @param {number} millisecond
 * @returns {Kapi}
 */
Kapi.prototype.calculateActorPositions (millisecond)

Update the position of all the Actors at millisecond, but do not draw them.

updateInternalState

/**
 * @returns {Kapi}
 */
Kapi.prototype.updateInternalState ()

Invalidate and re-compute the internal state of the Kapi.

exportTimeline

/**
 * @return {Object}
 */
Kapi.prototype.exportTimeline ()

Export a reference-less dump of this Kapi's animation properties and Actors.

moveActorToLayer

/**
 * @param {Kapi.Actor} actor
 * @param {number} layer
 * @returns {Kapi|undefined}
 */
Kapi.prototype.moveActorToLayer (actor, layer)

Move an Actor around in the layer list. Each layer has one Actor, and Actors are drawn in order of their layer. Lower layers (starting with 0) are drawn earlier. If layer is higher than the number of layers (which can be found with actorCount()) or lower than 0, this method will return undefined.

bind

/**
 * @param {string} eventName
 * @param {function} handler
 * @returns {Kapi}
 */
Kapi.prototype.bind (eventName, handler)

Bind an handler function to a Kapi event. Possible events include:

  • onFrameRender: Fires when a frame is rendered.
  • onAnimationComplete: Fires when all loops have finished.
  • onPlayStateChange: Fires when the animation is played, paused, or stopped.
  • onPlay: Fires when the animation is play()ed.
  • onPause: Fires when the animation is pause()d.
  • onStop: Fires when the animation is stop()ped.

unbind

/**
 * @param {string} eventName
 * @param {function=} opt_handler
 * @returns {Kapi}
 */
Kapi.prototype.unbind (eventName, opt_handler)

Unbind opt_handler from a Kapi event. If opt_handler is omitted, all handler functions bound to eventName are unbound. Valid events correspond to the list under bind().

setOrderFunction

/**
 * @param {function(Kapi.Actor, number)} sortFunction
 * @return {Kapi}
 */
Kapi.prototype.setOrderFunction (sortFunction)

Set a function that defines the draw order of the Actors. This is called each frame before the Actors are drawn. The following example assumes that all Actors are circles that have a radius property. The circles will be drawn in order of the value of their radius, from smallest to largest. This has the effect of layering larger circles on top of smaller circles, giving a sense of perspective.

kapi.setOrderFunction(function (actor) {
  return actor.get().radius;
});

unsetOrderFunction

/**
 * @return {Kapi}
 */
Kapi.prototype.unsetOrderFunction (sortFunction)

Remove the sort order function set by setOrderFunction. Draw order defaults back to the order in which Actors were added.

canvas_setContext

/**
 * @param {HTMLCanvas|HTMLElement|Object} canvas
 * @returns {CanvasRenderingContext2D|HTMLElement|Object}
 */
Kapi.prototype.canvas_setContext (canvas)

Define the context that Kapi is rendering in. This can be either an HTML 5 , other DOM element, or Object. Note that if canvas is not an HTML 5 , canvas_clear doesn't do anything.

canvas_getContext

/**
 * @returns {CanvasRenderingContext2D|HTMLElement|Object}
 */
Kapi.prototype.canvas_getContext ()

Return the 2d context of the <canvas>. This is needed for any and all drawing operations - it is also provided to an Actor's draw method. See the MDN for more info on the <canvas> context.

canvas_height, canvas_width

/**
 * @param {number=} opt_height
 * @returns {number}
 */
Kapi.prototype.canvas_height (opt_height)

/**
 * @param {number=} opt_width
 * @returns {number}
 */
Kapi.prototype.canvas_width (opt_width)

These methods get and optionally set their respective dimensions on the canvas.

canvas_style

/**
 * @param {string} styleName
 * @param {number|string=} opt_styleValue
 * @returns {number|string}
 */
Kapi.prototype.canvas_style (styleName, opt_styleValue)

Get and optionally set a CSS style on the canvas.

canvas_clear

/**
 * @returns {Kapi}
 */
Kapi.prototype.canvas_clear ()

Erase the canvas. This only does something if Kapi is bound to an HTML 5 <canvas>.