Examples

Orangutan Preying mantis
Toad Owl

Images from morguefile

Mouse over: -
Mouse co-ords: -, -

Orangutan: mouseover to start rotation animation, mouseout to stop.
Mantis: click to start/stop animation rotation
Toad: click to rotate 360° clockwise
Owl: click and drag to rotate

AWC Image Rotater Documentation

Contents

  1. Overview
  2. Prerequisites
  3. Installation
  4. Quick Start
  5. Tutorial
    1. Initialising
    2. Rotating And Animating
    3. Using The Mouse Events
    4. Accessing Objects Via The Global List
  6. Reference
    1. Configuration Options
    2. Object Properties
    3. Object Methods
    4. Static Properties
    5. Events
  7. Bugs / Issues
  8. Browser Compatibility
  9. Feedback / Bug Reports

Overview

AWC Image Rotater provides a way to rotate images on your web page, either as a one-off rotation operation or an animation. Custom events are provided so your own code can interact with mouse events such as mouseover, mousemove, click etc.

It is a Javascript / HTML5 <canvas> tag solution, and is built on top of the prototype javascript library. As such, it won't work in non-canvas-capable browsers (IE is the only major browser at present).

If you use this software, please drop us an email with a URL.

Prerequisites

This software requires the prototype javascript library. It is known to work with versions 1.6.0.2 and 1.6.1.

Installation

After unzipping the distribution, copy awc_image_rotater-min.js to your website, eg: 


cp awc_image_rotater-1.0/awc_image_rotater.js /www/sites/mysite.com/htdocs/js/

Include the file from the <head> of your web page, eg: 


<script type="text/javascript" src="/js/awc_image_rotater-min.js"></script>

NB: the javascript file must be included after the prototype library.

NB: you should configure your webserver to serve a gzipped version of this software, this will reduce the download size from 16105 bytes to about 4148 bytes.

Quick Start

Rotate an image 30°: 



if ( awc_image_rotater.supported )
{
    // Create the object, and rotate it when initialised
    var rotater1 = new awc_image_rotater( { img: $('thumb-orangutan') } );
    rotater1.observe( 'awc_image_rotater:initialised',
        function(ev)
        {
            rotater1.rotate( 30 );
        } );
}

Start/stop rotation animation on mouse click: 



if ( awc_image_rotater.supported )
{
    var rotater2 = new awc_image_rotater( { img: $('thumb-orangutan') } );
    rotater2.observe( 'awc_image_rotater:mouse_click',
        function(ev)
        {
            if ( !rotater2.is_animating() )
            {
                rotater2.animate( { degrees: 10, steps: 5,
                                    interval: 0.1, loop: true } );
            }
            else
            {
                rotater2.stop_animating();
            }
        } );
}

Tutorial

Initialising

For awc_image_rotater to work, the browser must support the HTML5 <canvas> tag. If it is supported, the awc_image_rotater.supported variable will be true.

The awc_image_rotater works by replacing the image with a copy of that image drawn onto a <canvas> element. It can't do this until the image is fully loaded. It will issue a awc_image_rotater:initialised event when the object is ready for use.

You can either control the rotater by reacting to events it fires, in which case you needn't worry about the awc_image_rotater:initialised event (none of the mouse related events will fire until after intialisation), but if you want to, for example, rotate the image to a certain angle as soon as it's loaded then you need to place your call to the rotate() or animate() method in an awc_image_rotater:initialised event handler: 



// Check for support
if ( awc_image_rotater.supported )
{
    // Create awc_image_rotater object
    var rotater = new awc_image_rotater( img: 'thumb-orangutan' );

    // Wait until it's initialised before using it
    rotater.observe( 'awc_image_rotater:initialised',
        function(ev)
        {
            rotater.rotate( 30 );
        } );
}

Preserving image events

By default, the awc_image_rotater will replace the image with a copy drawn onto a canvas as soon as the image is loaded. You will lose any event handlers you had on the image, and you must then use the custom events. Also important to note is that the canvas must be bigger than the image it is associated with, to accommodate the extra area required when rotated. This extra space around the edges of the image, although invisible, may interfere with the event handling of elements in its immediate vicinity.

You can keep your image events, and stop the canvas from interfering with elements around it, but with limitations. If you set the replace_image configuration option to false, the image will not be immediately replaced by the canvas. Instead, that will happen at the beginning of a rotate() or animate() operation. In the case of the animate() operation, once the rotation is finished, the canvas is replaced by the image, so will only be useful if your animation finishes in the same position as the original image, eg a full 360° rotation or smaller rotation if your image has some rotational symmetry. You will also not be able to use the awc_image_rotater's own custom events.

For example, to spin an image 360° on a mouse click, using the image's own click event (like the toad image on this page): 



var rotater = new awc_image_rotater( { img: $('thumb-toad'),
                                       replace_image: false } );
rotater.img.observe( 'click',
    function(ev)
    {
        rotater.animate( { degress: 360, steps: 20, interval: 0.05 } );
    } );

Rotating And Animating

The rotate() method takes a single argument - the number of degrees by which to rotate the image clockwise. For anti-clockwise rotation use a negative value for degrees: 



// Rotate 20 degrees clockwise
rotater.rotate( 20 );

// Rotate 20 degrees anti-clockwise
rotater.rotate( -20 );

Use the animate() and stop_animating() methods to start and stop a rotation animation. The single argument to animate() is a hash defining the animation with the three required properties degrees, steps and interval. A fourth optional property loop specifies whether to repeat the rotation when finished. If true, the animation is repeated until stop_animating() is called.

When stop_animating() is called, the animation will run to completion but not repeat afterwards. Therefore, stop_animating() is only relevant if the loop property of the animation config was set to true.

You should think of the animation config you supply as a single discrete unit of animation. You should bear this in mind if you want to stop the animation in response to an event (a mouse click for example).

In this example, when the user clicks on the image, the image will continue its rotation until it has gone a full 360°: 



rotater.animate( { degrees: 360, steps: 60, interval: 0.05, loop: true } );
rotater.observe( 'awc_image_rotater:image_click',
    function(ev)
    {
        rotater.stop_rotating();
    } );

In the next example, the image will appear to stop when clicked because the animation rotates in 'units' of 5° instead of 360°. The steps and interval properties are adjusted accordingly to keep roughly the same rotation speed: 



rotater.animate( { degrees: 5, steps: 3, interval: 0.02, loop: true } );
rotater.observe( 'awc_image_rotater:image_click',
    function(ev)
    {
        rotater.stop_rotating();
    } );

Using The Mouse Events

As well as the awc_image_rotater:initialised event, mouse events are also provided, to enable you to react to clicks, mouseover/out etc. These are roughly analogous to regular mouse events. You can add/remove handlers for these events using the observe and stopObserving methods, in the same way you would use the corresponding events in regular prototype coding. For example: 



// Create image_click event handler (using anonymous function)
rotater.observe( 'awc_image_rotater:image_click',
        function(ev)
        {
            // Do something here
        } );

// Remove all image_click event handlers
rotater.stopObserving( 'awc_image_rotater:image_click' );

Your event handler function receives the event object that prototype provides, which contains eventName and memo properties. memo contains the id of the object and three sets of mouse co-ordinates: imageX and imageY - mouse co-ordinates within the image (relative to the image's top left corner and ignoring its rotation); canvasX and canvasY - mouse co-ordinates relative to the top left of the canvas; mouseX and mouseY - actual mouse co-ordinates as supplied to the underlying event handler.

For example, to report the mouse pointer co-ordinates (reative to top left of image) when the user clicks an image (as with the orangutan image on this page): 



if ( awc_image_rotater.supported )
{
    var rotater = new awc_image_rotater( { img: $('thumb-orangutan') } );

    rotater.observe( 'awc_image_rotater:image_click',
        function(ev)
        {
            alert( 'You clicked at co-ordinates (' +
                   ev.memo.imageX + ', ' +
                   ev.memo.imageY + ')' );
        } );
}

The awc_image_rotater:image_mousechange event

If you want to detect when the mouse pointer moves relative to the image, the awc_image_rotater:image_mousemove event isn't going to be any use if the mouse pointer stays still but the image moves. The awc_image_rotater:mousechange event fires whenever the mouse pointer's position over the image changes, which may be caused by the mouse or the image underneath moving. You can see it in action if you move your mouse over the example images on this page (except the toad image) - a handler on image_mousechange event updates the co-ordinate information below the images.

Accessing Objects Via The Global List

Rotater objects can be accessed via the global list awc_image_rotater.rotaters. This is a hash with each object keyed twice - once by its own id, and once by its image's DOM id. The objects are not available in the global list until they have been initialised (ie the awc_image_rotater:initialised event has fired).

For example, to start/stop rotation on mouse click; on two rotater images; using the id supplied by the event handler; using same named function for both handlers: 



var rotater1 = new awc_image_rotater( { img: $('thumb-orangutan') } );
var rotater2 = new awc_image_rotater( { img: $('thumb-toad') } );

function onclick_rotater(ev)
{
    var rot = awc_image_rotater.rotaters[ ev.id ];

    if ( !rot.is_animating() )
    {
        rot.animate( { degrees: 10, steps: 5,
                       interval: 0.05, loop: true } );
    }
    else
    {
        rot.stop_animating();
    }
}

rotater1.observe( 'awc_image_rotater:initialised', onclick_rotater.bindAsEventListener() );
rotater2.observe( 'awc_image_rotater:initialised', onclick_rotater.bindAsEventListener() );

Example: two rotaters, given the ids 'orangutan_rotater' and 'toad_rotater'; when 'orangutan_rotater' is clicked, start/stop the rotation animation of 'toad_rotater': 



var rotater1 = new awc_image_rotater( { img: $('thumb-orangutan'),
                                        id: 'orangutan_rotater' } );
var rotater2 = new awc_image_rotater( { img: $('thumb-toad'),
                                        id: 'toad_rotater' } );

rotater1.observe( 'awc_image_rotater:initialised',
    function(ev)
    {
        rotater1.observe( 'awc_image_rotater:image_click',
            function(ev)
            {
                var rot = awc_image_rotater.rotaters['toad_rotater'];

                if ( !rot.is_animating() )
                {
                    rot.animate( { degrees: 10, steps: 5,
                                   interval: 0.05, loop: true } );
                }
                else
                {
                    rot.stop_animating();
                }
            } );
    } );

Reference

Configuration Options

The awc_image_rotater constructor takes one argument - a hash of configuration options:

Option Description
mixed img The image to rotate. Can be a reference to the image object or a string (the DOM id). Default: null
string id Unique identifier for this object (NB - this is not a DOM id). If not supplied, an id is auto-generated using 'awc_image_rotater__' followed by the image id Default: null
boolean replace_image Whether to initially replace the image with a canvas. This normally happens when the awc_image_rotater object is created. If this option is set to false the replacement is delayed until a rotation (or rotation animation) is performed on the image, and then the image is swapped back when the operation finishes. This gives you the option of being able to use event handlers you've already set on the image. Note though, that enough custom events are provided so that you will rarely need this option. Default: true
int zIndex When two or more images overlap, the z-index decides which image appears on top, and this also affects the firing of the awc_image_rotater:image_mouse(over|out|click) events. Default: null

Object Properties

Property Description
object img Reference to the image DOM element.
string id Unique id of this awc_image_rotater object.

Object Methods

Method Description
animate( object animateConfig ) Perform a rotation animation. animateConfig contains the following properties:
  • numeric degrees - angle to rotate
  • numeric steps - number of steps to perform the animation (ie, in each step the image will be rotated by degrees/steps degrees.
  • float interval - Delay between each animation step.
  • boolean loop - If true, repeat the animation until stop_animating() is called.
You should think of your animation definition in animateConfig as being a discrete unit of animation that will always run to completion, even when stop_animating() is called to stop a looped animation.
awc_image_rotater( object config ) Constructor.
config is a hash of configuration options (see 'config options').
object get_canvas_dimensions() Returns a hash with the width and height properties, which are both floats. Rounded integer versions are also supplied in iWidth and iHeight.
numeric get_canvas_rotation() Returns the image's current angle of rotation.
int get_zIndex() Returns the z-index value.
boolean is_animating() Returns true if the image is currently being animated, false if not.
observe( string event_name, function handler ) Attaches an event handler function to the specified event. See list of custom events.
rotate( numeric degrees ) Rotate the image clockwise by the specified number of degrees. Give a negative value for anti-clockwise rotation.
set_zIndex( int z ) Sets the z-index value.
stop_animating() Stops a looped animation at the end of the current loop.
stopObserving( string event_name, function handler ) Removes an event handler function from the specified event. See list of custom events.

Static Properties

Static Property Description
object awc_image_rotater.rotaters A hash containing all the awc_image_rotater objects on the page. Each object is keyed twice for convenience - once by the object's own id and once by the id of the image they are associated with.
boolean awc_image_rotater.supported Whether or not browser supports awc_image_rotater functionality.

Events

Event name Description
awc_image_rotater:initialised The awc_image_rotater object has finished initialisation (loading image, creating image copy on the canvas etc) and is now safe to use.
awc_image_rotater:image_mouseover
awc_image_rotater:image_mouseout
awc_image_rotater:image_mousemove
awc_image_rotater:image_mousedown
awc_image_rotater:image_mouseup
awc_image_rotater:image_click
awc_image_rotater:image_dblclick
 Analogous to normal mouse events. The Event.memo object provides the following properties:
  • id - the id of the awc_image_rotater object.
  • imageX and imageY - the co-ordinates of the mouse pointer relative to the top left of the image, assuming the whole co-ordinate system is rotated in line with the rotation of the image, so the top left corner of the image is always (0,0).
  • canvasX and canvasY - the co-ordinates of the mouse pointer relative to the top left corner of the canvas.
  • mouseX and mouseY - the actual mouse co-ordinates, as supplied to the underlying event handler.
awc_image_rotater:image_mousechange When the mouse pointer is over the image, this event fires when the position of the mouse pointer changes relative to the image. Similar to awc_image_rotater:image_mousemove, but is also fired if the image moves rather than the pointer.
Receives the same co-ordinate properties as the other mouse events.

Bugs / Issues

No problems reported yet.

Browser Compatibility

This software should run in any Javascript-capable browser that supports the HTML5 canvas tag, and the toDataURL() method of the canvas element. At present (version 1.0), this includes the following browsers:

(NB: this is not an exhaustive list, and will possibly go unmaintained):

  • Firefox: 3 (Windows)
  • Safari: 3(from 3.2) / 4 (Windows)
  • Opera: 9 / 10 (Windows)
  • Chrome: 2 / 3 (Windows)

Please let us know if you find the examples on this page run OK work in any other browsers, and we'll add them to the list.

Reporting Bugs & Other Feedback

To report bugs, please email: awc_image_rotater@tinternet.info.
To report browser compatibilities, please email: awc_image_rotater@tinternet.info.
For any other feedback, please email: awc_image_rotater@tinternet.info.

© 2012 Advanced Web Construction Ltd