jQuery plugin for simple but powerful sprite based animations and panning.
Motio is called on an element representing animation container, where animation is delivered as a CSS background image.
In sprite based animations, container should have the dimensions of one sprite frame. E.g, if you have 10 frames in a horizontal sprite that is 1000 x 100 pixels big, the container should be 100 x 100 pixels big.
In panning, container size doesn't play any role, just the background image should be seamless. Or not :), depending on what are you going for.
$(selector).motio( [ options [, returnInstance ]] );
Object with options. Properties:
- fps:
Int
default: 15
frames per second - vertical:
Bool
default: 0
whether the images in sprite are positioned vertically instead of horizontally - paused:
Bool
default: 0
whether to start animation paused
- frames:
Int
default: 0
number of frames in sprite - if this option remains0
, it is considered that you are requesting panning animation type
Panning is decided by frames option above. If you want to pan background, leave frames option at 0
.
- speed:
Int
default: 50
panning speed in pixels per second - bgSize:
Int
default: 50
background size so motio could reset background position if it gets over this value. not required
Boolean argument requesting to return a plugin instance instead of a chainable jQuery object. You can than use all methods documented below directly on this instance.
If motio is called on more than one element, it returns an array of instances.
var bgPan = $('#bg').motio( options, true );
bgPan.set( 'speed', 100 );
bgPan.play();
All methods can be called via .motio()
call:
$(selector).motio( methodName [, arguments, ... ] );
Or directly via Motio instance:
// Calling motio with `returnInstance = true`, and saving the instance
var motioInstance = $(selector).motio( options, true );
motioInstance.methodName( [ arguments, ... ] );
Reference to Motio instance is also saved in an element data storage. You can retrieve it with:
var motioInstance = $(selector).data('plugin_motio');
$(selector).motio( 'play' );
Starts playing an animation when paused.
$(selector).motio( 'pause' );
Pauses a playing animation.
$(selector).motio( 'toggle' );
Toggles between playing and paused states.
$(selector).motio( 'set', property, value );
Updates one of the options. Only these options can be updates: speed, fps
- property:
String
name of the property that should be updated - value:
Mixed
new property value
$(selector).motio( 'toStart' [, immediate ] );
Animates the animation to the start and than triggers pause. Doesn't work with panning animations.
- immediate:
Bool
move to the start immediately without animation
$(selector).motio( 'toStart' [, immediate ] );
Animates the animation to the end and than triggers pause. Doesn't work with panning animations.
- immediate:
Bool
move to the end immediately without animation
$(selector).motio( 'to', frame [, immediate ] );
Animates the animation to the passed frame index. Doesn't work with panning animations.
- frame:
Int
frame index starting at0
- immediate:
Bool
move to the end immediately without animation
Only for jQuery 1.7+.
$(selector).motio( 'on', eventName, function );
Binds a callback function to one of the custom events trigger by motio.
- eventName:
String
name of a custom event to bind the function to - function:
Function
callback function
If you are using older jQuery version, you can use the equivalent: $(selector).bind('motio:eventName', fn);
.
Only for jQuery 1.7+.
$(selector).motio( 'off', eventName [, function ] );
Unbinds a callback function from one of the custom events trigger by motio. If no function is specified, it unbinds all callbacks.
- eventName:
String
name of a custom event to unbind the function from - function:
Function
callback function
If you are using older jQuery version, you can use the equivalent: $(selector).unbind('motio:eventName', fn);
.
$(selector).motio( 'destroy' );
// or alias
$(selector).motio( false );
Removes motio from elements.
Motio is triggering bunch of useful events. You can bind your callbacks to them in a few different ways:
$(selector).motio( 'on', eventName, function );
// or directly via Motio instance
var motioInstance = $(selector).motio( options, true );
motioInstance.on( eventName, function );
// jQuery <1.7
$(selector).bind( 'motio:eventName', function );
And similarly unbinding with:
$(selector).motio( 'off', eventName, function );
// or via instance
motioInstance.off( eventName, function );
// jQuery <1.7
$(selector).unbind( 'motio:eventName', function );
Integrated Motio on/off methods are using jQuery $.Callbacks API, which is in jQuery sice 1.7+. If you can't use newer versions of jQuery, you can go for jQuery bind/unbind methods called on a frame element, with 'motio:' prefix on all event names.
Triggered on each frame. Receives 2 arguments, which are based on an animation type.
- sprite -
function( activeFrameIndex, numberOfFrames ){ ... }
- active frame index starts at0
- panning -
function( currentPosition, backgroundSize ){ ... }
-backgroundSize
is0
if you haven't passed bgSize in options
When toStart method has been called, this event is triggered when an animation arrives at the start and pauses itself.
When toEnd method has been called, this event is triggered when an animation arrives at the end and pauses itself.
Triggered when animation is paused.
Triggered when animation unpauses itself.
Triggered when toggle method is called.