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

<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

PropertyDescriptionDefault
borderThis controls the grey border of the Odometer.true
tickmarksThis controls whether tickmarks are shown. If you're animating the Odometer you'll need to turn this off.false
tickmarksHighlightedThis controls whether the tickmarks are highlighted in red/yellow/green.true
centerxIf required, you can position the Meter chart using this instead of the margins.null
centeryIf required, you can position the Meter chart using this instead of the margins.null
radiusIf 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

PropertyDescriptionDefault
marginLeftThe left margin of the chart, (the margin is where the labels and title are)).25
marginRightThe right margin of the chart, (the margin is where the labels and title are).25
marginTopThe top margin of the chart, (the margin is where the labels and title are).25
marginBottomThe bottom margin of the chart, (the margin is where the labels and title are).25
marginLeft
The left margin of the chart, (the margin is where the labels and title are)).
Default: 25

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

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

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

Color properties

PropertyDescriptionDefault
backgroundColorThe color of the background of the chart.#BEBCB0
borderColor1This is the first color used in the gradient of the outer border of the chart (if enabled).#BEBCB0
borderColor2This is the second/middle color used in the gradient of the outer border of the chart (if enabled).#F0EFEA
borderColor3This is the third color used in the gradient of the outer border of the chart (if enabled).#BEBCB0
colorsGreenColorThis is the color of the green area.green
colorsGreenMaxThis is the point at which the green area ends.75% of the maximum value
colorsRedColorThis is the color of the red area.red
colorsRedMinThis is the point at which the red area starts. The yellow area is between the green and red areas.90% of the maximum value
colorsYellowColorThis 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

PropertyDescriptionDefault
scaleUnitsPreThe 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
scaleUnitsPostThe 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
scaleDecimalsThe number of decimal places to display for the labels.0
scalePointThe character used as the decimal point..
scaleThousandThe 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

PropertyDescriptionDefault
labelsInstead of using computed numbers, which uses the maximum value, you can specify the Odometer to use textual labels instead, with this option.null
labelsValueControls whether the value is indicated as a text label in the center of the dial.false
labelsValueDecimalsThe number of decimals that are used by the valueText label.0
labelsValueUnitsPreThe pre units used on the textual value.An empty string
labelsValueUnitsPostThe post units used on the textual value.An empty string
labelsValueFontThe font used to render the value label.null
labelsValueSizeThe size of the value label.null
labelsValueColorThe color of the value label.null
labelsValueBoldWhether the value label is bold or not.null
labelsValueItalicWhether the value label is italic or not.null
labelsMarginThe width of the area that labels are put in.35
textSizeThe size of the text (in points).12
textFontThe font used to render the text.Arial, Verdana, sans-serif
textColorThe color of the labels.black
textBoldWhether the labels on the chart are bold or not.false
textItalicWhether the labels on the chart are italic or not.false
textAccessibleA 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
textAccessibleOverflowThis 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
textAccessiblePointereventsThis 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

PropertyDescriptionDefault
needleWidthHow thick the needle is.2
needleColorThe color that is applied to the needle.black
needleHeadThis controls whether the arrow head on the end of the needle is displayed.true
needleTypeThis determines which type of needle is used. It can be pointer or triangle.pointer
needleTriangleBorderThis 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
needleExtraWith 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

PropertyDescriptionDefault
titleThe title text.null
titleFontThe font that the title is rendered in. If not specified the textFont setting is used (usually Arial).null
titleSizeThe size of the title. If not specified the size is usually 2pt bigger than the textSize setting.null
titleBoldWhether the title is bold or not.null
titleItalicWhether the title is italic or not.null
titleColorThe color of the title.null
titleBackgroundThe background color (if any) for the title.null
titleXTo 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
titleYTo 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
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

Shadow properties

PropertyDescriptionDefault
shadowInnerWhether a drop shadow is applied to the inner circle of the Odometer.false
shadowInnerColorThe color for the inner shadow.black
shadowInnerOffsetxThe X offset for the inner shadow.3
shadowInnerOffsetyThe Y offset for the inner shadow.3
shadowInnerBlurThe extent of the blurring effect on the shadow.6
shadowOuterWhether a drop shadow is applied to the whole Odometer.false
shadowOuterColorThe color for the outer shadow.black
shadowOuterOffsetxThe X offset for the outer shadow.3
shadowOuterOffsetyThe Y offset for the outer shadow.3
shadowOuterBlurThe 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

PropertyDescriptionDefault
contextmenuAn array of context menu items. More information about context menus is here.An empty array
annotatableWhether annotations are enabled for the chart (ie you can draw on the chart interactively.false
annotatableColorIf you do not allow the use of the palette, then this will be the only color allowed for annotations.black
annotatableLinewidthThis is the linewidth of the annotations.1
adjustableYou 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

PropertyDescriptionDefault
cleartoThis 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
<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>