Defining axis labels

You define the values of axis labels on the horizontal axis or vertical axis. You can customize these values by using the available data in the series or you can disable these values altogether.

Disabling axis labels

You can disable labels by setting the value of the showLabels property to false on the AxisRenderer object, as the following example shows:

<?xml version="1.0"?>
<!-- charts/DisabledAxisLabels.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/expenses-xml.aspx"/>
         <!-- To see data in an HTML table, go to http://aspexamples.adobe.com/chart_examples/expenses.aspx -->  
    </fx:Declarations>

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

    <s:Panel title="Disabled Axis Labels">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
        <mx:ColumnChart id="column" 
            dataProvider="{srv.lastResult.data.result}" 
            showDataTips="true">
            <mx:horizontalAxis>
                <mx:CategoryAxis id="a1" categoryField="month"/>
            </mx:horizontalAxis>

            <mx:horizontalAxisRenderers>
                <mx:AxisRenderer 
                    axis="{a1}"                 
                    showLabels="false"/>
            </mx:horizontalAxisRenderers>

            <mx:verticalAxisRenderers>
                <mx:AxisRenderer axis="{a1}" showLabels="false"/>
            </mx:verticalAxisRenderers>

            <mx:series>
                <mx:ColumnSeries 
                    xField="month" 
                    yField="profit"
                    displayName="Profit"/>
                <mx:ColumnSeries 
                    xField="month" 
                    yField="expenses"
                    displayName="Expenses"/>
            </mx:series>
        </mx:ColumnChart>
        <mx:Legend dataProvider="{column}"/>
    </s:Panel>
</s:Application>

The executing SWF file for the previous example is shown below:

Note that any time you want to use an AxisRenderer, you must explicitly set the axis to which it is applied with the renderer’s axis property.

Customizing axis labels

You can customize the value of axis labels by using the labelFunction callback function of the axis. The function specified in labelFunction returns a String, Number, or Date object that Flex displays as the axis label.

The callback function signature for a NumericAxis object (including the DateTimeAxis, LinearAxis, and LogAxis classes) is:

function_name(labelValue:Object, previousLabelValue:Object, axis:IAxis):return_type

The callback function signature for a CategoryAxis object is:

function_name(labelValue:Object, previousLabelValue:Object, axis:axis_type, labelItem:Object):return_type

The following table describes the parameters of the callback function:

Parameter

Description

labelValue

The value of the current label.

previousLabelValue

The value of the label preceding this label. If this is the first label, the value of previousLabelValue is null.

axis

The axis object, such as CategoryAxis or NumericAxis.

labelItem

A reference to the label object. This argument is only passed in for a CategoryAxis object. For NumericAxis subclasses such as LogAxis, DateTimeAxis, and LinearAxis objects, you omit this argument.

This object contains a name/value pair for the chart data. For example, if the data provider defines the Month, Profit, and Expenses fields, this object might look like the following:

Profit:1500

Month:Mar

Expenses:500

You can access the values in this object by using dot-notation for dynamic objects, as the following example shows:

return "$" + labelItem.Profit;

return_type

The type of object that the callback function returns. This can be any object type, but is most commonly a String for CategoryAxis axes, a Number for NumericAxis objects, or a Date object for DateTimeAxis objects.

When you use the labelFunction, you must be sure to import the class of the axis or the entire charts package; for example:

import mx.charts.*;

The following example defines a labelFunction for the horizontal CategoryAxis object. In that function, Flex appends ’10 to the axis labels, and displays the labels as Jan ’10, Feb ’10, and Mar ‘10. For the vertical axis, this example specifies that it is a LinearAxis, and formats the values to include a dollar sign and a thousands separator (by setting the useGrouping property to true on the NumberFormatter). The NumberFormatter also removes decimal values by setting the fractionalDigits property to 0. The return types of the label formatting functions are Strings.

<?xml version="1.0"?>
<!-- charts/CustomLabelFunction.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/expenses-xml.aspx"/>
         <!-- To see data in an HTML table, go to http://aspexamples.adobe.com/chart_examples/expenses.aspx -->  

         <s:NumberFormatter id="numForm" useGrouping="true" fractionalDigits="0"/>  
    </fx:Declarations>

  <fx:Script><![CDATA[
    import mx.charts.*;

    // This method customizes the values of the axis labels.
    // This signature (with 4 arguments) is for a CategoryAxis.
    public function defineLabel(cat:Object, 
                                    pcat:Object,
                                    ax:CategoryAxis,
                                    labelItem:Object):String 
    {
        // Show contents of the labelItem:
        for (var s:String in labelItem) {
            trace(s + ":" + labelItem[s]);
        }

        // Return the customized categoryField value:
        return cat + " '10";

        // Note that if you did not specify a categoryField, 
        // cat would refer to the entire object and not the
        // value of a single field. You could then access 
        // fields by using cat.field_name.
    }

    // For a NumericAxis, you do not use the labelItem argument.
    // This example uses a NumberFormatter to add a thousands
    // separator (by setting useGrouping to true) and removes decimal values 
    // (by setting fractionalDigits to 0).
    public function defineVerticalLabel(
                                        cat:Object, 
                                        pcat:Object,
                                        ax:LinearAxis):String 
    {
        return "$" + numForm.format(cat);
    }

  ]]></fx:Script>
  
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

  <s:Panel title="Custom Label Function">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
     <mx:ColumnChart id="column" 
        dataProvider="{srv.lastResult.data.result}" 
        showDataTips="true">
        <mx:horizontalAxis>
           <mx:CategoryAxis 
                categoryField="month"
                title="Expenses" 
                labelFunction="defineLabel"/>
        </mx:horizontalAxis>

        <mx:verticalAxis>
            <mx:LinearAxis title="Income"
                minimum="0" maximum="2500"
                labelFunction="defineVerticalLabel"/>
        </mx:verticalAxis>

        <mx:series>
           <mx:ColumnSeries 
                xField="month" 
                yField="profit"
                displayName="Profit"/>
           <mx:ColumnSeries 
                xField="month" 
                yField="expenses"
                displayName="Expenses"/>
        </mx:series>
     </mx:ColumnChart>
  </s:Panel>
</s:Application>

The executing SWF file for the previous example is shown below:

In the previous example, if you use a CategoryAxis but do not specify the value of the categoryField property on the axis, the label format function receives an object rather than a value for the first argument. In that case, you must drill down into the object to return a formatted String.

You can also customize labels by using the labelFunction property of the AxisRenderer class. This lets you control the labels if you use multiple axes. The callback function signature for the AxisRenderer’s label function is:

function_name(axisRenderer:IAxisRenderer, label:String):String

Because this particular callback function takes an argument of type IAxisRenderer, you must import that class when you use this function:

import mx.charts.chartClasses.IAxisRenderer;

The following example specifies the value of the labelFunction property for one of the vertical axis renderers. The resulting function, CMstoInches(), converts centimeters to inches for the axis’ labels.

<?xml version="1.0"?>
<!-- charts/CustomLabelsOnAxisRenderer.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"
    height="600">  
    
    <fx:Script>  
    <![CDATA[
        import spark.formatters.NumberFormatter;
        import mx.charts.chartClasses.IAxisRenderer;   
        import mx.collections.ArrayCollection;  
        
        private function CMstoInches(ar:IAxisRenderer, strCMs:String):String {
            var n:NumberFormatter = new NumberFormatter();
            // Set precision to 1 decimal place:
            n.fractionalDigits = 1;
            return n.format((Number(strCMs) * 0.393700787).toString());
        }
        
        [Bindable]
        private var SampleHeightData:ArrayCollection = new ArrayCollection([
            { Age: "Birth", height: 53},
            { Age: "3", height: 57 },
            { Age: "6", height: 64 },
            { Age: "9", height: 70 },
            { Age: "12", height: 82 },
            { Age: "15", height: 88 }
        ]);
            
        [Bindable]
        private var HeightData:ArrayCollection = new ArrayCollection([
            { Age: "Birth", 5: 52, 10: 53, 25:54, 50:58, 75:60, 90:62, 95:63 },
            { Age: "3", 5: 56, 10: 57, 25:58, 50:62, 75:64, 90:66, 95:67 },
            { Age: "6", 5: 62, 10: 63, 25:64, 50:68, 75:70, 90:72, 95:73 },
            { Age: "9", 5: 66, 10: 67, 25:68, 50:72, 75:74, 90:76, 95:77 },
            { Age: "12", 5: 70, 10: 71, 25:72, 50:76, 75:80, 90:82, 95:83 },
            { Age: "15", 5: 74, 10: 75, 25:76, 50:80, 75:84, 90:86, 95:87 }
        ]);
    ]]>
    </fx:Script>

    <fx:Declarations>
        <mx:SolidColorStroke id="s1" weight="1"  />
    </fx:Declarations>
     
    <s:layout>
        <s:VerticalLayout/>
    </s:layout>

    <s:Panel title="Multiple Axis Example, Boys: Age - Height percentiles" 
        height="100%" width="100%">          
        <s:layout>
            <s:HorizontalLayout/>
        </s:layout>
        <mx:ColumnChart id="linechart" height="100%" width="100%"
            paddingLeft="5" 
            paddingRight="5" 
            showDataTips="true" 
            dataProvider="{HeightData}">

            <mx:seriesFilters>
                <fx:Array/>
            </mx:seriesFilters> 

            <mx:backgroundElements>
                <mx:GridLines gridDirection="both"/>
            </mx:backgroundElements>    

            <mx:horizontalAxis>
                <mx:CategoryAxis id="h1"
                    categoryField="Age" 
                    title="Age in Months" 
                    ticksBetweenLabels="false"/>
            </mx:horizontalAxis>

            <mx:verticalAxis>
                <mx:LinearAxis id="v1" 
                    title="Height" 
                    baseAtZero="false"/>
            </mx:verticalAxis>

            <mx:verticalAxisRenderers>                
                <mx:AxisRenderer 
                    axis="{v1}" 
                    placement="right"/>
                <mx:AxisRenderer 
                    axis="{v1}" 
                    placement="right" 
                    labelFunction="CMstoInches" 
                    highlightElements="true"/>
            </mx:verticalAxisRenderers>

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

            <mx:series>
                <mx:LineSeries yField="5"  form="curve" displayName="5%"/>
                <mx:LineSeries yField="10" form="curve" displayName="10%"/>
                <mx:LineSeries yField="25" form="curve" displayName="25%"/>
                <mx:LineSeries yField="50" form="curve" displayName="50%"/>
                <mx:LineSeries yField="75" form="curve" displayName="75%"/>
                <mx:LineSeries yField="90" form="curve" displayName="90%"/>
                <mx:LineSeries yField="95" form="curve" displayName="95%"/>
                <mx:ColumnSeries displayName="Height of Child X" 
                    dataProvider="{SampleHeightData}" 
                    yField="height" 
                    fills="{[0xCC6600]}"/>
            </mx:series>
        </mx:ColumnChart>
        <mx:Legend dataProvider="{linechart}"/>
    </s:Panel>
</s:Application>

The executing SWF file for the previous example is shown below:

Another way to customize the labels on an axis is to set a custom data provider for the labels. This can be done if you are using the CategoryAxis and not the NumericAxis class for the axis values. For more information, see About the CategoryAxis class.

For the PieChart control, you can customize labels with the label function defined on the PieSeries class. For more information, see Using data labels with PieChart controls.

Setting ranges on a NumericAxis

Flex determines the minimum and maximum values along an axis and sets the interval based on the settings of the NumericAxis object. You can override the values that Flex calculates. By changing the range of the data displayed in the chart, you also change the range of the tick marks.

The following table describes the properties of the axis that define the ranges along the axes:

Property

Description

minimum

The lowest value of the axis.

maximum

The highest value of the axis.

interval

The number of units between values along the axis.

The following example defines the range of the y-axis:

<?xml version="1.0"?>
<!-- charts/LinearAxisSample.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/stocks-xml.aspx"/>
        <!-- To see data in an HTML table, go to http://aspexamples.adobe.com/chart_examples/stocks.aspx -->  
    </fx:Declarations>

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

    <s:Panel title="LineChart control with a linear axis">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
        <mx:LineChart id="myChart" 
            dataProvider="{srv.lastResult.data.result}" 
            showDataTips="true" 
            height="300" width="400">
            <mx:verticalAxis>
                <mx:LinearAxis 
                    title="linear axis" 
                    minimum="40" 
                    maximum="50" 
                    interval="1"/>
            </mx:verticalAxis>

            <mx:horizontalAxis>        
                <mx:CategoryAxis categoryField="date"/>
            </mx:horizontalAxis>

            <mx:series>
                <mx:LineSeries 
                    yField="close" 
                    displayName="FRED close"/>
            </mx:series>
        </mx:LineChart>
        <mx:Legend dataProvider="{myChart}"/>
    </s:Panel>
</s:Application>

The executing SWF file for the previous example is shown below:

In this example, the minimum value displayed along the y‑axis is 10, the maximum value is 100, and the interval is 10. Therefore, the label text is 10, 20, 30, 40, and so on.

To set the minimum and maximum values on a DateTimeAxis, you must use Date objects rather than Strings or Numbers in the axis’s tag. For more information, see Setting minimum and maximum values on a DateTimeAxis.

For information about setting the length and location of tick marks, see Formatting tick marks.