SVG Activity meter API reference

Documentation about the SVG Activity meter API reference including information about all of the options and methods that are available to you.

Example

The code below produces a chart like this:

<script>
    new RGraph.SVG.Activity({
        id: 'chart-container',
        min: 0,
        max: 100,
        value: [24,32,45],
        options: {
            names: ['Richard','John','Frank'],
            width: 40,
            tooltips: '%{property:names[%{index}]}: %{value}%',
            tooltipsCss: {
                fontSize: '20pt'
            }
        }
    }).grow();
</script>

Properties

You can use these properties to control how the meter appears. You can set them by including them in the options section of the configuration as is shown above.

Chart configuration properties

PropertyDescriptionDefault
centerxIf required, you can position the meter using this instead of the margins.null
centeryIf required, you can position the meter using this instead of the margins.null
radiusIf required, you can size the meter using this instead of the margins.null
widthThe width of each bar on the meter.null
endsThis determines whether the bars on the chart have rounded or straight edges. The possible values for the property are round or straightround
centerx
If required, you can position the meter using this instead of the margins.
Default: null

centery
If required, you can position the meter using this instead of the margins.
Default: null

radius
If required, you can size the meter using this instead of the margins.
Default: null

width
The width of each bar on the meter.
Default: null

ends
This determines whether the bars on the chart have rounded or straight edges. The possible values for the property are round or straight
Default: round

Margin properties

PropertyDescriptionDefault
marginLeftThe left margin of the chart.15
marginRightThe right margin of the chart.15
marginTopThe top margin of the chart.15
marginBottomThe bottom margin of the chart.15
marginInnerThe margin in between the circular bars on the chart.1
marginLeft
The left margin of the chart.
Default: 15

marginRight
The right margin of the chart.
Default: 15

marginTop
The top margin of the chart.
Default: 15

marginBottom
The bottom margin of the chart.
Default: 15

marginInner
The margin in between the circular bars on the chart.
Default: 1

Background properties

PropertyDescriptionDefault
backgroundGridWhether the background grid is drawn or not.false
backgroundGridColorIf it's enabled then the background grid will be drawn in this color.#ddd
backgroundGridRadialsWhether the straight lines that emanate from the center outwards are drawn or not.true
backgroundGridRadialsCountHow many of the background grid radial lines there are.8
backgroundGrid
Whether the background grid is drawn or not.
Default: false

backgroundGridColor
If it's enabled then the background grid will be drawn in this color.
Default: #ddd

backgroundGridRadials
Whether the straight lines that emanate from the center outwards are drawn or not.
Default: true

backgroundGridRadialsCount
How many of the background grid radial lines there are.
Default: 8

Color properties

PropertyDescriptionDefault
colorsThe colors to be used for the meter.['#F45B5B', '#90EE7E', '#2B908F', 'red', 'green', 'blue', 'yellow', 'pink']
backgroundColorThe color of the background.black
colors
The colors to be used for the meter.
Default: ['#F45B5B', '#90EE7E', '#2B908F', 'red', 'green', 'blue', 'yellow', 'pink']

backgroundColor
The color of the background.
Default: black

Labels and text properties

PropertyDescriptionDefault
textFontThe font used to render the text.Arial, Verdana, sans-serif
textSizeThe size of the text.12
textColorThe color of the labels.#aaa
textItalicWhether the labels are italic or not.false
textBoldWhether the labels are bold or not.false
labelsCenterWhether to show the center label.false
labelsCenterIndexIf you have multiple values being shown on your meter this is the index of the value which will be shown as the center label.0
labelsCenterFontThe font used to render the center label.null
labelsCenterSizeThe size of the center label.40
labelsCenterColorThe color of the center label.null
labelsCenterItalicWhether the center label is italic or not.null
labelsCenterBoldWhether the center label is bold or not.null
labelsCenterUnitsPreUnits that are prepended to the center label.[an empty string]
labelsCenterUnitsPostUnits that are appended to the center label.[an empty string]
labelsCenterPointThe character used as the decimal point for the center label..
labelsCenterThousandThe character used as the thousand separator for the center label.,
labelsCenterDecimalsThe number of decimals to apply to the center label.0
labelsCenterSpecificThe specific text to use as the center label.null
labelsCenterHalignThe horizontal alignment of the center label.center
labelsCenterValignThe vertical alignment of the center label.center
labelsCenterOffsetxAn offset to add to the horizontal position of the center label. 0
labelsCenterOffsetyAn offset to add to the vertical position of the center label. 0
labelsAn array of labels to use on the chart.[] (an empty array)
labelsColorThe color of the labels.null
labelsFontThe font that's used to render the labels.null
labelsSizeThe size of the labels.null
labelsBoldWhether the labels are bold or not.null
labelsItalicWhether the labels are italic or not.null
labelsBackgroundFillThe color used as the background fill color of the labels.transparent
labelsBackgroundStrokeThe color used as the background stroke color of the labels.transparent
labelsHalignThe horizontal alignment of the chart.right
labelsValignThe vertical alignment of the chart.center
labelsOffsetxA horizontal offset for the labels.0
labelsOffsetyA vertical offset for the labels.0
labelsFormattedDecimalsWhen using formatted labels this is the number of decimals that are applied to the %{value_formatted} macro. 0
labelsFormattedPointWhen using formatted labels this is the decimal point character that's used with the %{value_formatted} macro..
labelsFormattedThousandWhen using formatted labels this is the thousand separator character that's used with the %{value_formatted} macro.,
labelsFormattedUnitsPreWhen using formatted labels these are the units that are prepended to the number with the %{value_formatted} macro.(an empty string)
labelsFormattedUnitsPostWhen using formatted labels this are the units that are appended to the number with the %{value_formatted} macro.(an empty string)
textFont
The font used to render the text.
Default: Arial, Verdana, sans-serif

textSize
The size of the text.
Default: 12

textColor
The color of the labels.
Default: #aaa

textItalic
Whether the labels are italic or not.
Default: false

textBold
Whether the labels are bold or not.
Default: false

labelsCenter
Whether to show the center label.
Default: false

labelsCenterIndex
If you have multiple values being shown on your meter this is the index of the value which will be shown as the center label.
Default: 0

labelsCenterFont
The font used to render the center label.
Default: null

labelsCenterSize
The size of the center label.
Default: 40

labelsCenterColor
The color of the center label.
Default: null

labelsCenterItalic
Whether the center label is italic or not.
Default: null

labelsCenterBold
Whether the center label is bold or not.
Default: null

labelsCenterUnitsPre
Units that are prepended to the center label.
Default: [an empty string]

labelsCenterUnitsPost
Units that are appended to the center label.
Default: [an empty string]

labelsCenterPoint
The character used as the decimal point for the center label.
Default: .

labelsCenterThousand
The character used as the thousand separator for the center label.
Default: ,

labelsCenterDecimals
The number of decimals to apply to the center label.
Default: 0

labelsCenterSpecific
The specific text to use as the center label.
Default: null

labelsCenterHalign
The horizontal alignment of the center label.
Default: center

labelsCenterValign
The vertical alignment of the center label.
Default: center

labelsCenterOffsetx
An offset to add to the horizontal position of the center label.
Default: 0

labelsCenterOffsety
An offset to add to the vertical position of the center label.
Default: 0

labels
An array of labels to use on the chart.
Default: [] (an empty array)

labelsColor
The color of the labels.
Default: null

labelsFont
The font that's used to render the labels.
Default: null

labelsSize
The size of the labels.
Default: null

labelsBold
Whether the labels are bold or not.
Default: null

labelsItalic
Whether the labels are italic or not.
Default: null

labelsBackgroundFill
The color used as the background fill color of the labels.
Default: transparent

labelsBackgroundStroke
The color used as the background stroke color of the labels.
Default: transparent

labelsHalign
The horizontal alignment of the chart.
Default: right

labelsValign
The vertical alignment of the chart.
Default: center

labelsOffsetx
A horizontal offset for the labels.
Default: 0

labelsOffsety
A vertical offset for the labels.
Default: 0

labelsFormattedDecimals
When using formatted labels this is the number of decimals that are applied to the %{value_formatted} macro.
Default: 0

labelsFormattedPoint
When using formatted labels this is the decimal point character that's used with the %{value_formatted} macro.
Default: .

labelsFormattedThousand
When using formatted labels this is the thousand separator character that's used with the %{value_formatted} macro.
Default: ,

labelsFormattedUnitsPre
When using formatted labels these are the units that are prepended to the number with the %{value_formatted} macro.
Default: (an empty string)

labelsFormattedUnitsPost
When using formatted labels this are the units that are appended to the number with the %{value_formatted} macro.
Default: (an empty string)

Tooltips properties

PropertyDescriptionDefault
tooltipsAn array of tooltips for the chart. You can also check the canvas tooltips documentation for more information.null
tooltipsOverrideIf required this can be a function that totally handles the tooltip showing instead of the default RGraph tooltips. It should look like this:
tooltipsOverride: function (obj, opt)
{
    // Show tooltip
}
The opt is an argument that contains these items:
  • object The chart object.
  • index The index of the element (that triggered the tooltip).
  • sequentialIndex The sequential index of the element that was clicked.
  • text The text to be used as the tooltip. Remember that this may contain HTML (or whatever else you may have specified).
  • event The event object (either a click or mousemove event).
null
tooltipsEventThe event used for tooltips (either click or mousemove.click
tooltipsFormattedPointWhen using formatted tooltip strings this is used as the point when using the %{value_formatted} option..
tooltipsFormattedThousandWhen using formatted tooltip strings this is used as the thousand separator when using the %{value_formatted} option.,
tooltipsFormattedDecimalsWhen using formatted tooltip strings this specifies the number of decimals when using the %{value_formatted} option.0
tooltipsFormattedUnitsPreWhen using formatted tooltip strings these units are prepended to the number when using the %{value_formatted} option.(an empty string)
tooltipsFormattedUnitsPostWhen using formatted tooltip strings these units are appended to the number when using the %{value_formatted} option.(an empty string)
tooltipsFormattedKeyLabelsThe labels that are used in the formatted tooltip key.[] (an empty array)
tooltipsFormattedKeyColorsThe colors that are used in the formatted tooltip key. Normally these are automatically taken from the colors on the chart, but can be specified differently using this property.null
tooltipsFormattedKeyColorsShapeThis is the shape that's used in the tooltip key. It can be square or circlesquare
tooltipsFormattedKeyColorsCss By using this property you can add CSS values to the key color shape that appears in the tooltip key. Note the property name is "color" and not "colors" like previous properties. It should be an object of CSS properties like this:
tooltipsFormattedKeyColorsCss : {
    border: "1px solid #ddd";
}
null
tooltipsFormattedListTypeWith this property you can switch between an unordered list (the default) and an ordered list. Possible values are ul and ol.ul
tooltipsFormattedListItemsThis should be a two-dimension array of the list items that are to be shown for all of the tooltips. An example of this property is:
tooltipsFormattedListItems: [
    ['Bill','Jerry','Berty'], // First tooltip
    ['Gill','Carrie','Lucy'], // Second tooltip
    ['Pob','Nobby','Hilda']   // Third tooltip
]
You can use CSS to style this list - for example:
.RGraph_tooltip ul#rgraph_formatted_tooltips_list li {
    text-align: left;
    color: yellow;
}
null
tooltipsFormattedTableHeadersWhen showing a table in the tooltips this can be an array of headers for the table. These are added to the tooltip using <th> tags.null
tooltipsFormattedTableDataThis is the data that is added to the table. This is a 3-dimensional array so it's easy to make a mistake. See the example in the canvas documentation, copy the code from it and then modify it suit. You'll create fewer bugs this way.null)
tooltipsPointerBy default the tooltips have a small triangular pointer that points to the shape that was clicked on. You can turn this off with this property.true
tooltipsPointerCssIf you want any CSS values applied to the tooltips pointer (for example a CSS border) then specify an object containing those values to this property. For example:
tooltips: {
    borderLeft: 'gray 2px solid',
    borderBottom: 'gray 2px solid'
}
null
tooltipsPositionStaticThe new default (as of August 2020) is for tooltips to be positioned statically and not be dependent on the mouse position. If you don't want this for whatever reason, you can disable it with this setting. When you set it to false tooltips are positioned next to the mouse pointer.true
tooltipsCssIf you want to specify some CSS that gets applied to all of the tooltips, but don't want to use the RGraph.SVG.tooltips.style object (which gets applied to all of the tooltips on the page for every chart) you can use this property to give some per-object CSS for the tooltips. These are CSS styles that get applied to all of the tooltips for the specific object only. It should look like this:
tooltipsCss: {
    fontFamily: 'Verdana',
    fontSize: '20pt'
}
null
tooltipsCssClassThe CSS class that's applied to the tooltip DIV.RGraph_tooltip
tooltipsOffsetxThis property allows you to shift the tooltips left or right.0
tooltipsOffsetyThis property allows you to shift the tooltips up or down.0
highlightStrokeThe stroke color that's used when highlighting the chart.rgba(0,0,0,0)
highlightFillThe fill color that's used when highlighting the chart.rgba(255,255,255,0.7)
highlightLinewidthThe linewidth that's used when highlighting the chart.1
tooltips
An array of tooltips for the chart. You can also check the canvas tooltips documentation for more information.
Default: null

tooltipsOverride
If required this can be a function that totally handles the tooltip showing instead of the default RGraph tooltips. It should look like this:
tooltipsOverride: function (obj, opt)
{
    // Show tooltip
}
The opt is an argument that contains these items:
Default: null

tooltipsEvent
The event used for tooltips (either click or mousemove.
Default: click

tooltipsFormattedPoint
When using formatted tooltip strings this is used as the point when using the %{value_formatted} option.
Default: .

tooltipsFormattedThousand
When using formatted tooltip strings this is used as the thousand separator when using the %{value_formatted} option.
Default: ,

tooltipsFormattedDecimals
When using formatted tooltip strings this specifies the number of decimals when using the %{value_formatted} option.
Default: 0

tooltipsFormattedUnitsPre
When using formatted tooltip strings these units are prepended to the number when using the %{value_formatted} option.
Default: (an empty string)

tooltipsFormattedUnitsPost
When using formatted tooltip strings these units are appended to the number when using the %{value_formatted} option.
Default: (an empty string)

tooltipsFormattedKeyLabels
The labels that are used in the formatted tooltip key.
Default: [] (an empty array)

tooltipsFormattedKeyColors
The colors that are used in the formatted tooltip key. Normally these are automatically taken from the colors on the chart, but can be specified differently using this property.
Default: null

tooltipsFormattedKeyColorsShape
This is the shape that's used in the tooltip key. It can be square or circle
Default: square

tooltipsFormattedKeyColorsCss
By using this property you can add CSS values to the key color shape that appears in the tooltip key. Note the property name is "color" and not "colors" like previous properties. It should be an object of CSS properties like this:
tooltipsFormattedKeyColorsCss : {
    border: "1px solid #ddd";
}

Default: null

tooltipsFormattedListType
With this property you can switch between an unordered list (the default) and an ordered list. Possible values are ul and ol.
Default: ul

tooltipsFormattedListItems
This should be a two-dimension array of the list items that are to be shown for all of the tooltips. An example of this property is:
tooltipsFormattedListItems: [
    ['Bill','Jerry','Berty'], // First tooltip
    ['Gill','Carrie','Lucy'], // Second tooltip
    ['Pob','Nobby','Hilda']   // Third tooltip
]
You can use CSS to style this list - for example:
.RGraph_tooltip ul#rgraph_formatted_tooltips_list li {
    text-align: left;
    color: yellow;
}

Default: null

tooltipsFormattedTableHeaders
When showing a table in the tooltips this can be an array of headers for the table. These are added to the tooltip using <th> tags.
Default: null

tooltipsFormattedTableData
This is the data that is added to the table. This is a 3-dimensional array so it's easy to make a mistake. See the example in the canvas documentation, copy the code from it and then modify it suit. You'll create fewer bugs this way.
Default: null)

tooltipsPointer
By default the tooltips have a small triangular pointer that points to the shape that was clicked on. You can turn this off with this property.
Default: true

tooltipsPointerCss
If you want any CSS values applied to the tooltips pointer (for example a CSS border) then specify an object containing those values to this property. For example:
tooltips: {
    borderLeft: 'gray 2px solid',
    borderBottom: 'gray 2px solid'
}

Default: null

tooltipsPositionStatic
The new default (as of August 2020) is for tooltips to be positioned statically and not be dependent on the mouse position. If you don't want this for whatever reason, you can disable it with this setting. When you set it to false tooltips are positioned next to the mouse pointer.
Default: true

tooltipsCss
If you want to specify some CSS that gets applied to all of the tooltips, but don't want to use the RGraph.SVG.tooltips.style object (which gets applied to all of the tooltips on the page for every chart) you can use this property to give some per-object CSS for the tooltips. These are CSS styles that get applied to all of the tooltips for the specific object only. It should look like this:
tooltipsCss: {
    fontFamily: 'Verdana',
    fontSize: '20pt'
}

Default: null

tooltipsCssClass
The CSS class that's applied to the tooltip DIV.
Default: RGraph_tooltip

tooltipsOffsetx
This property allows you to shift the tooltips left or right.
Default: 0

tooltipsOffsety
This property allows you to shift the tooltips up or down.
Default: 0

highlightStroke
The stroke color that's used when highlighting the chart.
Default: rgba(0,0,0,0)

highlightFill
The fill color that's used when highlighting the chart.
Default: rgba(255,255,255,0.7)

highlightLinewidth
The linewidth that's used when highlighting the chart.
Default: 1

Other properties

PropertyDescriptionDefault
adjustableIf true then the meter will be adjustable. Click on the meter to alter the values of the bars.false
iconsThis should be an array of file paths of images that appear at the start of the bars.null
iconsWidthIf you want you can specify the width of the image with this property.null
iconsHeightIf you want you can specify the height of the image with this property.null
iconsOffsetxWith this property you can adjust the image position in the horizontal direction.0
iconsOffsetyWith this property you can adjust the image position in the vertical direction.0
adjustable
If true then the meter will be adjustable. Click on the meter to alter the values of the bars.
Default: false

icons
This should be an array of file paths of images that appear at the start of the bars.
Default: null

iconsWidth
If you want you can specify the width of the image with this property.
Default: null

iconsHeight
If you want you can specify the height of the image with this property.
Default: null

iconsOffsetx
With this property you can adjust the image position in the horizontal direction.
Default: 0

iconsOffsety
With this property you can adjust the image position in the vertical direction.
Default: 0

Methods

obj.get(name)

This can be used to get properties if necessary. It's normally used after the chart is drawn if you need to get parameters (if you're doing custom coding for example).

obj.set(name, value)

This can be used to set properties if necessary. It's normally used after the chart is drawn if you need to set additional parameters or change them.

obj.on(event, handler)

This function adds an event listener (such as beforedraw draw or tooltip) to the chart object. For example:

obj.on('draw', function (obj)
{
    // Put your code here
});
obj.exec(func)

This function can be used to execute a function (immediately). It's not event based (ie it doesn't run when something happens) - it just runs immediately - and only once. You might use it when you need to get something from the chart when it's drawn and then call the redraw function. Because this function only runs once the RGraph.SVG.redraw() function would not cause a loop - which would happen if you used the draw event.

obj.exec(function (obj)
{
    // Put your code 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.

The responsive() function is documented on its own page here in the canvas section of the website (though the information applies equally to SVG charts).

obj.getAngle(event or value)

When you click on the chart this method can be used to get the corresponding angle. Angles are measured in radians and go from (approximately) -(Math.PI / 2) (middle top) to 1.5 * Math.PI. Example usage is:

<script>
    activity = new RGraph.SVG.Activity({
        id: 'chart-container',
        min: 0,
        max: 100,
        value: 63,
        options: {
            width: 60,
            labelsCenterDecimals: 1
        }
    }).draw();
    
    activity.container.onclick = function (e)
    {
        var angle = activity.getAngle(e);
        // var angle = activity.getAngle(51); // You can also pass the function a value too
        
        alert(angle);
    };
</script>
obj.getValue(event or angle)

When you click on the chart this method can be used to get the corresponding value. The value is based on the minimum and maximum values. Example usage is:

<script>
    activity = new RGraph.SVG.Activity({
        id: 'chart-container',
        min: 0,
        max: 100,
        value: 63,
        options: {
            width: 60,
            labelsCenterDecimals: 1
        }
    }).draw();
    
    activity.container.onclick = function (e)
    {
        var value = activity.getValue(e);
        // var value = activity.getValue(angle); // You can also pass the function an angle too
        
        alert(value);
    };
</script>
obj.getRadius(event)

When you click on the chart this method can be used to get the corresponding radius of the click starting from the center of the chart. Example usage is:

<script>
    activity = new RGraph.SVG.Activity({
        id: 'chart-container',
        min: 0,
        max: 100,
        value: 63,
        options: {
            width: 60,
            labelsCenterDecimals: 1
        }
    }).draw();
    
    activity.container.onclick = function (e)
    {
        var radius = activity.getRadius(e);
        
        alert(radius);
    };
</script>

Events

RGraph supports custom events that allow you to easily add interactivity to your charts if required. The following events are available:

For example:
new RGraph.SVG.Activity({
    id: 'chart-container',
    min: 0,
    max: 100,
    value: [23,35,45],
    options: {
        adjustable: true
    }
}).draw().on('adjustbegin', function (obj)
{
    console.log('Adjusting has started');

}).on('adjust', function (obj)
{
    console.log('Adjusting is in progress...');

}).on('adjustend', function (obj)
{
    alert('Adjusting has finished. New values are: ' + obj.value);
});

Effects

These effects are available and can be used instead of the draw() function.
<script>
    //
    // Optional callback function that's called when the effect is complete
    //
    function myCallback (obj)
    {
        // ...
    }


    new RGraph.SVG.Activity({
        id: 'chart-container',
        min: 0,
        max: 100,
        value: 63,
        options: {
            width: 60,
            labelsCenterDecimals: 1
        }
    }).grow({frames: 60, callback: myCallback});
</script>