Animator - Javascript

Dual licensed under the MIT and GPL version 3 licenses.

What's this

Animator is ment to create smother animations when possible. It uses requestAnimationFrame as callback routine. It also has an queue system to prevent multiple simultaneous routines being used at the same time.

Questions

If you have any questions you're more then welcome to contact me on twitter: ErikLandvall, or just add an issue here on github and I will answer as fast as I can.

See

Example of use

Let's start of by defining our rendering loop:

var loop = function()
{
  // do cool stuff
}

Then we need an instance of Animator:
The new interface has a static alternative that doesn't require this step

var instance = new Animator();

Now we want to add the loop to Animators queue:

var id = instance.addCallback( loop );

// Or you can use a shorter alternative:
var id = instance.add( loop );

// And then there is a static alternative:
var id = Animator.add( loop );

By adding the loop to a queue we are able to use multiple rendering loops within the same callback routin. Just stack them on by using addCallback

By adding a callback to the routine we also start the animation. If we wish to prevent this to manually start the routine at a later point we have to declare this when calling the method. We do this by passing on a false third parameter to the method:

var id = instance.add( loop, null, false );

// Static alternative:
var id = Animator.add( loop, null, false );

To start the routine manually:

instance.start();

// Static alternative:
Animator.start();

To stop Animator from calling the loop we need to remove it from the queue, we can do this manually or specify how many times the loop should be called upon adding it to the queue.

To do it manually we need to alter the rendering loop:

var loop = function( i )
{
  if( i == expectedLength )
  {
    instance.removeCallback( id );

    // Or a more simple alternative:
    instance.remove( id );

    // Static alternative:
    Animator.remove( id );
    
    return;
  }

  // do cool stuff
}

Tough, if we alredy know the expected length then we can specify this when we add the loop to the queue:

instance.add( loop, expectedLength );

// Static alternative:
Animator.add( loop, expectedLength );

By specifying the expected length when we add the loop to the queue we no longer need to alter the animation loop.

When there's no longer any callbacks in the queue then the routine will automatically stop. If you by any reason would like to stop or pause the routine at any time then use the method stop:

instance.stop();

// Static alternative:
Animator.stop();

Animators instance interface

Name	Return type	Parameters	Description
start	Animator		Starts the animation loop, if not already running.
stop	Animator		Stops/Pauses the animation loop, if running.
isRunning	boolean		Returns if animation loop is currently running.
getCallback	function\|null	int\|string id The id of the callback we wont returned	Returns the callback by specified id. If id dosn't exists in queue, null is returned
get	*Alias for "getCallback" and "getQueue". If param is undefined then the whole queue is returned.*
setCallback	Animator	int\|string id The id of the callback function fn The callback we wish to set int length [optional] How many times we wish to call upon the callback	Sets a callback function with a given id. This can also be used to replace an alredy existing callback. WARNING! Using this function is not the recomended way to add a function to the queue. Use addCallback for this purpose instead.
set	*Alias for "setCallback" and "setQueue".*
addCallback	int\|array	function\|array fn The function, or an array of functions, we wish to add to the queue int length [optional] How many times we wish to call upon the callback start boolean [optional] If true, the callback routine will automatically start after callbacks are added. Defaults to true	Adds one or many functions to the queue. Returns the generated id or an array of them if multiple callbacks where specicified.
add	*Alias for "addCallback"*
removeCallback	Animator	int\|function\|object fn The id, function or instance we wish to remove from the queue	Removes a callback from the queue and stops the routine if there's no more callbacks in the queue.
remove	*Alias for "removeCallback"*
getQueue	Object		Returns the current queue
setQueue	Animator	Object queue The queue new queue	Clears the old queue and sets a new one.
clearQueue	Animator		Unsets the queue
clear	*Alias for "clearQueue"*
isQueueEmpty	boolean		Returns if the queue is empty.
getElement	Element\|undefined		Returns the specified element we wish to render on.
setElement	Animator	Element element The element to render in	Not required! If specifyed one may optimize the animation.
removeElement	Animator		Removes any specified element to render in.

Animators static interface

OBS! All the methods that are availible from the instance interface are also availible in the static interface.

Name	Return type	Parameters	Description
getInstance	Animator		Lazyloads an instance that can be accessed through a static interface.