jQuery Bend Gauge

Short introduction.

One picture is worth more than thousands of words:

Getting started

Download a plugin from repository (normal or minified version), then you need to embed some scripts:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js" type="text/javascript"></script>
<script src="http://cdnjs.cloudflare.com/ajax/libs/raphael/2.1.0/raphael-min.js" type="text/javascript"></script>
<script src="jquery.bend-gauge.js" type="text/javascript"></script>

And create an empty layer. Then, initialize Bend Gauge using its namespaced function:

<div id="indicator"></div>

$('#indicator').bendGauge();

That's all!

Some examples

Setting a value

The primary purpose of this plugin is to show numerical value in "circular" way. So, go ahead!

As you can see, setting a value is pretty simple. Just initialize Bend Gauge and use jQuery's val() function. Alternatively you can call it using its namespace:

$('#indicator').bendGauge('value', 10);

Enabling particular bends

The second purpose of this indicator is to provide a simple platform for fx effects. You can enable bends using two functions: set and setMatrix. Both of them get an array as argument but first one needs numerical indexes and second one - an array with true/false values. For more information, try this example:

Rotating

Any state of the bends could be rotated by desired amount.

Flashing

Flashing is available as well.

Stacking operations

You can order a few operations to the Bend Gauge and they will be executed in specified order.

Infinite operations

The rotation and flashing could be performed till the manual stopping.

Configuration options

Default configuration object:

duration: 200,
delayFactor: 1/3,
disabledColor: 'rgba(0,0,0,.6)',
fillColor: 'rgba(255,255,255,0.8)',
glow: [
    {
        width: 10,
        opacity: 0.7,
        color: '#D30000'
    },
    {
        width: 3,
        opacity: 0.7,
        color: '#D07872'
    }
],
easing: 'linear',
queue: 'jquery-bend-gauge'

duration: Specifies a duration of animation for particular bend (msec).
delayFactor: A factor that specifies how fast in timing next bend should be enabled in setting value. This time is calculated as delayFactor*duration, so - for example - if delayFactor = 1/3 and duration = 300, the next bend will start to (dis)appear in 100ms after previous one.
disabledColor and fillColor: Colors for disabled and enabled bends. See: syntax.
glow: Glows for bends. Could be false or array of Raphael's glow definitions.
easing: See: Raphael docs.

Callbacks and a few words about API construction

Plugin has a queueable architecture - it allows to execute a function after any method.

You can specify the callback in two ways: as an argument or chainable method.

$('#control').bendGauge('rotate', 2, function(){...});

$('#control').bendGauge('rotate', 2).bendGauge('callback', function(){...});

API functions

(constructor)([Object options]): Instantiates Bend Gauge. Optionally, applies supplied options.
array getMatrix(): Returns a matrix-array with true/false values of bends states.
setMatrix(array idx, [Function callback]): Sets states using matrix-array values.
callback(Function callback): Appends a callback onto queue.
on(Number idx, [Function callback]): Enable bend of idx index.
off(Number idx, [Function callback]): Opposite to on.
options(Object options): Sets options for Gauge. Notice: after instantiation, it wouldn't (yet) change colors and glows.
set(Array idx, [Function callback]): Sets indexes specified in idx array. The missing ones will be turned off.
array get: Gets indexes of enabled bends.
value(Number val, [Function callback]): Sets indicator to the specified value.
flash(Number times, [Function callback]): Flash specified times. If times is empty, flashes till the stop.
rotate(Number amount, [Function|Number callbackOrDirection]): Rotates enabled bends by number of steps. amount greater than zero - clockwise; lower - counter clockwise. It may perform infinite rotations (till the stop) if amount is empty and callbackOrDirection specifies direction just like amount one.
stop: Clears all ordered animations.
clear: Clears all enabled bends.

Once again about queues

If you want to sync animations with jQuery's things, set options.queue to fx.

Known limitations

Currently, this plugin has constant number of bends used (so maximum value too) to 10. It's planned to make it more flexible so you will gain a control over almost all aspects of configuration.

Reporting bugs

It's almost certain that this plugin contains some bugs I've tried to find out but it's impossible to notice all of them. So feel free, to create issue in GitHub's tracker or - even better - submit a pull request to fix problem you found.

I kindly ask you to post a JSFiddle with the working bug case. It will noticeably improve the process of bug hunting.

Thanks

I want to say thank you! for jQuery Developers and Dmitry Baranovskiy for great libraries that unleashed my imagination. ;)