Using labels with PieChart controls -- Flex 2

PieChart controls support labels that display information about each data point. All charts support DataTips, which display the value of a data point when the user moves the mouse over it. Labels are different from DataTips in that they are always visible and do not react to mouse movements. The PieChart control is the only chart that supports labels.

To add 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 properties of the PieChart control that you can use to manipulate the appearance of labels:

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.
`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.
`insideWithCallout`	Draws labels inside the pie, but if labels are shrunk below a legible size, Flex converts them to callout labels. This is a common value to set `labelPosition` to when the actual size of your chart is flexible and users might resize it.
`none`	Does not draw labels. This is the default value.
`outside`	Draws labels around the boundary of the PieChart control.

Property	Description
`calloutGap`	Defines how much space, in pixels, to insert between the edge of the pie and the 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.
`insideLabelSizeLimit`	Defines the size threshold, expressed in points, below which inside labels are considered illegible. Below this threshold, labels are either removed entirely or turned into callouts based on the setting of the series `labelPosition` property.

To modify the label text, you use the labelFunction property to specify a callback function. The function specified in labelFunction returns a string that Flex displays as the label over the pie wedge. The following is the required format of the callback function:

function function_name ( data, field, index, percentValue ): return_type { }

The following table describes the parameters of the labelFunction callback function:

Parameter	Description
`data`	A reference to the data point that this pie wedge represents; type Object.
`field`	The field name from the data provide; type String.
`index`	The number of the data point in the data provider; type Number.
`percentValue`	The size of the pie wedge relative to the pie. If the pie wedge is a quarter of the size of the pie, this value is 25; type Number.

The following example generates labels that include data and formatting. It defines the display() method as the labelFunction to handle formatting of the label text.

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script><![CDATA[
        import mx.formatters.*;
        import mx.collections.ArrayCollection;
        [Bindable]
        public var expenses:ArrayCollection = new ArrayCollection([
            {Expense: "Taxes", Amount: 1900000},
            {Expense: "Salaries", Amount: 1350000},
            {Expense: "Building Rent", Amount: 300000},
            {Expense: "Insurance", Amount: 750000},
            {Expense: "Benefits", Amount: 800000},
            {Expense: "Miscellaneous", Amount: 900000}
        ]);
        public function display(data:Object, field:String, index:Number,
                percentValue:Number):String {
            return data.Expense + ": $" + data.Amount + "\n" +
                round(percentValue,2) + "%";
        }
        // Rounds to 2 places:
        public function round(num:Number, precision:Number):Number { 
            var result:String;
            var f:NumberFormatter = new NumberFormatter();
            f.precision = precision;
            result = f.format(num);
            return Number(result);
        }
    ]]></mx:Script>
    <mx:Panel title="Expenditures for FY04">
        <mx:PieChart id="chart" dataProvider="{expenses}"
            showDataTips="false">
            <mx:series>
                <mx:PieSeries labelPosition="callout" field="Amount"
                    labelFunction="display"/>
            </mx:series>
        </mx:PieChart>
    </mx:Panel>
</mx:Application>