Horseshoe meter

Example

View example on CodePen
<script>
    new RGraph.Horseshoe({
        id: 'cvs',
        min: 0,
        max: 100,
        value: 63,
        options: {
            labelSize: 60,
            labelUnitsPost: '%',
            adjustable: true
        }
    }).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

PropertyDescriptionDefault
centerxThe horizontal coordinate of the meter.null (the horizontal center of the canvas)
centeryThe vertical coordinate of the meter.null (the vertical center of the canvas)
radiusThe radius of the chart.null (this is generated based on the size of the canvas)
widthThis is the width of the circular bar that makes up the chart.10
centerx
The horizontal coordinate of the meter.
Default: null (the horizontal center of the canvas)

centery
The vertical coordinate of the meter.
Default: null (the vertical center of the canvas)

radius
The radius of the chart.
Default: null (this is generated based on the size of the canvas)

width
This is the width of the circular bar that makes up the chart.
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 color of the indicator bars (foreground and background). These can be solid colors or gradients that you create.['black','#eee']
backgroundColorThe background color of the whole canvas.null (ie no color)
colors
The color of the indicator bars (foreground and background). These can be solid colors or gradients that you create.
Default: ['black','#eee']

backgroundColor
The background color of the whole canvas.
Default: null (ie no color)

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
textFontThe font used to render the text.Arial, Verdana, sans-serif
textColorThe color of the label.black
textSizeThe size of the text (in points).70
textBoldWhether the text on the chart is bold or not.false
textItalicWhether the text on the chart is italic or not.false
labelsCenterWhether the center label is displayed or not.true
labelsCenterFontThe font used by the labels. Because there's only one label you might as well use the textFont property.null
labelsCenterSizeThe size of the labels. Because there's only one label you might as well use the textSize property.null
labelsCenterColorThe color of the labels. Because there's only one label you might as well use the textColor property.null
labelsCenterBoldWhether the labels are bold or not. Because there's only one label you might as well use the textBold property.null
labelsCenterItalicWhether the labels are italic or not. Because there's only one label you might as well use the textItalic property.null
labelsCenterDecimalsThe number of decimals that are shown on the label. 0
labelsCenterUnitsPreThese units are prepended to the number.[an empty string]
labelsCenterUnitsPostThese units are appended to the number.[an empty string]
labelsCenterPointThe character that's used as the decimal point..
labelsCenterThousandThe character that's used as the thousand separator.,
labelsCenterSpecificIf you want to specify your own label, which can be textual, you can use this property. You can also use formatted labels.null
labelsCenterSpecificFormattedDecimalsWhen using formatted labels this is the number of decimals that are applied to the %{value_formatted} macro. 0
labelsCenterSpecificFormattedPointWhen using formatted labels this is the decimal point character that's used with the %{value_formatted} macro..
labelsCenterSpecificFormattedThousandWhen using formatted labels this is the thousand separator character that's used with the %{value_formatted} macro.,
labelsCenterSpecificFormattedUnitsPreWhen using formatted labels these are the units that are prepended to the number with the %{value_formatted} macro.(an empty string)
labelsCenterSpecificFormattedUnitsPostWhen using formatted labels these are the units that are appended to the number with the %{value_formatted} macro.(an empty string)
labelsCenterOffsetxThis allows you finer-grained control in the horizontal direction over the text positioning if you need it. 0
labelsCenterOffsetyThis allows you finer-grained control in the vertical direction over the text positioning if you need it. 0
textThis allows you to add custom text to your chart if you want to. There's a dedicated page that describes this option here.null
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

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

textColor
The color of the label.
Default: black

textSize
The size of the text (in points).
Default: 70

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

labelsCenter
Whether the center label is displayed or not.
Default: true

labelsCenterFont
The font used by the labels. Because there's only one label you might as well use the textFont property.
Default: null

labelsCenterSize
The size of the labels. Because there's only one label you might as well use the textSize property.
Default: null

labelsCenterColor
The color of the labels. Because there's only one label you might as well use the textColor property.
Default: null

labelsCenterBold
Whether the labels are bold or not. Because there's only one label you might as well use the textBold property.
Default: null

labelsCenterItalic
Whether the labels are italic or not. Because there's only one label you might as well use the textItalic property.
Default: null

labelsCenterDecimals
The number of decimals that are shown on the label.
Default: 0

labelsCenterUnitsPre
These units are prepended to the number.
Default: [an empty string]

labelsCenterUnitsPost
These units are appended to the number.
Default: [an empty string]

labelsCenterPoint
The character that's used as the decimal point.
Default: .

labelsCenterThousand
The character that's used as the thousand separator.
Default: ,

labelsCenterSpecific
If you want to specify your own label, which can be textual, you can use this property. You can also use formatted labels.
Default: null

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

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

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

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

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

labelsCenterOffsetx
This allows you finer-grained control in the horizontal direction over the text positioning if you need it.
Default: 0

labelsCenterOffsety
This allows you finer-grained control in the vertical direction over the text positioning if you need it.
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

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 meter will be adjustable (click the bar and drag it).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 meter will be adjustable (click the bar and drag it).
Default: false

Miscellaneous properties

PropertyDescriptionDefault
endsRadiusUse this property to specify the radius of the ends of the chart.null
endsColorIf you want to specify the color of the ends of the meter then you can use this property. Otherwise, they default to be the same color as the meter.null
cleartoThis is used in animations and effects as the default color to use when clearing the canvas.null
responsiveThis 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
endsRadius
Use this property to specify the radius of the ends of the chart.
Default: null

endsColor
If you want to specify the color of the ends of the meter then you can use this property. Otherwise, they default to be the same color as the meter.
Default: null

clearto
This is used in animations and effects as the default color to use when clearing 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.getValue(event or angle)

This method can be used to get the value at a particular point when you click on the chart (or you can provide an angle, measured in radians). An example:

obj.canvas.onclick = function (e)
{
    var obj   = e.target.__object__;
    var value = obj.getValue(e);
    // var value = obj.getValue(3.14); // You can also provide an angle
    
    // ...
}

obj.getAngle(event or value)
This method will return you an appropriate angle for the given value (or you can provide an event object).

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:

obj.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.Horseshoe({
    id: 'cvs',
    min: 0,
    max: 100,
    value: 56,
    options: {
    }
}).on('draw', function (e, shape)
{
    // Put the draw event code here
})
.on('click', function (e, shape)
{
    // Handle the click event
}).draw();
obj.exec(function)

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:

For example:
new RGraph.Horseshoe({
    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 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)
    {
        // ...
    }

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