Motio
jQuery plugin for simple but powerful sprite based animations and panning.
Calling
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 ]] );
[ options ]
Object with options. Properties:
Shared options
- 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
Sprite animation specific options
- frames:
Int
default: 0
number of frames in sprite - if this option remains0
, it is considered that you are requesting panning animation type
Panning animation specific options
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
[ returnInstance ]
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.
Usage:
var bgPan = $('#bg').motio( options, true );
bgPan.set( 'speed', 100 );
bgPan.play();
Methods
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');
play
$(selector).motio( 'play' );
Starts playing an animation when paused.
pause
$(selector).motio( 'pause' );
Pauses a playing animation.
toggle
$(selector).motio( 'toggle' );
Toggles between playing and paused states.
set
$(selector).motio( 'set', property, value );
Updates one of the options. Only these options can be updates: speed, fps
Arguments:
- property:
String
name of the property that should be updated - value:
Mixed
new property value
toStart
$(selector).motio( 'toStart' [, immediate ] );
Animates the animation to the start and than triggers pause. Doesn't work with panning animations.
Arguments:
- immediate:
Bool
move to the start immediately without animation
toEnd
$(selector).motio( 'toStart' [, immediate ] );
Animates the animation to the end and than triggers pause. Doesn't work with panning animations.
Arguments:
- immediate:
Bool
move to the end immediately without animation
to
$(selector).motio( 'to', frame [, immediate ] );
Animates the animation to the passed frame index. Doesn't work with panning animations.
Arguments:
- frame:
Int
frame index starting at0
- immediate:
Bool
move to the end immediately without animation
on
Only for jQuery 1.7+.
$(selector).motio( 'on', eventName, function );
Binds a callback function to one of the custom events trigger by motio.
Arguments:
- 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);
.
off
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.
Arguments:
- 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);
.
destroy
$(selector).motio( 'destroy' );
// or alias
$(selector).motio( false );
Removes motio from elements.
Custom events
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.
frame
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
start
When toStart method has been called, this event is triggered when an animation arrives at the start and pauses itself.
end
When toEnd method has been called, this event is triggered when an animation arrives at the end and pauses itself.
pause
Triggered when animation is paused.
play
Triggered when animation unpauses itself.
toggle
Triggered when toggle method is called.