Gauge API

#Canvas Gauge API

ATTENTION This wiki is for canvas gauges v1. Documentation for version 2+ is available here.

Canvas gauge allows to implement various customizable gauges on an HTML page within element. It does not require any other external library like jQuery or something. BTW by using the library it's easy to create plugins for such kind of the tools, for example, we can found an AngularJS directive build on top of canv-gauge.

Instead of using JavaScript API the gauge could be easily configured via plain HTML definition. To learn how to do that, please, refer Gauge HTML API.

Configuration Options

The configuration options are provided to Gauge constructor as an object which could contain any of the parameters described below. The only one parameter is mandatory. So to create a gauge on a page it is enough to initialize it like this:

var gauge = new Gauge({ renderTo: 'canvas-id' }); gauge.draw();

renderTo - {String|HTMLCanvasElement} - HTML canvas element ID or element itself. This identifies the canvas element to which a gauge will be drawn. This parameter is mandatory to specify.

width - {Integer} - canvas width in pixels

height - {Integer} - canvas height in pixels

title - {String} - the title which should be drawn on a gauge. By default is false (no title to display)

minValue - {Number} - the minimal value which is used on a gauge bar. Default is 0

maxValue - {Number} - the maximum value which is used on a gauge bar. Default is 100

majorTicks - {Array} - array of a major tick marks. By default is ['0', '20', '60', '80', '100']

minorTicks - {Integer} - number of minor ticks to draw between major ticks on a gauge bar. Default is 10.

strokeTicks - {Boolean} - the flag which identifies if the ticks bar should be stroked or not. By default is true.

units - {String} - specify a units name which will be shown on a gauge. By default is false (do not display the units).

valueFormat - {Object} - specify how the value should be displayed. It is possible to specify an integer part of the value and the decimal part. By default is { int : 3, dec : 2 }

updateValueOnAnimation - {Boolean} - specifies if value should be constantly updated during needle animation, by default is false.

glow - {Boolean} - indicates if shadow glow should be drawn for gauge plate or not

animation - {Object} - Gauge needle animation config. Handles three options - delay, duration and animate function.

• duration - {Integer} milliseconds - total number of animation duration
• fn - {String|Function} - animation function to use. Possible string values are 'linear', 'quad', 'quint', 'cycle', 'bounce', 'elastic'. If requires to implement another animation behavior - animation function itself could be provided instead of string value. This function takes one argument 'progress' which is a numeric value between 0 and 1. This function is called on each animation iteration to calculate the value for needle should be set on current iteration.

Examples:

animation : false /* no animation is used to display value on a gauge */ animation : { duration : 400, fn : 'elastic' } animation : { duration : 400, fn : function( p) { return Math.pow( p, 3) } /* cubic animation implementation */ }

colors - {Object} - the colors to use on a different gauge parts when drawing. Could be specified in hex ('#000000' - '#ffffff') or RGB with/without the alpha channel. Defaults are:

plate: '#fff',
majorTicks: '#444',
minorTicks: '#666',
title: '#888',
units: '#888',
numbers: '#444',
needle: {
	start: 'rgba(240, 128, 128, 1)',
	end: 'rgba(255, 160, 122, .9)',
	circle: {
	  outerStart: '#f0f0f0',
	  outerEnd: '#ccc',
	  innerStart: '#e8e8e8',
	  innerEnd: '#f5f5f5'
	},
	shadowUp: 'rgba(2, 255, 255, 0.2)',
	shadowDown: 'rgba(188, 143, 143, 0.45)'
},
valueBox: {
	rectStart: '#888',
	rectEnd: '#666',
	background: '#babab2',
	shadow: 'rgba(0, 0, 0, 1)'
},
valueText: {
	foreground: '#444',
	shadow: 'rgba(0, 0, 0, 0.3)'
},
circle: {
	shadow: 'rgba(0, 0, 0, 0.5)',
	outerStart: '#ddd',
	outerEnd: '#aaa',
	middleStart: '#eee',
	middleEnd: '#f0f0f0',
	innerStart: '#fafafa',
	innerEnd: '#ccc'
}

highlights - {Array} - an array of highlights colors which could be drawn on a gauge bar. If specified as an empty array or false will not be drawn. By default is:

[{ from: 20, to: 60, color: '#eee' }, { from: 60, to: 80, color: '#ccc' }, { from: 80, to: 100, color: '#999' }]

Where from is a value to start highlight draw from, to - the value to which highlight draw to, color - the color to use.

circles - {Object} - used to determine the visibility of the gauge's outer, middle and inner circles, which are drawn outside the gauge's major ticks. We can hide one or all of these circles as we wanted. By default all circles are visibles, that is:

circles: {
	outerVisible: true,
	middleVisible: true,
	innerVisible: true
}

valueBox - {Object} - right now this allow us to shown or hide the gauge's value box. We can show the gauge's value text but hide the box (see below). By default is:

valueBox: {
	visible: true
}

valueText - {Object} - this allow us to shown or hide the gauge's value text. Note if we hide the value text also the value box (see above) are hidden. By default is:

valueText: {
	visible: true
}

Methods

Gauge( {Object} options) - constructor. Takes configuration options as an argument. Configuration options are described above.

updateConfig( {Object} config) - updates the gauge config and re-initialize the gauge. Config object allows to pass config changes partially. For example, if you want to change dynamically only with and height of the gauge canvas it can be done as follows: gauge.updateConfig({ width: 300, height: 300 });

draw() - draws the gauge (renders it on specified canvas)

clear() - immediately sets the gauge value to minimal one and re-draws the gauge

setValue( {Float} value) - sets a new value to display within the gauge. If animations is enabled - starts an animation.

getValue() - returns the current value on a gauge

##Events

onready - A good practice is to use this even if it is required to dynamically work with the gauge (change the value) and be assured that the gauge was correctly initialized and drawn before the dynamic updates was started.

Examples:

var Gauge = new Gauge({ renderTo: 'canvas-id' });
// now handle initial gauge draw with onready event
gauge.onready = function() {
	// and do update of gauge value each second with the random value
	setInterval( function() {
		gauge.setValue( Math.random() * 100);
	}, 1000);
};
// draw the gauge
gauge.draw();