Dialify
=======
Overview
--------
Dialify is a jQuery plugin which replaces instances of the <meter> element with
a <canvas>-drawn dial.
Features:
- customisation of size and colours
- customisation of min/max angle
- customisation of which dial parts are drawn and their sizes
- use an image to draw entirely custom dials
Usage
-----
To use the default settings, simply call the dialify method on the appropriate
meter elements:
$('meter.mydial').dialify();
This creates a dial in a canvas of 100x100px, with a white dial drawn in it. The
resulting canvas will be given a class of 'dialify-meter'.
Customisation options can be passed in like so:
$('meter#mydial2').dialify({
'width': 60,
'height': 60,
'class': 'my-awesome-dial'
});
This will create a 60x60px canvas, which will be given a class of 'my-awesome-dial'.
The dial will use the defaults for any unspecified options.
The examples folder contains some practical demonstrations of various options.
Browser Support
---------------
Dialify should work in all browsers supporting the HTML5 canvas API. To make it
work in IE 7/8, the ExplorerCanvas library will need to be used (http://code.google.com/p/explorercanvas/).
Unfortunately, there are some problems concerning rotation of images, so I have
provided a version patched using http://dev.sencha.com/playpen/tm/excanvas-patch/.
This version should work correctly, and can be found in the lib folder. The examples
make use of this to ensure they work in IE.
Options
-------
Options marked with an asterisk (*) have no meaning when a custom image is being
used (see 'Using a Custom Image'), and are ignored.
Option Default
--------------------------- -----------------------
width 100
The width of the canvas - if the width & height do not match, the dial is drawn
in the centre, using the smaller of the two dimensions as a diameter.
height 100
The height of the canvas - if the width & height do not match, the dial is drawn
in the centre, using the smaller of the two dimensions as a diameter.
class 'dialify-meter'
The class given to the new canvas element
drawDialFace* true
Draw the dace of the dial (outline, background and shaded scale area).
scaleArcRadius* [automatically fits to the dial size]
This is the radius from the pointer rotation point to the outside edge of the
shaded scale area. This allows the scale to be grown/shrunk independently of
the overall dial size.
drawSpindle* true
Draw the centre spindle (the part the dial is attached to).
dialFaceColor* '#FFF'
The background colour for the dial face.
dialOutlineColor* '#000'
The colour of the dial face outline.
scaleRangeColor* '#DDD'
The colour of the shared scale area representing the range from min to max.
pointerColor* '#000'
The colour of the dial's pointer.
spindleColor* '#999'
The colour of the centre spindle to which the needle is attached.
spindleOutlineColor* '#000'
The outline colour of the centre spindle
pointerWidth* 4
Thickness of the pointer.
pointerRotationPoint [automatically determines the centre based on dial size]
Takes an object in the form { 'x': 50 , 'y': 50 }, representing the point around
which the pointer rotates. Either component (x or y) may be omitted and the
default will be used.
pointerRange { min: 0 - (Math.PI * 1.25), max: (Math.PI * 0.25) }
The angles in radians which make up the min and max points on the dial. These are
specified in radians, and the zero point is at the 3 o'clock position. Like the
pointerRotationPoint option, either part may be omitted. However it is best to
specify them both. The default options place the min point between the 7 and
8 o'clock position, and the max point between the 4 and 5 o'clock position.
pointerLength [automatically determined based on the scaleArcRadius setting]
The length of the pointer, from the centre point to the tip.
image [none]
This option specifies an image file to be used for rendering a custom dial image.
See the following section for full details.
Using a Custom Image
--------------------
Dialify offers the option of using an image for building up an entirely custom
dial look-and-feel. This will normally be combined with the width/height options
and the options for manipulating the pointer range and rotation point to build
up the correct effect.
The image file contains all the parts needed for the dial including the background,
the pointer and any overlay which is required (such as a spindle or a glossy cover).
The image dimensions should be as follows:
The letters/functions used below represent:
x: the desired width of the dial
y: the desired height of the dial
Max(): returns the largest of the provided numbers
width:
2*x
height:
1*y + Max(x, y)
The top left section of the image is where the background is drawn. This section
is enclosed in the region defined by these points:
top left: 0, 0
bottom right: x, y
The top right section is where the overlay is drawn. This is the final part drawn
on to the dial.
top left: x, 0
bottom right: x*2, y
Across the bottom of these two sections, a 1-pixel gap is left. This is intentional.
The remaining section of the image is where the pointer is drawn. This section
is defined with the following corners:
top left: 0, y+1
bottom right: x*2, y + Max(x,y) + 1
The pointer should be drawn so that it is in the 3 o'clock position. The centre
point is always assumed to be in the very centre of this section, at this point
in the image:
pointer rotation point: x, (y+1) + (Max(x, y) / 2)
See the examples folder for an example of this image. The pointer section is as
large as it is to ensure it is possible to cater for any possibility, including
that of having a pointer which has a counter-weight on the other side, or consists
of a disc with a hole marking the current point. This should all be possible.