Odometer chart API reference

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.false
tickmarksThis controls whether tick marks are shown. If you're animating the Odometer you'll need to turn this off.true
tickmarksHighlightedThis controls whether the tick marks are highlighted in red/yellow/green.false
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

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

Colour properties

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

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 colour 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 colour 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

Needle properties

PropertyDescriptionDefault
needleWidthHow thick the needle is.2
needleColorThe colour 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 colour 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:
odo.set('needleExtra', [[16, 'red'], [24, 'blue']]);
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.true
titleItalicWhether the title is italic or not.false
titleColorThe colour of the title.black
titleBackgroundThe background colour (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

Shadow properties

PropertyDescriptionDefault
shadowInnerWhether a drop shadow is applied to the inner circle of the Odometer.false
shadowInnerColorThe colour 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 colour 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

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 colour allowed for annotations.black
annotatableLinewidthThis is the line width of the annotations.1
resizableDefaulting to false, this determines whether your chart will be resizable. Because of the numerous event handlers this has to install code on, This feature is unlikely to work with other dynamic features (the context menu is fine however).false
resizableHandleBackgroundWith this you can specify the background colour for the resize handle. If you're adjusting the position of the handle then you may need this to make the handle stand out more.null
resizableMinwidthThis allows you to set a minimum width that the chart can be resized to.null
resizableMinheightThis allows you to set a minimum height that the chart can be resized to.null
resizableMaxwidthThis allows you to set a maximum width that the chart can be resized to.null
resizableMaxheightThis allows you to set a maximum height that the chart can be resized to.null
adjustableYou can make the Odometer interactively adjustable by setting this to true.false

Miscellaneous properties

PropertyDescriptionDefault
cleartoThis is used in animations and effects as the default colour to use when the canvas.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 ondraw 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>