Canvas Meter chart API reference

Documentation about the Meter chart including information on all the options available to you. The Meter chart can be used to show a single value and it's quite versatile in it's appearance.

 

Example

<script>
    var meter = 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>

The example pages are here.

 

Properties

You can use these properties to control how the chart apears. 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.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...)

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 demos.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

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

Color properties

PropertyDescriptionDefault
colorsStrokeThe color of the bits separating the segements. By setting this to white you can get a separation effect.null
colorsBorderColorThe color of the outline (including tickmarks).black
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
colorsGreenColorThe 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('colors.ranges', [[0, 60, 'green'],[60, 80 'yellow'],[80, 100, 'red']]),
null
colorsBackgroundThe background color for the Meter. If you have a non-white background you may want to change this.white

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>
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
textColorThe color of the labels.black
textSizeThe size (in points) of the labels.10
textFontThe font used to render the text.Arial
textValignThe vertcal alignment of the text. In some cases you may want to change this to bottomcenter
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[Defaults to the textFont setting]
labelsValueTextSizeThe size (in points) of the text16
labelsValueTextBoldWhether the text is bold or notfalse
labelsValueTextItalicWhether the text is italic or notfalse
labelsValueTextColorThe color of the text[Defaults to the textColor setting]
labelsValueTextBackgroundWhether the text has a background or nottrue
labelsValueTextBackgroundFillThe color of the background of the textrgba(255,255,255,0.75)
labelsValueTextBackgroundStrokeThe stroke color of the backgroundrgba(0,0,0,0)
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 (theres an example of such a chart in the demos Theres also an SVG Gauge chart that can provide two scales.).0

Title properties

PropertyDescriptionDefault
titleThe title of the chart, if any.null
titleFontThe font that the title is rendered in. If not specified the text.font setting is used (usually Arial)null
titleSizeThe size of the title. If not specified the size is usually 2pt bigger than the text.size setting.null
titleBoldWhether the title is bold or not.true
titleItalicWhether the title is italic or not.false
titleColorThe color of the title.black
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

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,

Interactive features properties

PropertyDescriptionDefault
contextmenuAn array of context menu items. More information on context menus is here.[] (An empty array)
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 color 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
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
adjustableDefaulting to false, this determines whether your bar chart will be adjustable.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

Zoom properties

PropertyDescriptionDefault
zoomFactorThis is the factor that the chart will be zoomed by (bigger values means more zoom)1.5
zoomFadeInWhether the zoomed canvas fades in or not. This also can be used to control the fade in for the zoom in thumbnail mode.true
zoomFadeOutWhether the zoomed canvas fades out or not. This also can be used to control the fade in for the zoom in thumbnail mode.true
zoomHdirThe horizontal direction of the zoom. Possible values are: left, center, rightright
zoomVdirThe vertical direction of the zoom. Possible values are: up, center, downdown
zoomDelayThe delay (in milliseconds) between frames.50
zoomFramesThe number of frames in the zoom animation.10
zoomShadowWhether or not the zoomed canvas has a shadow or not.true

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 coloured segments.null
needleTypeThis can be set to normal or pointer. You can an example of the pointer type by going here.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
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 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: one, twonull
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. Centering 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

 

Methods

 

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

 

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

 

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

 

obj.on(event, func)

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 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.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)
    {
        // ...
    }

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