Using pie charts

You use the PieChart control to define a standard pie chart. The data for the data provider determines the size of each wedge in the pie chart relative to the other wedges.

You use the PieSeries chart series with the PieChart control to define the data for the chart. The PieSeries can create standard pie charts or doughnut charts. PieChart controls also support labels that identify data points.

The following table describes the properties of the PieChart control’s PieSeries chart series that you commonly use to define your chart:

Property

Description

 
field

Specifies the field of the data provider that determines the data for each wedge of the pie chart. 

labelPosition

Specifies how to render data labels for the wedges.

 
nameField

Specifies the field of the data provider to use as the name for the wedge in DataTip objects and legends.

The following example defines a PieChart control:

<?xml version="1.0"?>
<!-- charts/BasicPie.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="srv.send()"
    height="600">

    <fx:Declarations>
         <!-- View source of the following page to see the structure of the data that Flex uses in this example. -->
         <mx:HTTPService id="srv" url="http://aspexamples.adobe.com/chart_examples/budget-xml.aspx"/>
         <!-- To see data in an HTML table, go to http://aspexamples.adobe.com/chart_examples/budget.aspx -->  
    </fx:Declarations>

    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

  <s:Panel title="Pie Chart">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
     <mx:PieChart id="myChart" 
        dataProvider="{srv.lastResult.data.result}" 
        showDataTips="true">
        <mx:series>
           <mx:PieSeries 
                field="amount" 
                nameField="item" 
                labelPosition="callout"/>
        </mx:series>
     </mx:PieChart>
     <mx:Legend dataProvider="{myChart}"/>
  </s:Panel>
</s:Application>
The executing SWF file for the previous example is shown below:

To customize the colors of the wedges in a PieChart control, you use the fills property. You pass this an Array of SolidColor objects. The following example defines an Array of custom SolidColor objects, and applies it to the PieSeries object in the PieChart control.

<?xml version="1.0"?>
<!-- charts/PieFilling.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="srv.send()"
    height="600">

    <fx:Declarations>
        <!-- View source of the following page to see the structure of the data that Flex uses in this example. -->
        <mx:HTTPService id="srv" url="http://aspexamples.adobe.com/chart_examples/budget-xml.aspx"/>
        <!-- To see data in an HTML table, go to http://aspexamples.adobe.com/chart_examples/budget.aspx -->  

        <!-- Define custom colors for use as pie wedge fills. -->
        <mx:SolidColor id="sc1" color="blue" alpha=".3"/>
        <mx:SolidColor id="sc2" color="red" alpha=".3"/>
        <mx:SolidColor id="sc3" color="green" alpha=".3"/>
        <mx:SolidColor id="sc4" color="gray" alpha=".3"/>
        <mx:SolidColor id="sc5" color="black" alpha=".3"/>
        <mx:SolidColor id="sc6" color="yellow" alpha=".3"/>
    </fx:Declarations>

    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

    <s:Panel title="PieChart control with custom fills">
         <s:layout>
             <s:VerticalLayout/>
         </s:layout>
        <mx:PieChart id="pie" 
            dataProvider="{srv.lastResult.data.result}" 
            showDataTips="true">
            <mx:series>
                <mx:PieSeries 
                    field="amount" 
                    nameField="item"
                    labelPosition="callout"
                    fills="{[sc1, sc2, sc3, sc4, sc5, sc6]}"/>
            </mx:series>
        </mx:PieChart>
        <mx:Legend dataProvider="{pie}"/>
    </s:Panel>
</s:Application>
The executing SWF file for the previous example is shown below:

For more information on using fills, see Using fills with chart controls.

You can also customize the lines that outline each wedge by using the stroke property of a PieSeries object. You set this property to an instance of the SolidColorStroke class. For more information on using the SolidColorStroke class, see Using strokes with chart controls.

Using data labels with PieChart controls

PieChart controls support data labels that display information about each data point. All charts support DataTip objects, which display the value of a data point when the user moves the mouse over it. Data labels, on the other hand, are only supported by PieSeries, ColumnSeries, and BarSeries objects. Data labels are different from DataTip objects in that they are always visible and do not react to mouse movements.

To add data labels to your PieChart control, set the labelPosition property on the series to a valid value other than none. To remove labels from your pie chart, set the labelPosition property to none. The default value is none.

The following table describes the valid values of the labelPosition property for a PieSeries object. The PieSeries class supports more values for this property than the BarSeries and ColumnSeries classes.

Value

Description

callout

Draws labels in two vertical stacks on either side of the PieChart control. Shrinks the PieChart if necessary to make room for the labels. Draws key lines from each label to the associated wedge. Shrinks labels as necessary to fit the space provided.

This property can only be used with a PieSeries object. You cannot use callouts with BarSeries and ColumnSeries objects.

inside

Draws labels inside the chart. Shrinks labels to ensure that they do not overlap each other. Any label that must be drawn too small, as defined by the insideLabelSizeLimit property, is hidden from view.

When two labels overlap, Flex gives priority to labels for larger slices. not true any more???

insideWithCallout

Draws labels inside the pie, but if labels are shrunk below a legible size, Flex converts them to callout labels. You commonly set the value of the labelPosition property to insideWithCallout when the actual size of your chart is flexible and users might resize it.

This property can only be used with a PieSeries object. You cannot use callouts with BarSeries and ColumnSeries objects.

none

Does not draw labels. This is the default value.

outside

Draws labels around the boundary of the PieChart control.

The following table describes the properties of the PieSeries object that you can use to manipulate the appearance of labels:

Property

Description

calloutGap

Defines how much space, in pixels, to insert between the edge of the pie and the data labels when rendering callouts. The default value is 10 pixels.

calloutStroke

Defines the line style used to draw the lines to callouts. For more information on defining line data points, see Using strokes with chart controls.

insideLabelSizeLimit

Defines the size threshold, expressed in points, below which inside data labels are considered illegible. Below this threshold, data labels are either removed entirely or turned into callouts based on the setting of the series labelPosition property.

You can change the value of the data labels by using the labelFunction property of the PieSeries object to specify a callback function. For more information, see Customizing data label values.

Creating doughnut charts

Flex lets you create doughnut charts out of PieChart controls. Doughnut charts are identical to pie charts, except that they have hollow centers and resemble wheels rather than filled circles.

To create a doughnut chart, specify the innerRadius property on the PieChart control, as the following example shows: 

<?xml version="1.0"?>
<!-- charts/DoughnutPie.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="srv.send()"
    height="600">

    <fx:Declarations>
         <!-- View source of the following page to see the structure of the data that Flex uses in this example. -->
         <mx:HTTPService id="srv" url="http://aspexamples.adobe.com/chart_examples/budget-xml.aspx"/>
         <!-- To see data in an HTML table, go to http://aspexamples.adobe.com/chart_examples/budget.aspx -->  
    </fx:Declarations>

    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

  <s:Panel title="Pie Chart">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
     <mx:PieChart id="myChart" 
        dataProvider="{srv.lastResult.data.result}" 
        showDataTips="true" 
        innerRadius=".3">
        <mx:series>
           <mx:PieSeries 
                field="amount" 
                nameField="item" 
                labelPosition="callout"/>
        </mx:series>
     </mx:PieChart>
     <mx:Legend dataProvider="{myChart}"/>
  </s:Panel>
</s:Application>
The executing SWF file for the previous example is shown below:

The value of the innerRadius property is a percentage value of the “hole” compared to the entire pie’s radius. Valid values range from 0 to 1.

Creating exploding pie charts

The PieSeries chart series supports exploding wedges, both uniformly and on a per-wedge basis, so that you can achieve effects similar to the following:

View full size graphic

The following table describes the properties that support exploding pie charts:

Property

Description

explodeRadius

A value from 0 to 1, representing the percentage of the available pie radius to use when exploding the wedges of the pie.

perWedgeExplodeRadius

An array of values from 0 to 1. The Nth value in this array is added to the value of explodeRadius to determine the explode amount of each individual wedge of the pie. Individual values can be left undefined, in which case the wedge will only explode according to the explodeRadius property.

reserveExplodeRadius

A value from 0 to 1, representing an amount of the available pie radius to reserve for animating an exploding wedge.

To explode all wedges of a pie chart evenly, you use the explodeRadius property on the PieSeries, as the following example shows: 

<?xml version="1.0"?>
<!-- charts/ExplodingPie.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="srv.send()"
    height="600">

    <fx:Declarations>
         <!-- View source of the following page to see the structure of the data that Flex uses in this example. -->
         <mx:HTTPService id="srv" url="http://aspexamples.adobe.com/chart_examples/budget-xml.aspx"/>
         <!-- To see data in an HTML table, go to http://aspexamples.adobe.com/chart_examples/budget.aspx -->  
    </fx:Declarations>

    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

  <s:Panel title="Exploding Pie Chart">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
     <mx:PieChart id="pie" 
        dataProvider="{srv.lastResult.data.result}" 
        showDataTips="true">
        <mx:series>
           <!--explodeRadius is a number between 0 and 1.-->
           <mx:PieSeries
                field="amount"
                nameField="item"
                explodeRadius=".12"/>
        </mx:series>
     </mx:PieChart>
     <mx:Legend dataProvider="{pie}"/>
  </s:Panel>
</s:Application>
The executing SWF file for the previous example is shown below:

To explode one or more wedges of the pie, you use an Array of explodeRadius values. Each value in the Array applies to the corresponding data point. In the following example, the fourth data point, the Car expense, is exploded: 

<?xml version="1.0"?>
<!-- charts/ExplodingPiePerWedge.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    creationComplete="srv.send()"
    height="600">

    <fx:Declarations>
         <!-- View source of the following page to see the structure of the data that Flex uses in this example. -->
         <mx:HTTPService id="srv" url="http://aspexamples.adobe.com/chart_examples/budget-xml.aspx"/>
         <!-- To see data in an HTML table, go to http://aspexamples.adobe.com/chart_examples/budget.aspx -->  
    </fx:Declarations>

  <fx:Script><![CDATA[
     // Create a bindable Array of explode radii.
     [Bindable]
     public var explodingArray:Array = [0,0,0,.2,0,0]
  ]]></fx:Script>

    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

  <s:Panel title="Exploding Pie Chart Per Wedge">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
     <mx:PieChart id="pie" 
        dataProvider="{srv.lastResult.data.result}" 
        showDataTips="true">
        <mx:series>
           <!--Apply the Array of radii to the PieSeries.-->
           <mx:PieSeries
                field="amount"
                nameField="item"
                perWedgeExplodeRadius="{explodingArray}"
                labelPosition="callout"/>
        </mx:series>
     </mx:PieChart>
     <mx:Legend dataProvider="{pie}"/>
  </s:Panel>
</s:Application>
The executing SWF file for the previous example is shown below: