Odometer chart API reference

Summary: Documentation about the Odometer chart including information about all of the options that are available to you. The Odometer chart is a meter type of chart and can be used to display a single value or quantity.

Example
Properties
Methods
Animation effects

Example

<script>
    new RGraph.Odometer({
        id: 'cvs',
        min: 0,
        max: 100,
        value: 18,
        options: {
            colorsGreenMax: 75,
            colorsRedMin: 90,
            labelsAreaWidth: 50,
            needleThickness: 2
        }
    }).draw();
</script>

Properties

You can use these properties to control how the chart appears. You can set them by including them in the options section of the configuration as is shown above.

Chart configuration properties
Margin properties
Color properties
Scale properties
Labels and text properties
Needle properties
Title properties
Shadow properties
Interactive features properties
Miscellaneous properties

Chart configuration properties

Property	Description	Default
border	This controls the grey border of the Odometer.	true
tickmarks	This controls whether tickmarks are shown. If you're animating the Odometer you'll need to turn this off.	false
tickmarksHighlighted	This controls whether the tickmarks are highlighted in red/yellow/green.	true
centerx	If required, you can position the Meter chart using this instead of the margins.	null
centery	If required, you can position the Meter chart using this instead of the margins.	null
radius	If required, you can size the Meter chart using this instead of the margins.	null

border
This controls the grey border of the Odometer.
Default: true

tickmarks
This controls whether tickmarks are shown. If you're animating the Odometer you'll need to turn this off.
Default: false

tickmarksHighlighted
This controls whether the tickmarks are highlighted in red/yellow/green.
Default: true

centerx
If required, you can position the Meter chart using this instead of the margins.
Default: null

centery
If required, you can position the Meter chart using this instead of the margins.
Default: null

radius
If required, you can size the Meter chart using this instead of the margins.
Default: null

Margin properties

Property	Description	Default
marginLeft	The left margin of the chart, (the margin is where the labels and title are)).	35
marginRight	The right margin of the chart, (the margin is where the labels and title are).	35
marginTop	The top margin of the chart, (the margin is where the labels and title are).	35
marginBottom	The bottom margin of the chart, (the margin is where the labels and title are).	35

marginLeft
The left margin of the chart, (the margin is where the labels and title are)).
Default: 35

marginRight
The right margin of the chart, (the margin is where the labels and title are).
Default: 35

marginTop
The top margin of the chart, (the margin is where the labels and title are).
Default: 35

marginBottom
The bottom margin of the chart, (the margin is where the labels and title are).
Default: 35

Color properties

Property	Description	Default
backgroundColor	The color of the background of the chart.	#BEBCB0
borderColor1	This is the first color used in the gradient of the outer border of the chart (if enabled).	#BEBCB0
borderColor2	This is the second/middle color used in the gradient of the outer border of the chart (if enabled).	#F0EFEA
borderColor3	This is the third color used in the gradient of the outer border of the chart (if enabled).	#BEBCB0
colorsGreenColor	This is the color of the green area.	green
colorsGreenMax	This is the point at which the green area ends.	75% of the maximum value
colorsRedColor	This is the color of the red area.	red
colorsRedMin	This is the point at which the red area starts. The yellow area is between the green and red areas.	90% of the maximum value
colorsYellowColor	This is the color of the yellow area.	yellow

backgroundColor
The color of the background of the chart.
Default: #BEBCB0

borderColor1
This is the first color used in the gradient of the outer border of the chart (if enabled).
Default: #BEBCB0

borderColor2
This is the second/middle color used in the gradient of the outer border of the chart (if enabled).
Default: #F0EFEA

borderColor3
This is the third color used in the gradient of the outer border of the chart (if enabled).
Default: #BEBCB0

colorsGreenColor
This is the color of the green area.
Default: green

colorsGreenMax
This is the point at which the green area ends.
Default: 75% of the maximum value

colorsRedColor
This is the color of the red area.
Default: red

colorsRedMin
This is the point at which the red area starts. The yellow area is between the green and red areas.
Default: 90% of the maximum value

colorsYellowColor
This is the color of the yellow area.
Default: yellow

Scale properties

Property	Description	Default
scaleUnitsPre	The units that the value is measured in. This string is displayed before the actual number, allowing you to specify values such as "$50" and is only used if `valueText` is `true`.	none
scaleUnitsPost	The units that the value is measured in. This string is displayed after the actual number, allowing you to specify values such as "50ms" and is only used if `valueText` is `true`.	none
scaleDecimals	The number of decimal places to display for the labels.	0
scalePoint	The character used as the decimal point.	.
scaleThousand	The character used as the thousand separator.	,

scaleUnitsPre
The units that the value is measured in. This string is displayed before the actual number, allowing you to specify values such as "$50" and is only used if valueText is true.
Default: none

scaleUnitsPost
The units that the value is measured in. This string is displayed after the actual number, allowing you to specify values such as "50ms" and is only used if valueText is true.
Default: none

scaleDecimals
The number of decimal places to display for the labels.
Default: 0

scalePoint
The character used as the decimal point.
Default: .

scaleThousand
The character used as the thousand separator.
Default: ,

Labels and text properties

Property	Description	Default
labels	Instead of using computed numbers, which uses the maximum value, you can specify the Odometer to use textual labels instead, with this option.	null
labelsValue	Controls whether the value is indicated as a text label in the center of the dial.	false
labelsValueDecimals	The number of decimals that are used by the `valueText` label.	0
labelsValueUnitsPre	The pre units used on the textual value.	An empty string
labelsValueUnitsPost	The post units used on the textual value.	An empty string
labelsValueFont	The font used to render the value label.	null
labelsValueSize	The size of the value label.	null
labelsValueColor	The color of the value label.	null
labelsValueBold	Whether the value label is bold or not.	null
labelsValueItalic	Whether the value label is italic or not.	null
labelsMargin	The width of the area that labels are put in.	35
textSize	The size of the text (in points).	12
textFont	The font used to render the text.	Arial, Verdana, sans-serif
textColor	The color of the labels.	black
textBold	Whether the labels on the chart are bold or not.	false
textItalic	Whether the labels on the chart are italic or not.	false
textAccessible	A new feature in 2016 that allows you to use DOM text in place of canvas text. It makes for much higher quality text that you can also select if desired (for copy/paste operations). It won't fit all situations and you can read more about the DOM text feature here. A good way to control borders/margins/padding etc is not to set them on the canvas but to wrap the canvas in a div and set them on that like this: <div style="margin-left: 50px; display: inline-block"> <canvas id="cvs" width="650" height="250"></canvas> </div>	true
textAccessibleOverflow	This can be `visible` or `hidden` and it controls whether the text is clipped to the edges of the canvas. It defaults to be visible and means you can set small margins if you wish.	visible
textAccessiblePointerevents	This controls whether the DOM text responds to mouse based events or not (it sets the `pointer-events` CSS property to `none`).	true

labels
Instead of using computed numbers, which uses the maximum value, you can specify the Odometer to use textual labels instead, with this option.
Default: null

labelsValue
Controls whether the value is indicated as a text label in the center of the dial.
Default: false

labelsValueDecimals
The number of decimals that are used by the valueText label.
Default: 0

labelsValueUnitsPre
The pre units used on the textual value.
Default: An empty string

labelsValueUnitsPost
The post units used on the textual value.
Default: An empty string

labelsValueFont
The font used to render the value label.
Default: null

labelsValueSize
The size of the value label.
Default: null

labelsValueColor
The color of the value label.
Default: null

labelsValueBold
Whether the value label is bold or not.
Default: null

labelsValueItalic
Whether the value label is italic or not.
Default: null

labelsMargin
The width of the area that labels are put in.
Default: 35

textSize
The size of the text (in points).
Default: 12

textFont
The font used to render the text.
Default: Arial, Verdana, sans-serif

textColor
The color of the labels.
Default: black

textBold
Whether the labels on the chart are bold or not.
Default: false

textItalic
Whether the labels on the chart are italic or not.
Default: false

textAccessible
A new feature in 2016 that allows you to use DOM text in place of canvas text. It makes for much higher quality text that you can also select if desired (for copy/paste operations). It won't fit all situations and you can read more about the DOM text feature here. A good way to control borders/margins/padding etc is not to set them on the canvas but to wrap the canvas in a div and set them on that like this:

<div style="margin-left: 50px; display: inline-block">
    <canvas id="cvs" width="650" height="250"></canvas>
</div>

Default: true

textAccessibleOverflow
This can be visible or hidden and it controls whether the text is clipped to the edges of the canvas. It defaults to be visible and means you can set small margins if you wish.
Default: visible

textAccessiblePointerevents
This controls whether the DOM text responds to mouse based events or not (it sets the pointer-events CSS property to none).
Default: true

Needle properties

Property	Description	Default
needleWidth	How thick the needle is.	2
needleColor	The color that is applied to the needle.	black
needleHead	This controls whether the arrow head on the end of the needle is displayed.	true
needleType	This determines which type of needle is used. It can be `pointer` or `triangle`.	pointer
needleTriangleBorder	This controls the color of the border for the pointer. If you don't want it you could set it to be transparent: `rgba(0,0,0,0)`.	#aaa
needleExtra	With this you can specify a number of extra pointers that will be drawn on the Odometer. An example would be a meter that's used to show upload and download data. An example use: obj.set('needleExtra', [[16, 'red'], [24, 'blue']]);	An empty array

needleWidth
How thick the needle is.
Default: 2

needleColor
The color that is applied to the needle.
Default: black

needleHead
This controls whether the arrow head on the end of the needle is displayed.
Default: true

needleType
This determines which type of needle is used. It can be pointer or triangle.
Default: pointer

needleTriangleBorder
This controls the color of the border for the pointer. If you don't want it you could set it to be transparent: rgba(0,0,0,0).
Default: #aaa

needleExtra
With this you can specify a number of extra pointers that will be drawn on the Odometer. An example would be a meter that's used to show upload and download data. An example use:

obj.set('needleExtra', [[16, 'red'], [24, 'blue']]);

Default: An empty array

Title properties

Property	Description	Default
title	The title text.	null
titleFont	The font that the title is rendered in. If not specified the `textFont` setting is used (usually Arial).	null
titleSize	The size of the title. If not specified the size is usually 2pt bigger than the `textSize` setting.	null
titleBold	Whether the title is bold or not.	null
titleItalic	Whether the title is italic or not.	null
titleColor	The color of the title.	null
titleBackground	The background color (if any) for the title.	null
titleX	To give the exact X coordinate for the title - use this. This can also be a string like this: "-5" -- in which case it's converted to a number and added to the calculated coordinate - allowing you to adjust the calculated coordinate.	null
titleY	To give the exact Y coordinate for the title - use this. This can also be a string like this: "-5" -- in which case it's converted to a number and added to the calculated coordinate - allowing you to adjust the calculated coordinate.	null
titleHalign	The horizontal alignment of the title.	center (can change depending on other options)
titleValign	The vertical alignment of the title.	center (can change depending on other options)

title
The title text.
Default: null

titleFont
The font that the title is rendered in. If not specified the textFont setting is used (usually Arial).
Default: null

titleSize
The size of the title. If not specified the size is usually 2pt bigger than the textSize setting.
Default: null

titleBold
Whether the title is bold or not.
Default: null

titleItalic
Whether the title is italic or not.
Default: null

titleColor
The color of the title.
Default: null

titleBackground
The background color (if any) for the title.
Default: null

titleX
To give the exact X coordinate for the title - use this. This can also be a string like this: "-5" -- in which case it's converted to a number and added to the calculated coordinate - allowing you to adjust the calculated coordinate.
Default: null

titleY
To give the exact Y coordinate for the title - use this. This can also be a string like this: "-5" -- in which case it's converted to a number and added to the calculated coordinate - allowing you to adjust the calculated coordinate.
Default: null

titleHalign
The horizontal alignment of the title.
Default: center (can change depending on other options)

titleValign
The vertical alignment of the title.
Default: center (can change depending on other options)

Shadow properties

Property	Description	Default
shadowInner	Whether a drop shadow is applied to the inner circle of the Odometer.	false
shadowInnerColor	The color for the inner shadow.	black
shadowInnerOffsetx	The X offset for the inner shadow.	3
shadowInnerOffsety	The Y offset for the inner shadow.	3
shadowInnerBlur	The extent of the blurring effect on the shadow.	6
shadowOuter	Whether a drop shadow is applied to the whole Odometer.	false
shadowOuterColor	The color for the outer shadow.	black
shadowOuterOffsetx	The X offset for the outer shadow.	3
shadowOuterOffsety	The Y offset for the outer shadow.	3
shadowOuterBlur	The extent of the blurring effect on the shadow.	6

shadowInner
Whether a drop shadow is applied to the inner circle of the Odometer.
Default: false

shadowInnerColor
The color for the inner shadow.
Default: black

shadowInnerOffsetx
The X offset for the inner shadow.
Default: 3

shadowInnerOffsety
The Y offset for the inner shadow.
Default: 3

shadowInnerBlur
The extent of the blurring effect on the shadow.
Default: 6

shadowOuter
Whether a drop shadow is applied to the whole Odometer.
Default: false

shadowOuterColor
The color for the outer shadow.
Default: black

shadowOuterOffsetx
The X offset for the outer shadow.
Default: 3

shadowOuterOffsety
The Y offset for the outer shadow.
Default: 3

shadowOuterBlur
The extent of the blurring effect on the shadow.
Default: 6

Interactive features properties

Property	Description	Default
contextmenu	An array of context menu items. More information about context menus is here.	An empty array
annotatable	Whether annotations are enabled for the chart (ie you can draw on the chart interactively.	false
annotatableColor	If you do not allow the use of the palette, then this will be the only color allowed for annotations.	black
annotatableLinewidth	This is the linewidth of the annotations.	1
adjustable	You can make the Odometer interactively adjustable by setting this to `true`.	false

contextmenu
An array of context menu items. More information about context menus is here.
Default: An empty array

annotatable
Whether annotations are enabled for the chart (ie you can draw on the chart interactively.
Default: false

annotatableColor
If you do not allow the use of the palette, then this will be the only color allowed for annotations.
Default: black

annotatableLinewidth
This is the linewidth of the annotations.
Default: 1

adjustable
You can make the Odometer interactively adjustable by setting this to true.
Default: false

Miscellaneous properties

Property	Description	Default
clearto	This is used in animations and effects as the default color to use when the canvas.	null

clearto
This is used in animations and effects as the default color to use when the canvas.
Default: null

Methods

obj.get(name)
An accessor that you can use to retrieve the values of properties.

obj.set(name, value)
An accessor that you can use to set the values of properties.

obj.getAngle(value)
This method will return you an appropriate angle for the given value.

obj.on(event, function)

This method can be used to set an event listener on an object. It operates in a similar way to the jQuery on() function. The first argument is the event that you wish to attach to and the second is the handler function. For example:

.on('draw', function (obj)
{
    // Put event code here
});

The function is useful if you use method chaining when creating your charts:

var obj = new RGraph.Odometer({
    id: 'cvs',
    min: 0,
    max: 100,
    value: 56
}).on('draw', function (e, shape)
{
    // Put draw event code here
})
.on('click', function (e, shape)
{
    // Handle click event
}).draw();

The exec option and method

The exec function is documented here.

Animation effects

These effects are available and can be used instead of the draw() function. There are also generic effects available which you can see here: Generic effects and transitions

The Grow effect (effects-odo-grow.html in the download archive)

<script>
    window.onload = (function ()
    {
        /**
        * Optional callback function that's called when the effect is complete
        */
        function myCallback (obj)
        {
            // ...
        }
    
        new RGraph.Odometer({
            id: 'cvs',
            min: 0,
            max: 100,
            value: 56,
            options: {
                marginLeft: 35
            }
        }).grow({frames: 60}, myCallback);
    });
</script>