Meter chart
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 shown above.
- Chart configuration properties
- Background properties
- Margin properties
- Color properties
- Labels and text properties
- Title properties
- Scale properties
- Interactive features properties
- Shadow properties
- Miscellaneous properties
Chart configuration properties
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 chart
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.TWOPI
Default: Pi (3.14...)
anglesEnd
You can specify the angle that the
Meter chart
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
Property | Description | Default |
---|---|---|
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. | 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). | 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). | 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 ). | true |
backgroundColor | The background color for the Meter. If you have a non-white background you may want to change this. | white |
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
Property | Description | Default |
---|---|---|
marginLeft | The left margin of the chart. | 35 |
marginRight | The right margin of the chart. | 35 |
marginTop | The top margin of the chart. | 35 |
marginBottom | The bottom margin of the chart. | 35 |
The left margin of the chart.
Default: 35
marginRight
The right margin of the chart.
Default: 35
marginTop
The top margin of the chart.
Default: 35
marginBottom
The bottom margin of the chart.
Default: 35
Color properties
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
Property | Description | Default |
---|---|---|
textAccessible | A new feature in 2016 that allows you to use dom text in place of canvas text. It makes for a 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 |
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 |
textColor | The color of the labels. | black |
textSize | The size (in points) of the labels. | 12 |
textFont | The font used to render the text. | Arial, Verdana, sans-serif |
textBold | Whether the text on the chart is bold or not. | false |
textItalic | Whether the text on the chart is italic or not. | false |
textValign | The vertical alignment of the text. In some cases, you may want to change this to bottom . | center |
labelsValue | This option controls whether the value of the Meter is shown in text. | false |
labelsValueDecimals | The number of decimals shown in the text label. | 0 |
labelsValueUnitsPre | The units (before the value) shown in the text label. | An empty string |
labelsValueUnitsPost | The units (after the value) shown in the text label. | An empty string |
labelsValuePoint | The character(s) used as the decimal point. | . |
labelsValueThousand | The character(s) used as the thousand separator. | , |
labelsValueFont | The font that the text is rendered in. | null |
labelsValueSize | The size (in points) of the text. | null |
labelsValueBold | Whether the text is bold or not. | null |
labelsValueItalic | Whether the text is italic or not. | null |
labelsValueColor | The color of the text. | null |
labelsValueBackground | Whether the text has a background or not. | true |
labelsValueBackgroundFill | The color of the background of the text. | rgba(255,255,255,0.75) |
labelsValueBackgroundStroke | The stroke color of the background. | rgba(0,0,0,0) |
labelsValueSpecific | If you want to specify the label to display on the Meter you can specify it with this property. | 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 |
labels | Whether the labels are shown or not. | true |
labelsCount | This is used to stipulate how many labels are drawn on the Meter. | 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'] | null |
labelsOffsetRadius | 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.). | 0 |
text | This allows you to add custom text to your chart if you want to. There's a dedicated page that describes this option here. | null |
A new feature in 2016 that allows you to use
dom
text in place of canvas
text. It makes for a 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
labelsValue
This option controls whether the value of the Meter is shown in text.
Default: false
labelsValueDecimals
The number of decimals shown in the text label.
Default: 0
labelsValueUnitsPre
The units (before the value) shown in the text label.
Default: An empty string
labelsValueUnitsPost
The units (after the value) shown in the text label.
Default: An empty string
labelsValuePoint
The character(s) used as the decimal point.
Default: .
labelsValueThousand
The character(s) used as the thousand separator.
Default: ,
labelsValueFont
The font that the text is rendered in.
Default: null
labelsValueSize
The size (in points) of the text.
Default: null
labelsValueBold
Whether the text is bold or not.
Default: null
labelsValueItalic
Whether the text is italic or not.
Default: null
labelsValueColor
The color of the text.
Default: null
labelsValueBackground
Whether the text has a background or not.
Default: true
labelsValueBackgroundFill
The color of the background of the text.
Default: rgba(255,255,255,0.75)
labelsValueBackgroundStroke
The stroke color of the background.
Default: rgba(0,0,0,0)
labelsValueSpecific
If you want to specify the label to display on the Meter you can specify it with this property.
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
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
labelsOffsetRadius
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
text
This allows you to add custom text to your chart if you want to. There's a dedicated page that describes this option here.
Default: null
Title properties
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
4pt
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
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
titleSubtitle
The subtitle of the chart. If a subtitle is specified the title is moved up to accommodate it. As such you might need to give a larger
marginTop
value.Default: null
titleSubtitleSize
The size of the font used to render the subtitle.
Default: null
titleSubtitleColor
The color of the subtitle.
Default: #aaa
titleSubtitleFont
The font used to render the subtitle.
Default: null
titleSubtitleBold
Whether the subtitle is bold or not.
Default: null
titleSubtitleItalic
Whether the subtitle is italic or not.
Default: null
titleSubtitleOffsetx
Use this property to adjust the horizontal position of the subtitle.
Default: 0
titleSubtitleOffsety
Use this property to adjust the vertical position of the subtitle.
Default: 0
Scale properties
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 that's used as the decimal point.
Default: .
scaleThousand
The character that's used as the thousand separator.
Default: ,
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 | Defaulting to false, this determines whether your Meter chart will be adjustable. | 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
Defaulting to false, this determines whether your
Meter chart
will be adjustable.Default: false
Shadow properties
Whether a drop shadow is applied.
Default: false
shadowColor
The color of the shadow.
Default: rgba(0,0,0,0.5)
shadowOffsetx
The horizontal offset of the shadow.
Default: 3
shadowOffsety
The vertical offset of the shadow.
Default: 3
shadowBlur
The severity of the shadow blurring effect.
Default: 3
Miscellaneous properties
Property | Description | Default |
---|---|---|
linewidth | The width of the outline of the Meter. | 2 |
linewidthSegments | The linewidth of the lines separating the segments. | 1 |
tickmarksSmallCount | This controls the number of small tickmarks. | 100 |
tickmarksLargeCount | This controls the number of large tickmarks. | 10 |
tickmarksSmallColor | This sets the color of the small tickmarks. | #bbb |
tickmarksLargeColor | This sets the color of the large tickmarks. | black |
border | Whether the outline is drawn. | 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. | null |
needleType | This can be set to normal or pointer . You can see an example of the pointer type in the demos. | normal |
needleRadius | This can be used to stipulate the radius of the pointer. | null |
needleLinewidth | This can be used to specify the linewidth used when drawing the needle. | null |
needleTail | If true the needle will have a small tail. | false |
needleHead | This can be used to disable the drawing of the arrowhead on the pointer. | true |
needleHeadWidth | The width of the needle head. Keep in mind that this is measured in radians and not pixels. | 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. | 30 |
needleColor | The color of the needle. You'll probably also want the centerpin properties too. | 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. | 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. 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 |
needleImageOffsety | As above but for the needles Y positioning. | 0 |
centerpinStroke | The color of the stroke around the centerpin of the needle. | black |
centerpinFill | The color of the stroke around the centerpin of the needle. | black |
clearto | This is used in animations and effects as the default color to use when the canvas . | null |
responsive | This option is new to the July 2023 release (v6.13) and allows you to inline the responsive configuration instead of appending it on to the end of the object it as a function. The documentation and demo pages have been updated to use this new option. You can read more about the responsive feature by reading the responsive configuration page. | null |
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. 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.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
responsive
This option is new to the July 2023 release (v6.13) and allows you to inline the responsive configuration instead of appending it on to the end of the object it as a function. The documentation and demo pages have been updated to use this new option. You can read more about the responsive feature by reading the responsive configuration page.
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 similarly 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, options: { } }).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.
obj.responsive(configuration)
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.
Update: There is now the responsive configuration option available to you and this is now the preferred method of configuration.
The responsive function and configuration option are documented on their own page here.
Events
RGraph supports custom events that allow you to easily add interactivity to your charts if required. The following events are available:
adjustbegin
This event fires at the start of adjusting - like the standardmousedown
event.adjust
This event fires (repeatedly) during adjusting - like the standardmousemove
event.adjustend
This event fires at the end of adjusting - like the standardmouseup
event.annotatebegin
This event fires at the start of annotating - like the standardmousedown
event.annotate
This event fires (repeatedly) during annotating - like the standardmousemove
event.annotateend
This event fires at the end of annotating - like the standardmouseup
event.annotateclear
This event fires at the end of theRGraph.clearAnnotations
function.beforeclear
This event fires at the start of theRGraph.clear
function.clear
This event fires at the end of theRGraph.clear
function.beforecontextmenu
This event fires when you have the contextmenu enabled and it is about to appear.contextmenu
This event fires when you have the contextmenu enabled and it has been displayed.beforedraw
This event fires at the start of thedraw
method before anything has been done.firstdraw
This event fires at the end of thedraw
function - but only the first time that thedraw
function is called.draw
This event fires at the end of thedraw
function.
new RGraph.Meter({ id: 'cvs', min: 0, max: 100, value: 56, options: { } }).on('draw', function (obj) { console.log('The draw event has fired'); }).draw();
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-meter-grow.html
in the download archive)
<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>