Legend controls match the fill patterns on your chart to labels that describe the data series shown with those fill patterns. Each entry in a Legend control is known as a legend item. A legend item contains two basic parts: the marker, and the label. Legend items are of type LegendItem. The following example shows the two parts of a legend item:

In addition to matching fill patterns, legend markers also use the renderer classes of ChartItem objects, such as the points on a PlotChart control. The following example shows a Legend control for a PlotChart control with three series. Each series uses its own renderer class to draw a particular shape, and the Legend control reflects those shapes:

For information on styling Legend controls, see Formatting Legend controls.

Adding a Legend control to your chart

You use the Legend class to add a legend to your charts. The Legend control displays the label for each data series in the chart and a key that shows the chart element for the series.

The simplest way to create a Legend control is to bind a chart to it by using the dataProvider property, as the following example shows:

<?xml version="1.0"?>
<!-- charts/LegendNamedSeries.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

  <mx:Script>
     import mx.collections.ArrayCollection;
     [Bindable]
     public var expenses:ArrayCollection = new ArrayCollection([
        {Expense:"Taxes", Amount:2000, Cost:321, Discount:131},
        {Expense:"Rent", Amount:1000, Cost:95, Discount:313},
        {Expense:"Bills", Amount:100, Cost:478, Discount:841}
     ]);
  </mx:Script>

  <mx:Panel title="Bar Chart with Legend">
     <mx:BarChart id="myChart" dataProvider="{expenses}" showDataTips="true">
        <mx:verticalAxis>
           <mx:CategoryAxis 
                dataProvider="{expenses}" 
                categoryField="Expense"
           />
        </mx:verticalAxis>
        <mx:series>
           <mx:BarSeries 
                xField="Amount" 
                displayName="Amount (in $USD)"
           />
           <mx:BarSeries 
                xField="Cost" 
                displayName="Cost (in $USD)"
           />
           <mx:BarSeries 
                xField="Discount" 
                displayName="Discount (in $USD)"
           />
        </mx:series>
     </mx:BarChart>
     <mx:Legend dataProvider="{myChart}"/>
  </mx:Panel>

</mx:Application>
The executing SWF file for the previous example is shown below:

You add a Legend to a chart in ActionScript by instantiating a new object of type Legend, and then calling the container's addChild() method to add the Legend to the container, as the following example shows:

<?xml version="1.0"?>
<!-- charts/LegendInAS.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
creationComplete="createLegend()">

  <mx:Script><![CDATA[
     import mx.collections.ArrayCollection;
     import mx.charts.Legend;

     [Bindable]
     public var expenses:ArrayCollection = new ArrayCollection([
        {Expense:"Taxes", Amount:2000, Cost:321, Discount:131},
        {Expense:"Rent", Amount:1000, Cost:95, Discount:313},
        {Expense:"Bills", Amount:100, Cost:478, Discount:841}
     ]);

     private function createLegend():void {
        var myLegend:Legend = new Legend();
        myLegend.dataProvider = myChart;
        panel1.addChild(myLegend);
     }
  ]]></mx:Script>

  <mx:Panel id="panel1" title="Bar Chart with Legend (Created in ActionScript)">
     <mx:BarChart id="myChart" dataProvider="{expenses}" showDataTips="true">
        <mx:verticalAxis>
           <mx:CategoryAxis 
                dataProvider="{expenses}" 
                categoryField="Expense"
           />
        </mx:verticalAxis>
        <mx:series>
           <mx:BarSeries 
                xField="Amount" 
                displayName="Amount (in $USD)"
           />
           <mx:BarSeries 
                xField="Cost" 
                displayName="Cost (in $USD)"
           />
           <mx:BarSeries 
                xField="Discount" 
                displayName="Discount (in $USD)"
           />
        </mx:series>
     </mx:BarChart>
  </mx:Panel>

</mx:Application>
The executing SWF file for the previous example is shown below:

The Legend control creates the legend using information from the chart control. It matches the colors and names of the LegendItem markers to the fills and labels of the chart's data series. In the previous example, Flex uses the BarSeries control's displayName property to define the LegendItem label.

Legend controls require that elements of the charts be named. If they are not named, the Legend markers appear, but without labels.

A Legend control for a PieChart control uses the nameField property of the data series to find values for the legend. The values that the nameField property point to must be Strings.

The following example sets the nameField property of a PieChart control's data series to Expense. Flex uses the value of the Expense field in the data provider in the Legend control.

<?xml version="1.0"?>
<!-- charts/LegendNameField.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

<mx:Script>
  import mx.collections.ArrayCollection;
  [Bindable]
  public var expenses:ArrayCollection = new ArrayCollection([
     {Expense:"Taxes", Amount:2000},
     {Expense:"Rent", Amount:1000},
     {Expense:"Food", Amount:200}
  ]);
</mx:Script>

  <mx:Panel title="Pie Chart with Legend">
     <mx:PieChart id="myChart" 
        dataProvider="{expenses}" 
        showDataTips="true"
     >
        <mx:series>
           <mx:PieSeries 
                field="Amount" 
                nameField="Expense"
           />
        </mx:series>
     </mx:PieChart>
     <mx:Legend dataProvider="{myChart}"/>
  </mx:Panel>

</mx:Application>
The executing SWF file for the previous example is shown below:

The nameField property also defines the series for the DataTip objects and labels.

Creating a custom Legend control

You can create a custom Legend control in MXML by defining the <mx:Legend> tag and populating it with <mx:LegendItem> tags. The following example creates a custom legend for the chart with multiple axes:

<?xml version="1.0"?>
<!-- charts/MultipleAxesWithCustomLegend.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
  <mx:Script><![CDATA[
     import mx.collections.ArrayCollection;

     [Bindable]
      public var SMITH:ArrayCollection = new ArrayCollection([
        {date:"22-Aug-05", close:41.87},
        {date:"23-Aug-05", close:45.74},
        {date:"24-Aug-05", close:42.77},
        {date:"25-Aug-05", close:48.06},
     ]);

     [Bindable]
      public var DECKER:ArrayCollection = new ArrayCollection([
        {date:"22-Aug-05", close:157.59},
        {date:"23-Aug-05", close:160.3},
        {date:"24-Aug-05", close:150.71},
        {date:"25-Aug-05", close:156.88},
     ]);

    [Bindable]
    public var deckerColor:Number = 0x224488;

    [Bindable]
    public var smithColor:Number = 0x884422;


  ]]></mx:Script>

  <mx:Stroke id="h1Stroke" 
        color="{smithColor}" 
        weight="8" 
        alpha=".75"
        caps="square"
  />

  <mx:Stroke id="h2Stroke" 
        color="{deckerColor}" 
        weight="8" 
        alpha=".75"
        caps="square"
  />

  <mx:Panel title="Column Chart With Multiple Axes">
     <mx:ColumnChart id="myChart" showDataTips="true">
        <mx:horizontalAxis>
           <mx:CategoryAxis id="h1" categoryField="date"/>
        </mx:horizontalAxis>

        <mx:horizontalAxisRenderers>
            <mx:AxisRenderer placement="bottom" axis="{h1}"/>
        </mx:horizontalAxisRenderers>

        <mx:verticalAxisRenderers>
            <mx:AxisRenderer placement="left" axis="{v1}">
                <mx:axisStroke>{h1Stroke}</mx:axisStroke>
            </mx:AxisRenderer>
            <mx:AxisRenderer placement="left" axis="{v2}">
                <mx:axisStroke>{h2Stroke}</mx:axisStroke>
            </mx:AxisRenderer>
        </mx:verticalAxisRenderers>

        <mx:series>
           <mx:ColumnSeries id="cs1" 
                horizontalAxis="{h1}" 
                dataProvider="{SMITH}" 
                yField="close" 
                displayName="SMITH"
            >
                <mx:fill>
                    <mx:SolidColor color="{smithColor}"/>
                </mx:fill>
                
                <mx:verticalAxis>
                   <mx:LinearAxis id="v1" minimum="40" maximum="50"/>
                </mx:verticalAxis>           
           </mx:ColumnSeries>           
           <mx:LineSeries id="cs2" 
                horizontalAxis="{h1}" 
                dataProvider="{DECKER}" 
                yField="close" 
                displayName="DECKER"
            >
                <mx:verticalAxis>
                    <mx:LinearAxis id="v2" minimum="150" maximum="170"/>           
                </mx:verticalAxis>

                <mx:lineStroke>
                    <mx:Stroke 
                        color="{deckerColor}" 
                        weight="4" 
                        alpha="1"
                    />
                </mx:lineStroke>
           </mx:LineSeries>
        </mx:series>
     </mx:ColumnChart>
     <mx:Legend>
        <mx:LegendItem label="SMITH" fontWeight="bold">
           <mx:fill>
            <mx:SolidColor color="{smithColor}"/>
           </mx:fill>
           <mx:stroke>
            <mx:Stroke color="0xCCCCCC" weight="2"/>
           </mx:stroke>
        </mx:LegendItem>
        <mx:LegendItem label="DECKER" fontWeight="bold">
           <mx:fill>
            <mx:SolidColor color="{deckerColor}"/>
           </mx:fill>
           <mx:stroke>
            <mx:Stroke color="0xCCCCCC" weight="2"/>
           </mx:stroke>
         </mx:LegendItem>
     </mx:Legend>
  </mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below: