Please refer to the basic tutorial for a general introduction to creating a pie chart.
To create a new pie chart, simply use the following function:
new ac.ACPieChartBuilder() // ... .setWidth(450) .setHeight(250) // ... .build() // ...
As shown above, use setWidth(double)
and setHeight(double)
to set the size of the chart. All other commands would typically be added between new ACPieChartBuilder()
and build()
.
Note: Most of the following examples have been created with the showcase “browserstats” which is included in the distribution.
A pie chart with an empty circle in the middle is commonly called a donut chart. To create a donut chart, simply define the radius of the inner (empty) circle. The radius is in percent of the whole circle, e.g. 0.1 signifies 10% of the (outer) circle's radius wheras 0.9 signifies 90% of the circle's radius.
new ac.ACPieChartBuilder() // ... .setDonutRadius(0.4) // ...
In certains situations, you may wish to configure the angles at which the pie chart begins and ends.
Use the functions setStartAngleDegrees(double)
and setEndAngleDegrees(double)
for this. startAngle and endAngle define the beginning and the end of the circle, respectively. The circle is drawn clockwise.
For example, to draw the above chart, use the following code:
new ac.ACPieChartBuilder() // ... .setStartAngleDegrees(250) .setEndAngleDegrees(110) // ...
If you need to define start and end angle in radians instead of degrees, use the functions setStartAngleRadians(double)
and setEndAngleRadians(double)
for this.
For example, to draw the above chart, use the following code:
new ac.ACPieChartBuilder() // ... .setStartAngleRadians(250/180 * Math.PI) .setEndAngleRadians(110/180 * Math.PI) // ...
Let us assume that you want to display a pie chart with the distribution of web browsers that are used by visitors to your website. However, you want to limit your chart to the most important browsers, let's say to those that have more than 6% of the overall share. All other browsers with less than 6% of the market each are to be summarized into one pie slice labeled “Other browsers”. Here's how to do that with ArcadiaCharts:
new ac.ACPieChartBuilder() // ... .setSummarizeThresholdPercent(6) .setSummarizeLabel("Other browsers") // ...
setSummarizeThesholdPercent
sets the threshold to 6% , i.e. all pie slices below 6% should be added up and summarized into one aggregated slice. setSummarizeLabel
sets the name of that aggregated pie slice to something suitable; here it signifies the “Other web browsers”. In this example, Safari, Opera (and others) have been summarized into one pie slice.
You can either set the threshold as an absolute value (i.e. 500 Euros), or as a relative value (i.e., 6% of the total), by using either setSummarizeThresholdAbsolute(double)
or setSummarizeT
hresholdPercent(double)
Exploding a pie slice can be used to draw attention to a specific portion of the pie. In ArcadiaCharts, you can drag the pie slices outward to explode some or all of the slices away from each other. Let's say you want to draw special attention to the market share of the Firefox browser:
You would use the following code:
new ac.ACPieChartBuilder() // ... .setSliceOffset(0,20) // ...
The function setSliceOffset
takes two parameters: the first signifies the number of the slice that you want to drag outwards (0=first slice, 1=second slice, …), and the second should be a value between 0 and 100, signifying the percentage of the original pie chart's diameter that the slice should be dragged outwards. In our example above, we are extruding the first pie slice by 20% of the original pie chart's diameter.
Use the function resetSliceOffsets()
to return all slices to their original position before they were dragged outwards.
There are several ways of communicating to your audience the details of your pie slices: you can use the popup, you can use the legend, or you can use the pie slice labels, i.e. print a text directly on the pie slices or next to them. Here, the latter method is described.
By default, the pie slices will print the name of the respective value, i.e. “Firefox”.
To change the text in the pie slice labels, there are two functions: setLabelMode
and setLabelText
. setLabelMode
enables preconfigured labels while setLabelText
allows more detailed fine-tuning of the labels. By using setLabelText
you override all modes set by setLabelMode
.
The function setLabelMode
takes one string parameter which can contain the following:
For example:
new ac.ACPieChartBuilder() // ... .setLabelMode(ac.LabelMode.LABEL_PERCENT) // ...
The default separator setLabelMode
is a space character. If you wish to set a different separator e.g. a colon you can use setLabelSeparatingCharacter
For example:
new ac.ACPieChartBuilder() // ... .setLabelSeparatingCharacter(": ") // ...
For more sophisticated needs you can also use the function setLabelText
. It takes one string parameter which can contain the following:
To position your label, use the function setSliceLabelOffset
. It takes one parameter, which defines the position of the label relative to the diameter of the circle: 60 signifies that the label should be printed at 60% of the circle's diameter (i.e. well within the circle), whereas 130 signifies 130% of the pie chart's diameter, meaning slightly outside the pie chart.
For example:
new ac.ACPieChartBuilder() // ... .setLabelText("<h3>$percent</h3>") .setSliceLabelOffset(75) // ...will produce (using the browser statistics showcase):
When working with pie charts, sooner or later you may encounter problems with pie slice labels having too little space. As long as the labels fits into the slice everything ist fine. But if the slice is too small for the label element, the label has to be placed outside of the pie chart and if you have many small slices at the same place, it may be difficult to place all the labels without overlapping.
var myData = "Slice,Value\n"+ "big value:, 95\n"+ "small value 1:, 1\n"+ "small value 2:, 1\n"+ "small value 3:, 1\n"+ "small value 4:, 1\n"+ "small value 5:, 1\n";
ArcadiaCharts default behavior is to skip all labels that can´t be placed without overlapping. You can change this behaviour setting the PIE_CHART_DISPLAY_OUTSIDE_LABELS
variable:
.setBooleanVariable( "PIE_CHART_DISPLAY_OUTSIDE_LABELS", false )Removes all pie slice label that can´t be placed inside of the slices:
.setBooleanVariable( "PIE_CHART_DISPLAY_OUTSIDE_LABELS", true )Forces all pie slice label even if they will overlap:
To get the default behaviour back, just remove the .setBooleanVariable( “PIE_CHART_DISPLAY_OUTSIDE_LABELS”, true/false)
line:
Since pie slice labels can be omitted, you can enforce the display of percentage values next to the corresponding legend entry. To do this, you need to set the LEGEND_DISPLAY_PERCENTAGE
variable to “true”.
.setBooleanVariable( "LEGEND_DISPLAY_PERCENTAGE", true )
The screenshots above show an enabled LEGEND_DISPLAY_PERCENTAGE
.
<variable type="style" name="PieSliceLabel"> <fontFamily>RotisSansSerifStd</fontFamily> <fontSize>10pt</fontSize> <fontWeight>normal</fontWeight> <color>$RED</color> </variable>This would print all pie slice labels in red. Note that, alternatively, you could also define a <red> tag (by defining
<variable type=“style” name=“red”>
in the theme) and then use this in your setLabelText
definition. For a full documentation of available font options, please have a look at the Reference manual page on Fonts.
Please refer to the popup documentation for information on how to format popups and markers in pie charts.
As with all charts, you can change the style of the pie slices in the theme. The following styles are available:
To change the style of your pie slices, add (or edit) the following code to the theme:
<valueSlice> <style>indent</style> </valueSlice>
To change the width of the border effect in indent and beveled valueSlices use the following code in your theme:
<valueSlice> <style>indent</style> <borderWidth>0.1 * $radius</borderWidth> </valueSlice>
<valueSlice> <style>indent</style> <borderWidth>0.1 * $radius</borderWidth> <borderPadding>0.025 * $radius</borderPadding> </valueSlice>
For more information on the <valueSlice> setting, please refer to the <valueSlice> documentation.
ArcadiaCharts contains a number of “built-in” standard themes. The following standard themes are available for pie charts:
More information can be found on the Using themes page.