diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..94986f2 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,38 @@ +**2.2.2** :: *7th Aug 2014* + +- Fixing another extremely rare jamming of animations. Rendering pipeline has been more streamlined so there shouldn't be more of this. + +**2.2.1** :: *18th Apr 2013* + +- Fixing extremely rare jamming of sprite based animations. + +**2.2.0** :: *11th Apr 2013* + +- Exposing `element` property. +- Fixing immediate animation breaking other animations. + +**2.1.0** :: *6th Apr 2013* + +- Adding `width` & `height` options. + +**2.0.2** :: *5th Apr 2013* + +- Removing forgotten toggle event. + +**2.0.1** :: *5th Apr 2013* + +- Fixing `.to()` method not returning current instance. + +**2.0.0** :: *5th Apr 2013* + +- Dropping jQuery dependency. +- Adding optional jQuery plugin version of Motio. +- Improved events API. +- Method `.toStart()` - when called on an animation that is already at the start - will repeat the animation from the end. Ditto for the `.toEnd()` method. +- Methods `.toStart()`, `.toEnd()`, and `.to()` now accept callbacks. +- Removed `toStart`, `toEnd`, and `to` events. +- Added reversed sprite based animation playback by passing `true` into the `.play()` method's first argument. + +**1.0.0** :: *25th May 2012* + +The initial Motio version, dependent on jQuery. \ No newline at end of file diff --git a/README.md b/README.md index e853cf5..eb06ff8 100644 --- a/README.md +++ b/README.md @@ -17,9 +17,36 @@ Motio has no dependencies, but there is an optional Works everywhere. -### [Changelog](https://github.com/darsain/motio/wiki/Changelog) - -Motio upholds the [Semantic Versioning Specification](http://semver.org/). +## Usage + +Sprite animation mode: + +```js +var element = document.querySelector('#sprite'); +var sprite = new Motio(element, { + fps: 10, + frames: 14 +}); +sprite.play(); // start animation +sprite.pause(); // pause animation +sprite.toggle(); // toggle play/pause +``` + +Seamless background panning mode: + +```js +var element = document.querySelector('#panning'); +var panning = new Motio(element, { + fps: 30, // Frames per second. More fps = higher CPU load. + speedX: -30 // Negative horizontal speed = panning to left. +}); +sprite.play(); // start animation +sprite.pause(); // pause animation +sprite.toggle(); // toggle play/pause +sprite.toStart(); // animate to 1st frame and stop +sprite.toEnd(); // animate to last frame and stop +sprite.to(10); // animate to 11th frame and stop +``` ## Download @@ -39,23 +66,7 @@ When isolating issues on jsfiddle, you can use this URL: ## Documentation -- **[Markup](https://github.com/darsain/motio/wiki/Markup)** - how should the HTML & CSS look like -- **[Calling](https://github.com/darsain/motio/wiki/Calling)** - how to call Motio -- **[Options](https://github.com/darsain/motio/wiki/Options)** - all available options -- **[Properties](https://github.com/darsain/motio/wiki/Properties)** - accessible Motio object properties -- **[Methods](https://github.com/darsain/motio/wiki/Methods)** - all available methods, and how to use them -- **[Events](https://github.com/darsain/motio/wiki/Events)** - all available events, and how to register callbacks - -*Other languages are maintained by 3rd parties.* - -### Chinese - -- [Markup](http://strongme.github.io/Motio-Wiki-CN-Markup.html) -- [Calling](http://strongme.github.io/Motio-Wiki-CN-Calling.html) -- [Options](http://strongme.github.io/Motio-Wiki-CN-Options.html) -- [Properties](http://strongme.github.io/Motio-Wiki-CN-Properties.html) -- [Methods](http://strongme.github.io/Motio-Wiki-CN-Methods.html) -- [Events](http://strongme.github.io/Motio-Wiki-CN-Events.html) +Can be found in the [docs](https://github.com/darsain/motio/tree/master/docs) directory. ## Contributing diff --git a/docs/Calling.md b/docs/Calling.md new file mode 100644 index 0000000..1d3bf55 --- /dev/null +++ b/docs/Calling.md @@ -0,0 +1,39 @@ +# Calling + +```js +var motio = new Motio( frame [, options ] ); +``` + +This will create a new Motio object, ready to be used. By default, everything is turned off, so calling the Motio with all default options will leave you with a dead FRAME that doesn't do anything. + +New Motio object is also paused, so if you want to immediately start the animation, you have to call the `.play()` method afterwards. + +The list & documentation of all methods available can be found in the [Methods documentation page](Methods.md). + +--- + +### frame + +Type: `Element` + +DOM element of an object with animation background. Example: + +```js +var motio = new Motio(document.getElementById('frame')); // Native +var motio = new Motio($('#frame')[0]); // With jQuery +``` + +### options + +Type: `Object` + +Object with Motio options. All options are documented in the [Options Wiki page](Options.md). + + +## Calling via jQuery plugin + +```js +$('#frame').motio( [ options ] ); +``` + +Initiating motio via a jQuery plugin automatically starts the animation, so you don't have to call the `.play()` method afterwards. You can disable this with [`startPaused`](Options.md#startpaused) option. \ No newline at end of file diff --git a/docs/Events.md b/docs/Events.md new file mode 100644 index 0000000..c28f8e6 --- /dev/null +++ b/docs/Events.md @@ -0,0 +1,50 @@ +# Events + +You can register callbacks to Motio events with `#on()` and `#off()` methods: + +```js +var motio = new Motio(frame, options); + +// Register a callback to multiple events +motio.on('play pause', fn); + +// Start playing the animation +motio.play(); +``` + +More usage examples can be found in the [on & off methods documentation](Methods.md#on). + +## Common arguments + +#### this + +The `this` value in all callbacks is the Motio object triggering the event. With it you have access to all [Motio object properties](Properties.md). + +#### 1st argument + +All callbacks receive the event name as the first argument. + +--- + +Example: + +```js +motio.on('frame', function (eventName) { + console.log(eventName); // 'frame' + console.log(this.frame); // frame index +}); +``` + +## Events + +### pause + +Triggered when animation is paused. + +### play + +Triggered when animation is resumed. + +### frame + +Triggered on each animation frame. \ No newline at end of file diff --git a/docs/Markup.md b/docs/Markup.md new file mode 100644 index 0000000..119238f --- /dev/null +++ b/docs/Markup.md @@ -0,0 +1,68 @@ +# Markup + +Motio animates the background position of an element passed to it. The background can be a seamless image (panning animation), or an animation frames sprite (sprite based animation). + +### Example + +You have an element with background that holds either seamless repeating image (for panning), or animation frames sprite (sprite based animation). + +```html +
+
+``` + +The size and background of the elements is handled by your CSS. + +```css +.panning { + width: auto; // Span to the full width of container + height: 300px; + background: url('seamless-sky.jpg'); +} + +.sprite { + width: 256px; // Width of one animation frame + height: 256px; // Height of one animation frame + background: url('animation_frames_sprite.png'); +} +``` + +Motio calls than look like this: + +```js +// Panning +var element = document.querySelector('#panning'); +var panning = new Motio(element, { + fps: 30, // Frames per second. More fps = higher CPU load. + speedX: -30 // Negative horizontal speed = panning to left. +}); +sprite.play(); // start animation + +// Sprite +var element = document.querySelector('#sprite'); +var sprite = new Motio(element, { + fps: 10, + frames: 14 +}); +sprite.play(); // start animation +``` + +Motio knows that animation is sprite based when you set the `frames` option. + +Initiating animation with `#play()` method is not needed when calling via a jQuery proxy, as in this case the animation is initiated automatically after `new Motio` object has been created. Motio assumes that you are using jQuery proxy just to initiate animation and leave it alone. Calling methods and controlling the Motio animations via jQuery proxy, even when possible, just doesn't make sense. There is a `new Motio`, why would you even selector proxy everything... ? + +For more options and methods and everything, [RTFM](README.md). + +## Panning + +There are no rules in the panning mode. Just give element a background, and pass it to Motio. + +## Sprite + +To have a correctly working sprite based animation, you need an element that is the exact size of a one animation frame. Example: + +![Sprite markup](http://i.imgur.com/Sazfe0Q.png) + +This means that the element width & height (specifically the element's border box size) has to equal the width & height of one animation frame. The element size is set by you in CSS. You can set padding, margin, and border, Motio will still work, as long as the border-box size equals the size of one frame. The only thing that'll break it is changing the `background-origin`. So don't touch that :) + +Also, calling spriote based Motio on hidden elements just doesn't work, as Motio cannot retrieve their size. In this case, use [`width`](Options.md#width) & [`height`](Options.md#height) options to set the width and height of the element manually. \ No newline at end of file diff --git a/docs/Methods.md b/docs/Methods.md new file mode 100644 index 0000000..9028bfd --- /dev/null +++ b/docs/Methods.md @@ -0,0 +1,179 @@ +# Methods + +Motio has a handful of very useful methods. You can call them directly on a [new Motio object](Calling.md): + +```js +var motio = new Motio(frame, options); +// Play method call +motio.play(); +``` + +All methods return the current Motio object, unless specified otherwise. This means that you can chain method calls if you want: + +```js +motio.on('frame', callback).set('speedX', 50).play(); +``` + +#### Calling methods via a jQuery plugin proxy + +If you are using the jQuery plugin version of Motio, you can also call all methods via a proxy, like this: + +```js +$('#frame').motio('methodName' [, arguments... ] ); +``` + +Assuming the `$('#frame')` element has already a Motio object associated with it. This happens when [calling a Motio via a jQuery plugin](Calling.md#calling-via-jquery-plugin). Example: + +```js +$('#frame').motio('toEnd', callbackFunction); +``` + +## Methods + +### #play([reverse]) + +Starts playing continuous animation that doesn't stop until interrupted by other methods. + +- **[reverse]** `Boolean` Pass true to animate in the opposite direction. + +The **reverse** argument is relevant only in sprite animation mode, as panning animation direction is controlled by passing a positive or negative integers into the `speedX` & `speedY` options. + +### #pause() + +Pauses the current animation. + +### #toggle() + +Pauses when playing, resumes when paused. + +### #toStart([immediate], [callback]) + +*Available only in sprite animation mode!* + +Animate to the first frame, and pause the animation. If the first frame is already active, it will repeat the animation from the last frame. + +- **[immediate]** `Boolean` Whether the last frame should be activated immediately, skipping the animation. +- **[callback]** `Function` Callback to be fired when animation reaches the destination. + +If you interrupt the animation before it reaches the destination, callback won't fire. + +```js +motio.toStart(true); // Activate first frame immediately without animation. +motio.toStart(callback); // Execute callback when animation reaches the destination. +motio.toStart(true, callback); // Combination of both arguments. +``` + +### #toEnd([immediate], [callback]) + +*Available only in sprite animation mode!* + +Animates to the last frame, and pause the animation. If the last frame is already active, it will repeat the animation from the first frame. + +- **[immediate]** `Boolean` Whether the last frame should be activated immediately, skipping the animation. +- **[callback]** `Function` Callback to be fired when animation reaches the last frame. + +If you interrupt the animation before it reaches the destination, callback won't fire. + +```js +motio.toEnd(true); // Activate last frame immediately without animation. +motio.toEnd(callback); // Execute callback when animation reaches the destination. +motio.toEnd(true, callback); // Combination of both arguments. +``` + +### #to(frame, [immediate], [callback]) + +*Available only in sprite animation mode!* + +Animate to the specified frame, and pause the animation. + +- **[frame]** `Integer` Animation destination frame index, starting at `0`. +- **[immediate]** `Boolean` Whether the last frame should be activated immediately, skipping the animation. +- **[callback]** `Function` Callback to be fired when animation reaches the destination. + +If you interrupt the animation before it reaches the destination, callback won't fire. + +If the current active frame is specified as the destination, Motio will be paused, and callback will be fired immediately. + +```js +motio.to(2, true); // Activate 3rd frame immediately without animation. +motio.to(2, callback); // Execute callback when animation reaches the 3rd frame. +motio.to(2, true, callback); // Combination of both arguments. +``` + +### #set(name, value) + +Change a specified option value. + +- **name** `String` Name of the option to be changed. +- **value** `Mixed` New option value. + +Only these options can be changed dynamically: + +- fps +- speedX +- speedY + +Example: + +```js +motio.set('speedX', 100); +``` + +### #on(eventName, callback) + +Registers a callback to one or more of the Motio events. All available events and arguments they receive can be found in the [Events documentation](Events.md). + +- **eventName:** `Mixed` Name of the event, or callback map object. +- **callback:** `Mixed` Callback function, or an array with callback functions. + +Examples: + +```js +// Basic usage +motio.on('frame', function () {}); + +// Multiple events, one callback +motio.on('play pause', function () {}); + +// Multiple callbacks for multiple events +motio.on('play pause', [ + function () {}, + function () {} +]); + +// Callback map object +motio.on({ + play: function () {}, + frame: [ + function () {}, + function () {} + ] +}); +``` + +### #off(eventName, [callback]) + +Removes one, multiple, or all callbacks from one of the Motio events. + +- **eventName]** `String` Name of the event. +- **[callback]** `Mixed` Callback function, or an array with callback functions to be removed. Omit to remove all callbacks. + +Examples: + +```js +// Removes one callback from load event +motio.off('load', fn1); + +// Removes one callback from multiple events +motio.off('load move', fn1); + +// Removes multiple callbacks from multiple event +motio.off('load move', [ fn1, fn2 ]); + +// Removes all callbacks from load event +motio.off('load'); +``` + +### #destroy() + +Pauses the animation, and resets the background position to `0 0`. \ No newline at end of file diff --git a/docs/Options.md b/docs/Options.md new file mode 100644 index 0000000..b38ab9b --- /dev/null +++ b/docs/Options.md @@ -0,0 +1,121 @@ +# Options + +All default options are stored in the `Motio.defaults` object. You can modify them simply by: + +```js +Motio.defaults.fps = 60; +``` + +By default, everything is disabled. Initiating Motio with all default options will leave you with a dead FRAME that doesn't do anything. + +## Quick reference + +Motio call with all default options as defined in the source. + +```js +var panning = new Motio(element, { + fps: 15, // Frames per second. + + // Sprite animation specific options + frames: 0, // Number of frames in sprite. + vertical: 0, // Tells Motio that you are using vertically stacked sprite image. + width: 0, // Set the frame width manually (optional). + height: 0, // Set the frame height manually (optional). + + // Panning specific options + speedX: 0, // Horizontal panning speed in pixels per second. + speedY: 0, // Vertical panning speed in pixels per second. + bgWidth: 0, // Width of the background image (optional). + bgHeight: 0 // Height of the background image (optional). +}); +``` + +# Options + +--- + +### fps + +Type: `Int` +Default: `15` + +Animation frames per second. Bigger number means smoother animations, but higher CPU load. Maximum value is 60. + +*This option can be changed dynamically with `.set()` method.* + +## Sprite animation mode specific options + +### frames + +Type: `Integer` +Default: `null` + +How many frames are in the sprite image. Setting this options triggers the sprite animation mode. Otherwise Motio is in the panning mode. + +### vertical + +Type: `Boolean` +Default: `false` + +Tells Motio that you are using vertically stacked sprite image. + +### width + +Type: `Integer` +Default: `0` + +Sets the frame width manually. This is highly optional, as Motio figures out this value automatically, but if the element you are applying Motio to is currently hidden, this is impossible. In such situation use this option to help Motio out. + +### height + +Type: `Integer` +Default: `0` + +Sets the frame height manually. This is highly optional, as Motio figures out this value automatically, but if the element you are applying Motio to is currently hidden, this is impossible. In such situation use this option to help Motio out. + +## Panning mode specific options + +### speedX + +Type: `Integer` +Default: `null` + +Horizontal animation speed in pixels per second. Use negative values to move backwards. + +*This option can be changed dynamically with `.set()` method.* + +### speedY + +Type: `Integer` +Default: `null` + +Vertical animation speed in pixels per second. Use negative values to move backwards. + +*This option can be changed dynamically with `.set()` method.* + +### bgWidth + +Type: `Integer` +Default: `null` + +Width of the background image used for panning. This is highly optional. + +This and `bgHeight` options are needed so the Motio will know when to reset the background position back to 0, and thus not overflow the JavaScript's 2^53 integer limit. When omitted, the position will iterate into ridiculous numbers, which will in a few million years cause a buggy animation... You basically set these options if you have OCD. + +### bgHeight + +Type: `Integer` +Default: `null` + +Height of the background image used for panning. This is highly optional. + +## jQuery plugin options + +These options are relevant only when initiating Motio via a jQuery proxy. + +### startPaused + +Type: `Boolean` +Default: `0` + +By default, initiating via a jQuery plugin automatically starts the animation. Passing `true` into this value will prohibit that. \ No newline at end of file diff --git a/docs/Properties.md b/docs/Properties.md new file mode 100644 index 0000000..96e93bc --- /dev/null +++ b/docs/Properties.md @@ -0,0 +1,62 @@ +# Properties + +Motio object exposes some useful properties: + +### #element + +Type: `Object` + +The element Motio is called on. + +### #options + +Type: `Object` + +Object with all options used by the current Motio object. This is essentially a `Motio.defaults` object extended by options passed to `new Motio()`. + +### #width + +Type: `Integer` + +Width of the frame. Doesn't update, so if you have a panning animation on `body` element and you resize the window, it will not reflect in this value. You don't really ever need this property in panning mode anyway. + +### #height + +Type: `Integer` + +Height of the frame. Doesn't update, so if you have a panning animation on `body` element and you resize the window, it will not reflect in this value. You don't really ever need this property in panning mode anyway. + +### #isPaused + +Type: `Boolean` + +This property is `true` when Motio is paused, `false` otherwise. + +## Panning mode specific properties + +### #pos + +Type: `Object` + +Background position object: + +```js +{ + x: 100, // Horizontal background position. + y: 100 // Vertical background position. +} +``` + +## Sprite mode specific properties + +### #frame + +Type: `Integer` + +Active frame index. + +### #frames + +Type: `Integer` + +Number of frames total. \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..4582718 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,21 @@ +# Documentation + +- **[Markup](Markup.md)** - how should the HTML & CSS look like +- **[Calling](Calling.md)** - how to call Motio +- **[Options](Options.md)** - all available options +- **[Properties](Properties.md)** - accessible Motio object properties +- **[Methods](Methods.md)** - all available methods, and how to use them +- **[Events](Events.md)** - all available events, and how to register callbacks + +## Other languages + +*Other languages are maintained by 3rd parties.* + +#### Chinese + +- **[Markup](http://strongme.github.io/Motio-Wiki-CN-Markup.html)** +- **[Calling](http://strongme.github.io/Motio-Wiki-CN-Calling.html)** +- **[Options](http://strongme.github.io/Motio-Wiki-CN-Options.html)** +- **[Properties](http://strongme.github.io/Motio-Wiki-CN-Properties.html)** +- **[Methods](http://strongme.github.io/Motio-Wiki-CN-Methods.html)** +- **[Events](http://strongme.github.io/Motio-Wiki-CN-Events.html)** \ No newline at end of file