SVG Horseshoe meter API reference

Documentation about the SVG Horseshoe 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>
    horseshoe = new RGraph.SVG.Horseshoe({
        id: 'chart-container',
        min: 0,
        max: 100,
        value: 63,
        options: {
            labelsCenterDecimals: 1,
            labelsCenterUnitsPost: '%'
        }
    }).grow();
    
    var d = 2500; setTimeout(f = function ()
    {
        horseshoe.value = horseshoe.value + RGraph.SVG.random({min: -7, max: 5});
        horseshoe.grow();
        
        setTimeout(f, d);
    }, d);
</script>

Properties

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

Chart configuration properties

PropertyDescriptionDefault
centerxIf required, you can position the progress bar using this instead of the margins.null
centeryIf required, you can position the progress bar using this instead of the margins.null
radiusIf required, you can size the progress bar using this instead of the margins.null
widthThe width of the progress bar (ie the outer radius minus the inner radius).10
centerx
If required, you can position the progress bar using this instead of the margins.
Default: null

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

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

width
The width of the progress bar (ie the outer radius minus the inner radius).
Default: 10

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

Color properties

PropertyDescriptionDefault
colorsThe colors to be used for the meter. The first color is that of the foreground and the second color is used for the background circular bar.['black','#eee']
backgroundColorThe color of the background.null
colors
The colors to be used for the meter. The first color is that of the foreground and the second color is used for the background circular bar.
Default: ['black','#eee']

backgroundColor
The color of the background.
Default: null

Labels and text properties

PropertyDescriptionDefault
textFontThe font used to render the text.Arial, Verdana, sans-serif
textSizeThe size of the text.60
textColorThe color of the labels.black
textItalicWhether the labels are italic or not.false
textBoldWhether the labels are bold or not.false
labelsCenterWhether to show the center label.true
labelsCenterFontThe font used to render the center label.null
labelsCenterSizeThe size of the center label.null
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.null
labelsCenterUnitsPostUnits that are appended to the center label.null
labelsCenterPointThe character used as the decimal point for the center label.null
labelsCenterThousandThe character used as the thousand separator for the center label.null
labelsCenterDecimalsThe number of decimals to apply to the center label.null
labelsCenterSpecificThe specific text to use as the center label.null
labelsSpecificFormattedDecimalsWhen using formatted labels this is the number of decimals that are applied to the %{value_formatted} macro. 0
labelsSpecificFormattedPointWhen using formatted labels this is the decimal point character that's used with the %{value_formatted} macro..
labelsSpecificFormattedThousandWhen using formatted labels this is the thousand separator character that's used with the %{value_formatted} macro.,
labelsSpecificFormattedUnitsPreWhen using formatted labels these are the units that are prepended to the number with the %{value_formatted} macro.(an empty string)
labelsSpecificFormattedUnitsPostWhen using formatted labels this are the units that are appended to the number with the %{value_formatted} macro.(an empty string)
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
textFont
The font used to render the text.
Default: Arial, Verdana, sans-serif

textSize
The size of the text.
Default: 60

textColor
The color of the labels.
Default: black

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: true

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

labelsCenterSize
The size of the center label.
Default: null

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: null

labelsCenterUnitsPost
Units that are appended to the center label.
Default: null

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

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

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

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

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

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

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

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

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

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

Other properties

PropertyDescriptionDefault
endsWith this property you can disable the circles at the ends of the meter.true
endsRadiusIf specified this is the radius of the circles at each end of the meter.null
endsColorIf specified this is the color of the circles at each end of the meter.null
endsStrokeIf specified this is the stroke color of the circles at each end of the meter (the stroke goes around the fill).null
adjustableIf true then the meter will be adjustable. Click on the meter to alter its value.false
ends
With this property you can disable the circles at the ends of the meter.
Default: true

endsRadius
If specified this is the radius of the circles at each end of the meter.
Default: null

endsColor
If specified this is the color of the circles at each end of the meter.
Default: null

endsStroke
If specified this is the stroke color of the circles at each end of the meter (the stroke goes around the fill).
Default: null

adjustable
If true then the meter will be adjustable. Click on the meter to alter its value.
Default: false

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 or draw) 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 has been 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.

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>
    horseshoe = new RGraph.SVG.Horseshoe({
        id: 'chart-container',
        min: 0,
        max: 100,
        value: 63,
        options: {
            width: 60,
            labelsCenterDecimals: 1
        }
    }).draw();
    
    horseshoe.container.onclick = function (e)
    {
        var angle = horseshoe.getAngle(e);
        // var angle = horseshoe.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>
    horseshoe = new RGraph.SVG.Horseshoe({
        id: 'chart-container',
        min: 0,
        max: 100,
        value: 63,
        options: {
            width: 60,
            labelsCenterDecimals: 1
        }
    }).draw();
    
    horseshoe.container.onclick = function (e)
    {
        var value = horseshoe.getValue(e);
        // var value = horseshoe.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>
    horseshoe = new RGraph.SVG.Horseshoe({
        id: 'chart-container',
        min: 0,
        max: 100,
        value: 63,
        options: {
            width: 60,
            labelsCenterDecimals: 1
        }
    }).draw();
    
    horseshoe.container.onclick = function (e)
    {
        var radius = horseshoe.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.Horseshoe({
    id: 'chart-container',
    min: 0,
    max: 100,
    value: 54,
    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 value is: ' + 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)
    {
        // ...
    }


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