Meter chart API reference

Summary: Documentation about the Meter chart including information about all of the options that are available to you. The Meter chart can be used to show a single value and is quite versatile in its appearance.

Example

<script>
    new RGraph.Meter({
        id: 'cvs',
        min: 0,
        max: 100,
        value: 6.4,
        options: {
            colorsRanges: [
                [0,10, 'Gradient(white:red)'],
                [10,35, 'Gradient(white:yellow)'],
                [35,100, 'Gradient(white:green)']
            ]
        }
    }).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 above.

Chart configuration properties

PropertyDescriptionDefault
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
anglesStartYou can specify the angle that the Meter should start at with this property. Keep in mind though - that by default the Meter is positioned at the bottom of the canvas. Remember that there are three "constants" available for you to use: RGraph.HALFPI RGraph.HALFPI RGraph.PI RGraph.TWOPIPi (3.14...)
anglesEndYou can specify the angle that the Meter should end at with this property. Keep in mind though - that by default the Meter is positioned at the bottom of the canvas. Remember that there are three "constants" available for you to use: RGraph.HALFPI RGraph.PI RGraph.TWOPI2 * Pi (6.28...)
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

anglesStart
You can specify the angle that the Meter should start at with this property. Keep in mind though - that by default the Meter is positioned at the bottom of the canvas. Remember that there are three "constants" available for you to use: RGraph.HALFPI RGraph.HALFPI RGraph.PI RGraph.TWOPI
Default: Pi (3.14...)

anglesEnd
You can specify the angle that the Meter should end at with this property. Keep in mind though - that by default the Meter is positioned at the bottom of the canvas. Remember that there are three "constants" available for you to use: RGraph.HALFPI RGraph.PI RGraph.TWOPI
Default: 2 * Pi (6.28...)

Background properties

PropertyDescriptionDefault
backgroundImageUrlThe URL of an image that is used as the background for the Meter. If you use a background image you can create some significantly different looking Meters. You can see examples in the download archive.null
backgroundImageOffsetxBy default the image is positioned at [0,0] (the top left of the canvas) - you can use this to move the image left (negative) or right (positive).0
backgroundImageOffsetyBy default the image is positioned at [0,0] (the top left of the canvas) - you can use this to move the image up (negative) or down (positive).0
backgroundImageStretchIf true (the default) then the image will be stretched to fit the canvas width and height (the width and height are the same as the canvas width and height).true
backgroundColorThe background color for the Meter. If you have a non-white background you may want to change this.white
backgroundImageUrl
The URL of an image that is used as the background for the Meter. If you use a background image you can create some significantly different looking Meters. You can see examples in the download archive.
Default: null

backgroundImageOffsetx
By default the image is positioned at [0,0] (the top left of the canvas) - you can use this to move the image left (negative) or right (positive).
Default: 0

backgroundImageOffsety
By default the image is positioned at [0,0] (the top left of the canvas) - you can use this to move the image up (negative) or down (positive).
Default: 0

backgroundImageStretch
If true (the default) then the image will be stretched to fit the canvas width and height (the width and height are the same as the canvas width and height).
Default: true

backgroundColor
The background color for the Meter. If you have a non-white background you may want to change this.
Default: white

Margin properties

PropertyDescriptionDefault
marginLeftThe left margin of the chart.25
marginRightThe right margin of the chart.25
marginTopThe top margin of the chart.25
marginBottomThe bottom margin of the chart.25
marginLeft
The left margin of the chart.
Default: 25

marginRight
The right margin of the chart.
Default: 25

marginTop
The top margin of the chart.
Default: 25

marginBottom
The bottom margin of the chart.
Default: 25

Color properties

PropertyDescriptionDefault
colorsStrokeThe color of the bits separating the segments. By setting this to white you can get a separation effect.null
colorsGreenStartThe value that the green area should begin at.35% of the maximum value
colorsGreenEndThe value that the green area should end at.The maximum value
colorsGreenColorThe color of the green area.#207A20
colorsYellowStartThe value that the yellow area should begin at.10% of the maximum value
colorsYellowEndThe value that the yellow area should end at.35% of the maximum value
colorsYellowColorThe color of the yellow area (can be any color).#D0AC41
colorsRedStartThe value that the red area should begin at.The minimum value
colorsRedEndThe value that the red area should end at.10% of the maximum value
colorsRedColorThe color of the red area (can be any color).#9E1E1E
colorsRangesIf the green/yellow/red colors don't suit your desired Meter you can use this to completely control the color ranges on your chart. An example for a chart with a range of 0-100 would be:
obj.set('colorsRanges', [[0, 60, 'green'],[60, 80, 'yellow'],[80, 100, 'red']]),
null
colorsStroke
The color of the bits separating the segments. By setting this to white you can get a separation effect.
Default: null

colorsGreenStart
The value that the green area should begin at.
Default: 35% of the maximum value

colorsGreenEnd
The value that the green area should end at.
Default: The maximum value

colorsGreenColor
The color of the green area.
Default: #207A20

colorsYellowStart
The value that the yellow area should begin at.
Default: 10% of the maximum value

colorsYellowEnd
The value that the yellow area should end at.
Default: 35% of the maximum value

colorsYellowColor
The color of the yellow area (can be any color).
Default: #D0AC41

colorsRedStart
The value that the red area should begin at.
Default: The minimum value

colorsRedEnd
The value that the red area should end at.
Default: 10% of the maximum value

colorsRedColor
The color of the red area (can be any color).
Default: #9E1E1E

colorsRanges
If the green/yellow/red colors don't suit your desired Meter you can use this to completely control the color ranges on your chart. An example for a chart with a range of 0-100 would be:
obj.set('colorsRanges', [[0, 60, 'green'],[60, 80, 'yellow'],[80, 100, 'red']]),

Default: null

Labels and text properties

PropertyDescriptionDefault
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>
false
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
textColorThe color of the labels.black
textSizeThe size (in points) of the labels.12
textFontThe font used to render the text.Arial, Verdana, sans-serif
textBoldWhether the text on the chart is bold or not.false
textItalicWhether the text on the chart is italic or not.false
textValignThe vertical alignment of the text. In some cases you may want to change this to bottom.center
labelsValueTextThis option controls whether the value of the Meter is shown in text.false
labelsValueTextDecimalsThe amount of decimals shown in the text label.0
labelsValueTextUnitsPreThe units (before the value) shown in the text label.An empty string
labelsValueTextUnitsPostThe units (after the value) shown in the text label.An empty string
labelsValueTextFontThe font that the text is rendered in.null
labelsValueTextSizeThe size (in points) of the text.null
labelsValueTextBoldWhether the text is bold or not.null
labelsValueTextItalicWhether the text is italic or not.null
labelsValueTextColorThe color of the text.null
labelsValueTextBackgroundWhether the text has a background or not.true
labelsValueTextBackgroundFillThe color of the background of the text.rgba(255,255,255,0.75)
labelsValueTextBackgroundStrokeThe stroke color of the background.rgba(0,0,0,0)
labelsValueTextSpecificIf you want to specify the label to display on the Meter you can specify it with this property.null
labelsWhether the labels are shown or not.true
labelsCountThis is used to stipulate how many labels are drawn on the Meter.10
labelsSpecificIf you want to show specific labels on your Meter chart then you can use this property. The format of this array is an array of arrays, which contain the label and the value that that label should be positioned at. For example: [['Low', 10],['Medium', 30],['High',50]]

As of version 4.68 this can now also be an array of either strings or numbers (instead of an array of arrays). If this is the case then the labels are simply spaced equally around the Meter. For example: ['Low','Medium','High']

null
labelsRadiusOffsetThe radius offset that the labels are positioned at. Using this property you can easily make a dual scale Meter chart there's an example of such a chart in the download archive. There's also an SVG Gauge chart that can provide two scales.).0
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: false

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

textColor
The color of the labels.
Default: black

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

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

textBold
Whether the text on the chart is bold or not.
Default: false

textItalic
Whether the text on the chart is italic or not.
Default: false

textValign
The vertical alignment of the text. In some cases you may want to change this to bottom.
Default: center

labelsValueText
This option controls whether the value of the Meter is shown in text.
Default: false

labelsValueTextDecimals
The amount of decimals shown in the text label.
Default: 0

labelsValueTextUnitsPre
The units (before the value) shown in the text label.
Default: An empty string

labelsValueTextUnitsPost
The units (after the value) shown in the text label.
Default: An empty string

labelsValueTextFont
The font that the text is rendered in.
Default: null

labelsValueTextSize
The size (in points) of the text.
Default: null

labelsValueTextBold
Whether the text is bold or not.
Default: null

labelsValueTextItalic
Whether the text is italic or not.
Default: null

labelsValueTextColor
The color of the text.
Default: null

labelsValueTextBackground
Whether the text has a background or not.
Default: true

labelsValueTextBackgroundFill
The color of the background of the text.
Default: rgba(255,255,255,0.75)

labelsValueTextBackgroundStroke
The stroke color of the background.
Default: rgba(0,0,0,0)

labelsValueTextSpecific
If you want to specify the label to display on the Meter you can specify it with this property.
Default: null

labels
Whether the labels are shown or not.
Default: true

labelsCount
This is used to stipulate how many labels are drawn on the Meter.
Default: 10

labelsSpecific
If you want to show specific labels on your Meter chart then you can use this property. The format of this array is an array of arrays, which contain the label and the value that that label should be positioned at. For example: [['Low', 10],['Medium', 30],['High',50]]

As of version 4.68 this can now also be an array of either strings or numbers (instead of an array of arrays). If this is the case then the labels are simply spaced equally around the Meter. For example: ['Low','Medium','High']
Default: null

labelsRadiusOffset
The radius offset that the labels are positioned at. Using this property you can easily make a dual scale Meter chart there's an example of such a chart in the download archive. There's also an SVG Gauge chart that can provide two scales.).
Default: 0

Title properties

PropertyDescriptionDefault
titleThe title of the chart, if any.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 of the chart, if any.
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

Scale properties

PropertyDescriptionDefault
scaleUnitsPreThe units that the labels are measured in. This string is displayed before the actual number, allowing you to specify values such as "$50".none
scaleUnitsPostThe units that the labels are measured in. This string is displayed after the actual number, allowing you to specify values such as "50ms".none
scaleDecimalsThe number of decimal places to display for the values.0
scalePointThe character used as the decimal point..
scaleThousandThe character used as the thousand separator.,
scaleUnitsPre
The units that the labels are measured in. This string is displayed before the actual number, allowing you to specify values such as "$50".
Default: none

scaleUnitsPost
The units that the labels are measured in. This string is displayed after the actual number, allowing you to specify values such as "50ms".
Default: none

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

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

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

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
adjustableDefaulting to false, this determines whether your bar chart will be adjustable.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
Defaulting to false, this determines whether your bar chart will be adjustable.
Default: false

Shadow properties

PropertyDescriptionDefault
shadowWhether a drop shadow is applied.false
shadowColorThe color of the shadow.rgba(0,0,0,0.5)
shadowOffsetxThe X offset of the shadow.3
shadowOffsetyThe Y offset of the shadow.3
shadowBlurThe severity of the shadow blurring effect.3
shadow
Whether a drop shadow is applied.
Default: false

shadowColor
The color of the shadow.
Default: rgba(0,0,0,0.5)

shadowOffsetx
The X offset of the shadow.
Default: 3

shadowOffsety
The Y offset of the shadow.
Default: 3

shadowBlur
The severity of the shadow blurring effect.
Default: 3

Miscellaneous properties

PropertyDescriptionDefault
linewidthThe width of the outline of the Meter.2
linewidthSegmentsThe linewidth of the lines separating the segments.1
tickmarksSmallCountThis controls the number of small tickmarks.100
tickmarksLargeCountThis controls the number of large tickmarks.10
tickmarksSmallColorThis sets the color of the small tickmarks.#bbb
tickmarksLargeColorThis sets the color of the large tickmarks.black
borderWhether the outline is drawn.true
segmentsRadiusStartInstead of the segments going from the center point outwards, you can use this to specify a start point of the colored segments.null
needleTypeThis can be set to normal or pointer. You can see an example of the pointer type in the demos.normal
needleRadiusThis can be used to stipulate the radius of the pointer.null
needleLinewidthThis can be used to specify the linewidth used when drawing the needle.null
needleTailIf true the needle will have a small tail.false
needleHeadThis can be used to disable the drawing of the arrowhead on the pointer.true
needleHeadWidthThe width of the needle head. Keep in mind that this is measured in radians and not pixels.0.088
needleHeadLengthThe length of the needle head. Keep in mind that if you set this too high the line beneath the pointer may show through.30
needleColorThe color of the needle. You'll probably also want the centerpin properties too.black
needleImageUrlIf you want to use an image for the needle then you can do so using this property. Combined with the background image this can make some significantly different looking Meters. The needle should be pointing right (like this, or like this) Two examples of using the image properties are in the download archive.null
needleImageOffsetxNeedle images are drawn so that the top left of the needle image is the centerx/centery of the Meter chart (when the needle is horizontal and pointing to the right). You'll probably want to center your needle image and you can do so with these properties. Centring is best done when the needle is pointing right. So if you haven't changed the angles this will be when the Meters value is the maximum value. If you have changed the angles then you'll have to pick a suitable value so the needle is pointing right.0
needleImageOffsetyAs above but for the needles Y positioning.0
centerpinStrokeThe color of the stroke around the centerpin of the needle.black
centerpinFillThe color of the stroke around the centerpin of the needle.black
cleartoThis is used in animations and effects as the default color to use when the canvas.null
linewidth
The width of the outline of the Meter.
Default: 2

linewidthSegments
The linewidth of the lines separating the segments.
Default: 1

tickmarksSmallCount
This controls the number of small tickmarks.
Default: 100

tickmarksLargeCount
This controls the number of large tickmarks.
Default: 10

tickmarksSmallColor
This sets the color of the small tickmarks.
Default: #bbb

tickmarksLargeColor
This sets the color of the large tickmarks.
Default: black

border
Whether the outline is drawn.
Default: true

segmentsRadiusStart
Instead of the segments going from the center point outwards, you can use this to specify a start point of the colored segments.
Default: null

needleType
This can be set to normal or pointer. You can see an example of the pointer type in the demos.
Default: normal

needleRadius
This can be used to stipulate the radius of the pointer.
Default: null

needleLinewidth
This can be used to specify the linewidth used when drawing the needle.
Default: null

needleTail
If true the needle will have a small tail.
Default: false

needleHead
This can be used to disable the drawing of the arrowhead on the pointer.
Default: true

needleHeadWidth
The width of the needle head. Keep in mind that this is measured in radians and not pixels.
Default: 0.088

needleHeadLength
The length of the needle head. Keep in mind that if you set this too high the line beneath the pointer may show through.
Default: 30

needleColor
The color of the needle. You'll probably also want the centerpin properties too.
Default: black

needleImageUrl
If you want to use an image for the needle then you can do so using this property. Combined with the background image this can make some significantly different looking Meters. The needle should be pointing right (like this, or like this) Two examples of using the image properties are in the download archive.
Default: null

needleImageOffsetx
Needle images are drawn so that the top left of the needle image is the centerx/centery of the Meter chart (when the needle is horizontal and pointing to the right). You'll probably want to center your needle image and you can do so with these properties. Centring is best done when the needle is pointing right. So if you haven't changed the angles this will be when the Meters value is the maximum value. If you have changed the angles then you'll have to pick a suitable value so the needle is pointing right.
Default: 0

needleImageOffsety
As above but for the needles Y positioning.
Default: 0

centerpinStroke
The color of the stroke around the centerpin of the needle.
Default: black

centerpinFill
The color of the stroke around the centerpin of the needle.
Default: black

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:

obj = new RGraph.Meter({
    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.

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>
    /**
    * Optional callback function that's called when the effect is complete
    */
    function myCallback (obj)
    {
        // ...
    }

    new RGraph.Meter({
        id: 'cvs',
        min: 0,
        max: 100,
        value: 56,
        options: {
            marginLeft: 35
        }
    }).grow({frames: 60}, myCallback);
</script>