Rekapi src/rekapi.core.js

Kapi

function
Kapi()
  • @param: {Object}opt_config
  • @constructor:

Description

Rekapi constructor. Valid values for opt_config are:

  • context (Object): The context that the animation will run in. Can be any type of Object; gets used by the renderer and inherited by the Kapi.Actors as they are added to the animation. This isn't always needed, it usually just applies to <canvas> animations. See the documentation on the <canvas> extension for more info.

Example

Source

function Kapi (opt_config) {
    this.config = opt_config || {};
    this.context = this.config.context || {};
    this._actors = {};
    this._playState = playState.STOPPED;

    this._events = {
      'animationComplete': []
      ,'playStateChange': []
      ,'play': []
      ,'pause': []
      ,'stop': []
      ,'beforeUpdate': []
      ,'afterUpdate': []
      ,'addActor': []
      ,'removeActor': []
    };

    // How many times to loop the animation before stopping.
    this._timesToIterate = -1;

    // Millisecond duration of the animation
    this._animationLength = 0;

    // The setTimeout ID of `tick`
    this._loopId = null;

    // The UNIX time at which the animation loop started
    this._loopTimestamp = null;

    // Used for maintaining position when the animation is paused.
    this._pausedAtTime = null;

    // The last millisecond position that was updated
    this._lastUpdatedMillisecond = 0;

    _.extend(this.config, opt_config);

    this._scheduleUpdate = getUpdateMethod();
    this._cancelUpdate = getCancelMethod();

    _.each(this._contextInitHook, function (fn) {
      fn.call(this);
    }, this);

    return this;
  }


  // Decorate the Kapi object with the dependencies so that other modules can
  // access them.
  Kapi.Tweenable = Tweenable;
  Kapi._ = _;

addActor

method
Kapi.prototype.addActor()
  • @param: {Kapi.Actor}actor
  • @return: {Kapi}

Description

Add a Kapi.Actor to the animation.

Example

Source

Kapi.prototype.addActor = function (actor) {
    // You can't add an actor more than once.
    if (!_.contains(this._actors, actor)) {
      if (!actor.context()) {
        actor.context(this.context);
      }

      actor.kapi = this;
      this._actors[actor.id] = actor;
      recalculateAnimationLength(this, _);
      actor.setup();

      fireEvent(this, 'addActor', _, actor);
    }

    return this;
  };

getActor

method
Kapi.prototype.getActor()
  • @param: {number}actorId
  • @return: {Kapi.Actor}

Description

Retrieve a Kapi.Actor from the Kapi instance by its ID. All Actors have an id property.

Example

Source

Kapi.prototype.getActor = function (actorId) {
    return this._actors[actorId];
  };

getActorIds

method
Kapi.prototype.getActorIds()
  • @return: {Array.<number>}

Description

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

Example

Source

Kapi.prototype.getActorIds = function () {
    return _.pluck(this._actors, 'id');
  };

getAllActors

method
Kapi.prototype.getAllActors()
  • @return: {Array}

Description

Retrieve all Kapi.Actors in the animation as an Object. Actors' IDs correspond to the property names of the returned Object.

Example

Source

Kapi.prototype.getAllActors = function () {
    return _.clone(this._actors);
  };

removeActor

method
Kapi.prototype.removeActor()
  • @param: {Kapi.Actor}actor
  • @return: {Kapi}

Description

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

Example

Source

Kapi.prototype.removeActor = function (actor) {
    delete this._actors[actor.id];
    delete actor.kapi;
    actor.teardown();
    recalculateAnimationLength(this, _);

    fireEvent(this, 'removeActor', _, actor);

    return this;
  };

play

method
Kapi.prototype.play()
  • @param: {number}opt_howManyTimes
  • @return: {Kapi}

Description

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

Example

Source

Kapi.prototype.play = function (opt_howManyTimes) {
    cancelLoop(this);

    if (this._playState === playState.PAUSED) {
      this._loopTimestamp += now() - this._pausedAtTime;
    } else {
      this._loopTimestamp = now();
    }

    this._timesToIterate = opt_howManyTimes || -1;
    this._playState = playState.PLAYING;
    tick(this);

    fireEvent(this, 'playStateChange', _);
    fireEvent(this, 'play', _);

    return this;
  };

playFrom

method
Kapi.prototype.playFrom()
  • @param: {number}millisecond
  • @param: {number}opt_howManyTimes
  • @return: {Kapi}

Description

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

Example

Source

Kapi.prototype.playFrom = function (millisecond, opt_howManyTimes) {
    this.play(opt_howManyTimes);
    this._loopTimestamp = now() - millisecond;

    return this;
  };

playFromCurrent

method
Kapi.prototype.playFromCurrent()
  • @param: {number}opt_howManyTimes
  • @return: {Kapi}

Description

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

Example

Source

Kapi.prototype.playFromCurrent = function (opt_howManyTimes) {
    return this.playFrom(this._lastUpdatedMillisecond, opt_howManyTimes);
  };

pause

method
Kapi.prototype.pause()
  • @return: {Kapi}

Description

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

Example

Source

Kapi.prototype.pause = function () {
    if (this._playState === playState.PAUSED) {
      return this;
    }

    this._playState = playState.PAUSED;
    cancelLoop(this);
    this._pausedAtTime = now();

    fireEvent(this, 'playStateChange', _);
    fireEvent(this, 'pause', _);

    return this;
  };

stop

method
Kapi.prototype.stop()
  • @return: {Kapi}

Description

Stop the animation. A "stopped" animation will start from the beginning if play() is called.

Example

Source

Kapi.prototype.stop = function () {
    this._playState = playState.STOPPED;
    cancelLoop(this);

    // Also kill any shifty tweens that are running.
    _.each(this._actors, function (actor) {
      actor.stop();
    });

    fireEvent(this, 'playStateChange', _);
    fireEvent(this, 'stop', _);

    return this;
  };

isPlaying

method
Kapi.prototype.isPlaying()
  • @return: {boolean}

Description

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

Example

Source

Kapi.prototype.isPlaying = function () {
    return this._playState === playState.PLAYING;
  };

animationLength

method
Kapi.prototype.animationLength()
  • @return: {number}

Description

Return the length of the animation, in milliseconds.

Example

Source

Kapi.prototype.animationLength = function () {
    return this._animationLength;
  };

lastPositionUpdated

method
Kapi.prototype.lastPositionUpdated()
  • @return: {number}

Description

Return the normalized (between 0 and 1) timeline position that was last calculated.

Example

Source

Kapi.prototype.lastPositionUpdated = function () {
    return (this._lastUpdatedMillisecond / this._animationLength);
  };

actorCount

method
Kapi.prototype.actorCount()
  • @return: {number}

Description

Return the number of Kapi.Actors in the animation.

Example

Source

Kapi.prototype.actorCount = function () {
    return _.size(this._actors);
  };

update

method
Kapi.prototype.update()
  • @param: {number=}opt_millisecond
  • @return: {Kapi}

Description

Update the position of all the Kapi.Actors to opt_millisecond. If opt_millisecond is omitted, update to the last millisecond that the animation was updated to (it's a re-update).

Example

Source

Kapi.prototype.update = function (opt_millisecond) {
    if (opt_millisecond === undefined) {
      opt_millisecond = this._lastUpdatedMillisecond;
    }

    fireEvent(this, 'beforeUpdate', _);
    _.each(this._actors, function (actor) {
      actor.updateState(opt_millisecond);
      if (typeof actor.update === 'function') {
        actor.update(actor.context(), actor.get());
      }
    });
    this._lastUpdatedMillisecond = opt_millisecond;
    fireEvent(this, 'afterUpdate', _);

    return this;
  };

on

method
Kapi.prototype.on()
  • @param: {string}eventName
  • @param: {Function}handler
  • @return: {Kapi}

Description

Bind a handler function to a Kapi event. Valid events are:

  • animationComplete: Fires when all animations loops have completed.
  • playStateChange: Fires when the animation is played, paused, or stopped.
  • play: Fires when the animation is play()ed.
  • pause: Fires when the animation is pause()d.
  • stop: Fires when the animation is stop()ped.
  • beforeUpdate: Fires each frame before all Actors are updated.
  • afterUpdate: Fires each frame after all Actors are updated.
  • addActor: Fires when an Actor is added.
  • removeActor: Fires when an Actor is removed.
  • timelineModified: Fires when a keyframe is added, modified or removed.

Example

Source

Kapi.prototype.on = function (eventName, handler) {
    if (!this._events[eventName]) {
      return;
    }

    this._events[eventName].push(handler);

    return this;
  };

off

method
Kapi.prototype.off()
  • @param: {string}eventName
  • @param: {Function}opt_handler
  • @return: {Kapi}

Description

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().

Example

Source

Kapi.prototype.off = function (eventName, opt_handler) {
    if (!this._events[eventName]) {
      return;
    }

    if (!opt_handler) {
      this._events[eventName] = [];
    } else {
      this._events[eventName] = _.without(this._events[eventName],
        opt_handler);
    }

    return this;
  };

exportTimeline

method
Kapi.prototype.exportTimeline()
  • @return: {Object}

Description

Export the current state of the animation into a serializable Object.

Example

Source

Kapi.prototype.exportTimeline = function () {
    var exportData = {
      'duration': this._animationLength
      ,'actors': []
    };

    _.each(this._actors, function (actor) {
      exportData.actors.push(actor.exportTimeline());
    }, this);

    return exportData;
  };

importTimeline

method
Kapi.prototype.importTimeline()
  • @param: {Object}KapiDataAny object that has the same data format as the object generated from Kapi#exportTimeline.

Description

Import data that was created as a result of Kapi#exportTimeline. Sets up all necessary actors and keyframes. Note that this method only creates Kapi.Actor instances, not subclasses.

Source

Kapi.prototype.importTimeline = function (kapiData) {
    _.each(kapiData.actors, function (actorData) {
      var actor = new Kapi.Actor();
      actor.importTimeline(actorData);
      this.addActor(actor);
    }, this);
  };


  Kapi.util = {};

  // Some hooks for testing.
  if (KAPI_DEBUG) {
    Kapi._private = {
      'calculateLoopPosition': calculateLoopPosition
      ,'updateToCurrentMillisecond': updateToCurrentMillisecond
      ,'tick': tick
      ,'determineCurrentLoopIteration': determineCurrentLoopIteration
      ,'calculateTimeSinceStart': calculateTimeSinceStart
      ,'isAnimationComplete': isAnimationComplete
      ,'updatePlayState': updatePlayState
    };
  }

  root.Kapi = Kapi;

};