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
- Margin properties
- Color properties
- Scale properties
- Labels and text properties
- Needle properties
- Title properties
- Shadow properties
- Interactive features properties
- Miscellaneous properties
Chart configuration properties
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
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
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
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 |
labelsValuePoint | The character used as the decimal point. | . |
labelsValueThousand | The character used as the thousand separator. | , |
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 |
labelsValueOffsetx | This allows you finer grained control in the horizontal direction over the text positioning if you need it. | 0 |
labelsValueOffsety | This allows you finer grained control in the vertical direction over the text positioning if you need it. | 0 |
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"> | 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 |
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
labelsValuePoint
The character used as the decimal point.
Default: .
labelsValueThousand
The character used as the thousand separator.
Default: ,
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
labelsValueOffsetx
This allows you finer grained control in the horizontal direction over the text positioning if you need it.
Default: 0
labelsValueOffsety
This allows you finer grained control in the vertical direction over the text positioning if you need it.
Default: 0
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
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
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)
titleOffsetx
You can use this property to adjust the positioning of the title in the horizontal direction (positive values adjust the title to the right and negative values adjust it to the left).
Default: 0
titleOffsety
You can use this property to adjust the positioning of the title in the vertical direction (positive values adjust the title downwards and negative values adjust it upwards).
Default: 0
Shadow properties
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 |
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 |
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.
The responsive()
function helps your charts respond to different browser window
sizes and screen resolutions. For example for smaller screens you might want to have angled labels
or show shorter versions of them completely.
The responsive()
function is documented on its own page here.
Animation effects
These effects are available and can be used instead of thedraw()
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>