SVG Segmented donut chart API reference

Documentation about the SVG Segmented donut chart 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>
    seg = new RGraph.SVG.Segmented({
        id: 'chart-container',
        min: 0,
        max: 100,
        value: 63,
        options: {
            width: 60,
            labelsCenterDecimals: 1
        }
    }).roundRobin();
    
    var d = 2500; setTimeout(f = function ()
    {
        seg.value = seg.value + RGraph.SVG.random({min: -7, max: 5});
        seg.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).null
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: null

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 donut. The first color is that of the indicator segments and the second color is used as the background.['red','white']
backgroundColorThe color of the background.black
colors
The colors to be used for the donut. The first color is that of the indicator segments and the second color is used as the background.
Default: ['red','white']

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.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
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
labelsCenterFormattedDecimalsWhen using formatted labels this is the number of decimals that are applied to the %{value_formatted} macro.0
labelsCenterFormattedPointWhen using formatted labels this is the decimal point character that's used with the %{value_formatted} macro..
labelsCenterFormattedThousandWhen using formatted labels this is the thousand separator character that's used with the %{value_formatted} macro.,
labelsCenterFormattedUnitsPreWhen using formatted labels these are the units that are prepended to the number with the %{value_formatted} macro.(an empty string)
labelsCenterFormattedUnitsPostWhen 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: 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

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

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

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

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

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

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

Other properties

PropertyDescriptionDefault
adjustableIf true then the meter will be adjustable. Click on the meter to alter its value.false
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'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.

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


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