Pie chart API reference
Documentation about the Pie chart including information about all of the options that are available to you. The Pie chart can show a single dataset and with the donut option it can show multiple datasets. Some people find them to be quite contentious though as comparing individual pieces of data can be tricky.
Example
<script> data = [564,155,499,611,322]; new RGraph.Pie({ id: 'cvs', data: data, options: { labels: ['Abc', 'Def', 'Ghi', 'Jkl', 'Mno'], linewidth: 2, colorsStroke: 'white' } }).draw(); </script>
Properties
You can use these properties to control how the pie chart looks. You can set
them by using the set()
method. Eg:
myPie.set('name', 'value');
- Chart configuration properties
- Margin properties
- Colour properties
- Labels and text properties
- Title properties
- Shadow properties
- Interactive features properties
- Key properties
- Event properties
- Miscellaneous properties
Chart configuration properties
Margin properties
Colour properties
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 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"> | true |
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 |
textSize | The size of the text. | 10 |
textFont | The font used to render the text. | Arial, Verdana, sans-serif |
textColor | The colour of the labels. | black |
textItalic | Whether the text on the chart is italic or not. | false |
textBold | Whether the text on the chart is bold or not. | false |
labels | An array of labels to be used for the chart. | An empty array |
labelsFont | The font used to render the labels. | null |
labelsSize | The size of the labels. | null |
labelsColor | The colour of the labels. | null |
labelsBold | Whether the labels are bold or not. | null |
labelsItalic | Whether the labels are italic or not. | null |
labelsSticksLinewidth | Sets the linewidth of the label sticks. | 1 |
labelsList | A new way of organising the labels - this should help avoid label text overlaps. | true |
labelsIngraph | This shows in-graph labels in each segment. | null |
labelsIngraphBounding | Whether the in-graph labels are surrounded by a bounding box. | false |
labelsIngraphBoundingFill | The fill colour of the bounding square. | white |
labelsIngraphBoundingStroke | The stroke colour of the bounding square. | rgba(0,0,0,0) |
labelsIngraphUnitsPre | This string is PREPENDED to the label. | (empty string) |
labelsIngraphUnitsPost | This string is APPENDED to th label. | (empty string) |
labelsIngraphRadius | If specified this is the radius that the labels are positioned at. If its a number between 0 and 2 it is MULTIPLIED with the radius to get the position. If its above 2 though its used as the EXACT radius. | null |
labelsIngraphPoint | The character used as the decimal point. | . |
labelsIngraphThousand | The character used as the thousand separator. | , |
labelsIngraphDecimals | The number of decimals shown on the ingraph labels. | 0 |
labelsIngraphColor | The colour of the labels. | null |
labelsIngraphFont | The font to use for the ingraph labels. | null |
labelsIngraphSize | The size of the ingraph labels. | null |
labelsIngraphBold | Whether the ingraph labels are bold or not. | null |
labelsIngraphItalic | Whether the ingraph labels are italic or not. | null |
labelsIngraphSpecific | Instead of the values you use this option to specify the text that is shown. | null |
labelsCenter | If you have a donut chart this can show a label in the center. As of version 4.75 This should be a literal string - ie the label that you want to show. | false |
labelsCenterSize | The size of the center label. | 26 |
labelsCenterFont | The font used to render the label. | Arial |
labelsCenterColor | The colour of the center label. | black |
labelsCenterItalic | Whether the center label is italic. | false |
labelsCenterBold | Whether the center label is bold. | false |
Title properties
Shadow properties
Interactive features properties
Property | Description | Default |
---|---|---|
tooltips | A numerically indexed array of tooltips that are shown when a bar is clicked. These can contain HTML. | [] |
tooltipsEvent | This is the event that triggers the tooltips. It can be either onclick or onmousemove. | onclick |
tooltipsEffect | The effect used for showing tooltips. Can be either fade or none. | fade |
tooltipsCssClass | This is the name of the CSS class the chart uses. | RGraph_tooltip |
tooltipsOverride | If you wish to handle showing tooltips yourself, this should be a function object which does just that. There's more information on the tooltips documentation page. | null |
tooltipsNohideonclear | Not an option that you'll need particularly often if at all. Setting this to true means that when you call the RGraph.clear() API function tooltips DO NOT get hidden. | false |
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 colour allowed for annotations. | black |
annotatableLinewidth | This is the line width of the annotations. | 1 |
resizable | Defaulting to false, this determines whether your chart will be resizable. Because of the numerous event handlers this has to install code on, This feature is unlikely to work with other dynamic features (the context menu is fine however). | false |
resizableHandleBackground | With this you can specify the background colour for the resize handle. If you're adjusting the position of the handle then you may need this to make the handle stand out more. | null |
resizableMinwidth | This allows you to set a minimum width that the chart can be resized to. | null |
resizableMinheight | This allows you to set a minimum height that the chart can be resized to. | null |
resizableMaxwidth | This allows you to set a maximum width that the chart can be resized to. | null |
resizableMaxheight | This allows you to set a maximum height that the chart can be resized to. | null |
Key properties
The key properties are documented on the key documentation page.Event properties
Property | Description | Default |
---|---|---|
eventsClick | If you want to add your own onclick function you can do so by assigning it to this property. See here for details. | null |
eventsMousemove | If you want to add your own onmousemove function you can do so by assigning it to this property. See here for details. | null |
eventsMouseover | If you want to add your own onmouseover function you can do so by assigning it to this property. See here for details. | null |
eventsMouseout | If you want to add your own onmouseout function you can do so by assigning it to this property. See here for details. | null |
Miscellaneous properties
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.getShape(event)
obj.getSegment()
makes it easy to determine which segment of the
Pie chart was clicked on. It provides:
- Originating X coordinate
- Originating Y coordinate
- The radius of the segment
- The starting angle (measured in radians)
- The ending angle (measured in radians)
- The zero-indexed segment number
The shape also includes textual indexes like this:
shape['object']
And they are:
- object
- x
- y
- radius
- angle.start
- angle.end
- tooltip
- index
<script>
RGraph.register(myGraph);
myGraph.canvas.onclick = function (e)
{
RGraph.fixEventObject(e);
RGraph.redraw();
var ca = e.target;
var co = ca.getContext('2d');
var obj = ca.__object__;
var segment = obj.getShape(e);
if (segment) {
co.fillStyle = 'rgba(255,255,255,0.5)';
co.beginPath();
co.moveTo(segment[0], segment[1]);
co.arc(segment[0], segment[1], segment[2], segment[3], segment[4], 0);
co.stroke();
co.fill();
e.stopPropagation();
}
}
window.onclick = function (e)
{
RGraph.redraw();
}
</script>
Important Note
This method was formerly a common object method, called
RGraph.getSegment(e)
, but has now (March 2011) been
moved to be part of the Pie chart object.
The explodeSegment()
method allows you to programmatically
trigger the exploding (ie the highlighting of) a particular segment.
The Explode()
method is used like so:
<script>
pie = new RGraph.Pie({
id: 'cvs',
data: [8,9,4,6]
}).draw();
pie.explodeSegment(index, size);
</script>
The index argument is the zero-indexed segment to operate on (counting from the north axis). And the size is measured in pixels.
obj.getAngle(value)This method can be used to get an appropriate angle for a value using the "scale" of the Pie chart. So if your Pie chart is showing values that go from 0-100 and your requested value is 50, this method will return an angle for the bottom of the Pie chart (ie half way around).
obj.on(event, function)
This method can be used to set an event listener on an object. It
operates in a similar way 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:
new RGraph.Pie({ id: 'cvs', data: [4,5,3,8,6,3] }).on('draw', function (e, shape) { // Put your ondraw code here }) .on('click', function (e, shape) { // Handle the click event }) .draw()The exec option and method
The exec function is documented here.
Animation 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 (examples/effects-pie-grow.html)
- The Explode effect (examples/effects-pie-explode.html)
- The RoundRobin effect (examples/effects-pie-roundrobin.html)
<script> /** * Optional callback function that's called when the effect is complete */ function myCallback (obj) { // ... } new RGraph.Pie({ id: 'cvs', data: [8,6,6,5,3,4,2], options: { } }).grow({frames: 60}, myCallback) // .implode({frames: 60}, myCallback) // .roundRobin({frames: 60}, myCallback) </script>