API Docs for: 1.7.3
Show:

Rekapi.Actor Class

An actor represents an individual component of an animation. An animation may have one or many actors.

Constructor

Rekapi.Actor

(
  • opt_config
)

Parameters:

  • opt_config Object=

    Valid properties:

    • context (Object|CanvasRenderingContext2D|HTMLElement): The rendering context for this actor. If omitted, this Actor gets the parent Rekapi instance's context when it is added with addActor.
    • setup (Function): A function that gets called when the actor is added to an animation with addActor.
    • render (Function(Object, Object)): A function that gets called every time the actor's state is updated (once every frame). This function should do something meaningful with state of the actor (for example, visually rendering to the screen). This function receives two parameters: The first is a reference to the actor's context and the second is an Object containing the current state properties.
    • teardown (Function): A function that gets called when the actor is removed from an animation with removeActor.

Methods

addKeyframeProperty

(
  • keyframeProperty
)
chainable

Associate a Rekapi.KeyframeProperty to this actor. Augments the Rekapi.KeyframeProperty to maintain a link between the two objects. This is a lower-level method, and it is generally better to use keyframe. This is mostly useful for adding a Rekapi.KeyframeProperty back to an actor after it was detached.

Parameters:

copyKeyframe

(
  • copyTo
  • copyFrom
)
chainable

Copies all of the Rekapi.KeyframePropertys from one point on the actor's timeline to another. This is particularly useful for animating an actor back to its original position.

actor
  .keyframe(0, {
    x: 10,
    y: 15
  }).keyframe(1000, {
    x: 50,
    y: 75
  });

// Return the actor to its original position
actor.copyKeyframe(2000, 0);

Example

Parameters:

  • copyTo Number

    The timeline millisecond to copy KeyframeProperties to.

  • copyFrom Number

    The timeline millisecond to copy KeyframeProperties from.

exportTimeline

() Object

Returns:

Object:

A serializable Object of this actor's timeline property tracks and Rekapi.KeyframePropertys.

getEnd

(
  • opt_trackName
)
Number

Parameters:

  • opt_trackName String=

    Optionally scope the lookup to a particular keyframe track.

Returns:

Number:

The millisecond of the last state of an actor (the point in the timeline in which it is done animating). If there are no keyframes, this is 0.

getKeyframeProperty

(
  • property
  • millisecond
)
Rekapi.KeyframeProperty | Undefined

Parameters:

  • property String

    The name of the property track.

  • millisecond Number

    The millisecond of the property in the timeline.

Returns:

Rekapi.KeyframeProperty | Undefined:

A Rekapi.KeyframeProperty that is stored on the actor, as specified by the property and millisecond parameters. This is undefined if no properties were found.

getLength

(
  • opt_trackName
)
Number

Parameters:

  • opt_trackName String=

    Optionally scope the lookup to a particular track.

Returns:

Number:

The length of time in milliseconds that the actor animates for.

getPropertiesInTrack

(
  • trackName
)
Rekapi.KeyframeProperty[] | Undefined

Get all of the Rekapi.KeyframePropertys for a track.

Parameters:

  • trackName String

    The track name to query.

Returns:

getStart

(
  • opt_trackName
)
Number

Parameters:

  • opt_trackName String=

    Optionally scope the lookup to a particular track.

Returns:

Number:

The millisecond of the first animating state of an actor (for instance, if the actor's first keyframe is later than millisecond 0). If there are no keyframes, this returns 0.

getTrackNames

() Array(string)

Returns:

Array(string):

A list of all the track names for an actor.

hasKeyframeAt

(
  • millisecond
  • opt_trackName
)
Boolean

Parameters:

  • millisecond Number

    Point on the timeline to query.

  • opt_trackName String=

    Optionally scope the lookup to a particular track.

Returns:

Boolean:

Whether or not the actor has any Rekapi.KeyframePropertys set at millisecond.

importTimeline

(
  • actorData
)

Import an Object to augment this actor's state. This does not remove keyframe properties before importing new ones.

Parameters:

  • actorData Object

    Any object that has the same data format as the object generated from exportTimeline.

keyframe

(
  • millisecond
  • state
  • opt_easing
)
chainable

Create a keyframe for the actor. The animation timeline begins at 0. The timeline's length will automatically "grow" to accommodate new keyframes as they are added.

state should contain all of the properties that define this keyframe's state. These properties can be any value that can be tweened by Shifty (numbers, RGB/hexadecimal color strings, and CSS property strings). state can also be a function, but this works differently (see "Function keyframes" below).

Note: Internally, this creates Rekapi.KeyframePropertys and places them on a "track." These Rekapi.KeyframePropertys are managed for you by the Rekapi.Actor APIs.

Keyframe inheritance

Keyframes always inherit missing properties from the previous keyframe. For example:

actor.keyframe(0, {
  'x': 100
}).keyframe(1000, {
  // Implicitly specifies the x: 100 from above
  'y': 50
});

Keyframe 1000 will have a y of 50, and an x of 100, because x was inherited from keyframe 0.

Function keyframes

Instead of providing an Object to be used to interpolate state values, you can provide a function to be called at a specific point on the timeline. This function does not need to return a value, as it does not get used to render the actor state. Function keyframes are called once per animation loop and do not have any tweening relationship with one another. This is a primarily a mechanism for scheduling arbitrary code to be executed at specific points in an animation.

// drift is the number of milliseconds that this function was executed
// after the scheduled time.  There is typically some amount of delay
// due to the nature of JavaScript timers.
actor.keyframe(1000, function (drift) {
  console.log(this); // Logs the actor instance
});

Easing

opt_easing, if provided, can be a string or an Object. If opt_easing is a string, all animated properties will have the same easing curve applied to them. For example:

actor.keyframe(1000, {
    'x': 100,
    'y': 100
  }, 'easeOutSine');

Both x and y will have easeOutSine applied to them. You can also specify multiple easing curves with an Object:

actor.keyframe(1000, {
    'x': 100,
    'y': 100
  }, {
    'x': 'easeinSine',
    'y': 'easeOutSine'
  });

x will ease with easeInSine, and y will ease with easeOutSine. Any unspecified properties will ease with linear. If opt_easing is omitted, all properties will default to linear.

Parameters:

  • millisecond Number

    Where on the timeline to set the keyframe.

  • state Object | Function(number)

    The state properties of the keyframe. If this is an Object, the properties will be interpolated between this and those of the following keyframe for a given point on the animation timeline. If this is a function, it will be executed at the specified keyframe. The function will receive a number that represents the delay between when the function is called and when it was scheduled.

  • opt_easing String | Object=

    Optional easing string or Object. If state is a function, this is ignored.

modifyKeyframe

(
  • millisecond
  • stateModification
  • opt_easingModification
)
chainable

Augment the value or easing of the Rekapi.KeyframePropertys at a given millisecond. Any Rekapi.KeyframePropertys omitted in stateModification or opt_easing are not modified.

actor.keyframe(0, {
  'x': 10,
  'y': 20
}).keyframe(1000, {
  'x': 20,
  'y': 40
}).keyframe(2000, {
  'x': 30,
  'y': 60
})

// Changes the state of the keyframe at millisecond 1000.
// Modifies the value of 'y' and the easing of 'x.'
actor.modifyKeyframe(1000, {
  'y': 150
}, {
  'x': 'easeFrom'
});

Example

Parameters:

  • millisecond Number
  • stateModification Object
  • opt_easingModification Object=

modifyKeyframeProperty

(
  • property
  • millisecond
  • newProperties
)
chainable

Modify a Rekapi.KeyframeProperty stored on an actor. Internally, this calls modifyWith and then performs some cleanup.

Example

Parameters:

moveKeyframe

(
  • from
  • to
)
Boolean

Moves all of the Rekapi.KeyframePropertys from one point on the actor's timeline to another. Although this method does error checking for you to make sure the operation can be safely performed, an effective pattern is to use hasKeyframeAt to see if there is already a keyframe at the requested to destination.

Example

Parameters:

  • from Number

    The millisecond of the keyframe to be moved.

  • to Number

    The millisecond of where the keyframe should be moved to.

Returns:

Boolean:

Whether or not the keyframe was successfully moved.

removeAllKeyframes

() chainable

Remove all Rekapi.KeyframePropertys set on the actor.

NOTE: This method does not fire the beforeRemoveKeyframeProperty or removeKeyframePropertyComplete events. This method is a bulk operation that is more efficient than calling removeKeyframeProperty many times individually, but foregoes firing events.

Example

removeKeyframe

(
  • millisecond
)
chainable

Remove all Rekapi.KeyframePropertys set on the actor at a given millisecond in the animation.

Example

Parameters:

  • millisecond Number

    The location on the timeline of the keyframe to remove.

removeKeyframeProperty

(
  • property
  • millisecond
)
Rekapi.KeyframeProperty | Undefined

Remove a single Rekapi.KeyframeProperty from the actor.

Parameters:

Returns:

Rekapi.KeyframeProperty | Undefined:

The removed KeyframeProperty, if one was found.

wait

(
  • until
)
chainable

Extend the last state on this actor's timeline to simulate a pause. Internally, this method copies the final state of the actor in the timeline to the millisecond defined by until.

Example

Parameters:

  • until Number

    At what point in the animation the Actor should wait until (relative to the start of the animation timeline). If this number is less than the value returned from getLength, this method does nothing.