Adobe® Flex® 4 Language Reference
Hide Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
mx.charts 
CategoryAxis 
Packagemx.charts
Classpublic class CategoryAxis
InheritanceCategoryAxis Inheritance AxisBase Inheritance EventDispatcher Inheritance Object
Implements IAxis

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

The CategoryAxis class lets charts represent data grouped by a set of discrete values along an axis. You typically use the CategoryAxis class to define a set of labels that appear along an axis of a chart. For example, charts that render data according to City, Year, Business unit, and so on.

You are not required to explicitly set the dataProvider property on a CategoryAxis. A CategoryAxis used in a chart inherits its dataProvider property from the containing chart.

While you can use the same data provider to provide data to the chart and categories to the CategoryAxis, a CategoryAxis can optimize rendering if its data provider is relatively static. If possible, ensure that the categories are relatively static and that changing data is stored in separate data providers.

The dataProvider property can accept either an array of strings or an array of records (Objects) with a property that specifies the category name. If you specify a categoryField property, the CategoryAxis assumes that the data provider is an array of Objects. If the value of the categoryField property is null, the CategoryAxis assumes that the data provider is an array of Strings.

MXML SyntaxexpandedHide MXML Syntax

The <mx:CategoryAxis> tag inherits all the properties of its parent classes and adds the following properties:

  <mx:CategoryAxis
    Properties
    categoryField="null"
    dataFunction="No default"
    dataProvider="No default"
    labelFunction="No default"
    padding="Default depends on chart type"
    ticksBetweenLabels="true"
  />
  

View the examples

See also



Public Properties
 PropertyDefined By
  baseline : Number
[read-only] The baseline position for the axis.
CategoryAxis
  categoryField : String
Specifies the field of the data provider containing the text for the labels.
CategoryAxis
 InheritedchartDataProvider : Object
[write-only] The data provider assigned to the enclosing chart.
AxisBase
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  dataFunction : Function
Specifies a method that returns the value that should be used as categoryValue for current item.If this property is set, the return value of the custom data function takes precedence over categoryField The custom dataFunction has the following signature: function_name (axis:CategoryAxis, item:Object):Object { ...
CategoryAxis
  dataProvider : Object
Specifies the data source containing the label names.
CategoryAxis
 InheriteddisplayName : String
The name of the axis.
AxisBase
  labelFunction : Function
Specifies a function that defines the labels that are generated for each item in the CategoryAxis's dataProvider.
CategoryAxis
  padding : Number
Specifies the padding added to either side of the axis when rendering data on the screen.
CategoryAxis
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  ticksBetweenLabels : Boolean
Specifies the location of major tick marks on the axis, relative to the category labels.
CategoryAxis
 Inheritedtitle : String
The text for the title displayed along the axis.
AxisBase
 InheritedunitSize : Number
[read-only] The size of one unit of data as represented by this axis.
AxisBase
Public Methods
 MethodDefined By
  
Constructor.
CategoryAxis
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
EventDispatcher
 Inherited
Triggers events that inform the range object when the chart data has changed.
AxisBase
 Inherited
Dispatches an event into the event flow.
EventDispatcher
  
filterCache(cache:Array, field:String, filteredField:String):void
Filters a set of values of arbitrary type to a set of numbers that can be mapped.
CategoryAxis
  
Formats values for display in DataTips.
CategoryAxis
  
Determines the range to estimate what the axis labels should be.
CategoryAxis
  
getLabels(minimumAxisLength:Number):AxisLabelSet
Gets the labels text that is rendered.
CategoryAxis
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
  
Maps a position along the axis back to a numeric data value.
CategoryAxis
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
mapCache(cache:Array, field:String, convertedField:String, indexValues:Boolean = false):void
Converts a set of values of arbitrary type to a set of numbers that can be transformed into screen coordinates.
CategoryAxis
  
Determines how the axis handles overlapping labels.
CategoryAxis
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
  
reduceLabels(intervalStart:AxisLabel, intervalEnd:AxisLabel):AxisLabelSet
Invoked when an AxisRenderer is unable to cleanly render the labels without overlap, and would like the Axis object to reduce the set of labels.
CategoryAxis
 Inherited
Each DataTransform that makes use of an axis registers itself with that axis.
AxisBase
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
  
transformCache(cache:Array, field:String, convertedField:String):void
Maps a set of values from data space to screen space.
CategoryAxis
 Inherited
Each DataTransform that makes use of an axis registers itself with that axis.
AxisBase
  
Updates the chart.
CategoryAxis
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Protected Methods
 MethodDefined By
 Inherited
describeData(requiredFields:uint):Array
Called by the governing DataTransform to obtain a description of the data represented by this IChartElement.
AxisBase
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
Property Detail

baseline

property
baseline:Number  [read-only]

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

The baseline position for the axis. Some series, such as ColumnSeries or AreaSeries, use this value to define the base of a filled region when no minimum value is specified.



Implementation
    public function get baseline():Number

categoryField

property 
categoryField:String

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Specifies the field of the data provider containing the text for the labels. If this property is null, CategoryAxis assumes that the dataProvider contains an array of Strings.

The default value is null.



Implementation
    public function get categoryField():String
    public function set categoryField(value:String):void

dataFunction

property 
dataFunction:Function

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Specifies a method that returns the value that should be used as categoryValue for current item.If this property is set, the return value of the custom data function takes precedence over categoryField

The custom dataFunction has the following signature:

     function_name (axis:CategoryAxis, item:Object):Object { ... }
     
axis is the current axis that uses this dataFunction item is the item in the dataProvider that is considered. This function returns an object.

An example usage of a customized dataFunction is to return a value from a dataProvider that has items with nested fields



Implementation
    public function get dataFunction():Function
    public function set dataFunction(value:Function):void

Example
How to use this example
     public function myFunction(axis:CategoryAxis,item:Object):Object {
          return(item.Country.State);
     }     
     

dataProvider

property 
dataProvider:Object

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Specifies the data source containing the label names. The dataProvider can be an Array of Strings, an Array of Objects, or any object that implements the IList or ICollectionView interface. If the dataProvider is an Array of Strings, ensure that the categoryField property is set to null. If the dataProvider is an Array of Objects, set the categoryField property to the name of the field that contains the label text.



Implementation
    public function get dataProvider():Object
    public function set dataProvider(value:Object):void

labelFunction

property 
labelFunction:Function

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Specifies a function that defines the labels that are generated for each item in the CategoryAxis's dataProvider. If no labelFunction is provided, the axis labels default to the value of the category itself.

The labelFunction method for a CategoryAxis has the following signature:

      function function_name(categoryValue:Object, previousCategoryValue:Object, axis:CategoryAxis, categoryItem:Object):String { ... }
      

Where:

  • categoryValue is the value of the category to be represented.
  • previousCategoryValue is the value of the previous category on the axis.
  • axis is the CategoryAxis being rendered.
  • categoryItem is the item from the dataProvider that is being represented.

Flex displays the returned String as the axis label.

If the categoryField property is not set, the value will be the same as the categoryValue property.



Implementation
    public function get labelFunction():Function
    public function set labelFunction(value:Function):void

padding

property 
padding:Number

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Specifies the padding added to either side of the axis when rendering data on the screen. Set to 0 to map the first category to the very beginning of the axis and the last category to the end. Set to 0.5 to leave padding of half the width of a category on the axis between the beginning of the axis and the first category and between the last category and the end of the axis.

This is useful for chart types that render beyond the bounds of the category, such as columns and bars. However, when used as the horizontalAxis in a LineChart or AreaChart, it is reset to 0.

The default value is 0.5.



Implementation
    public function get padding():Number
    public function set padding(value:Number):void

ticksBetweenLabels

property 
ticksBetweenLabels:Boolean

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Specifies the location of major tick marks on the axis, relative to the category labels. If true, tick marks (and any associated grid lines) appear between the categories. If false, tick marks appear in the middle of the category, aligned with the label.



Implementation
    public function get ticksBetweenLabels():Boolean
    public function set ticksBetweenLabels(value:Boolean):void
Constructor Detail

CategoryAxis

()Constructor
public function CategoryAxis()

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Constructor.

Method Detail

filterCache

()method
public function filterCache(cache:Array, field:String, filteredField:String):void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Filters a set of values of arbitrary type to a set of numbers that can be mapped.

Parameters

cache:Array — An Array of objects where converted values are read from and stored.
 
field:String — The field of the objects in the cache Array containing the pre-filtered values.
 
filteredField:String — The field of the objects in the cache Array where filtered values should be stored.

formatForScreen

()method 
public function formatForScreen(value:Object):String

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Formats values for display in DataTips. Returns a user-readable string.

Parameters

value:Object — The value to convert to a String.

Returns
String — The text of the DataTip.

getLabelEstimate

()method 
public function getLabelEstimate():AxisLabelSet

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Determines the range to estimate what the axis labels should be. The axis almost immediately calls the getLabels() method to get the real values. The axis uses the estimated values to adjust chart margins, so any difference between the estimated labels and actual labels (returned from the getLabels() method) results in scaling the labels to fit.

An axis need only return the minimum and maximum labels when returning an estimate. If the label set is fairly static, without depending on the size of the axis being rendered on screen, an axis can return the entire label set from this function, and mark the estimate as accurate.

Returns
AxisLabelSet — An Array of AxisLabel objects.

getLabels

()method 
public function getLabels(minimumAxisLength:Number):AxisLabelSet

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Gets the labels text that is rendered. When Flex calls this method, the axis has already determined the minimum length of the label.

Parameters

minimumAxisLength:Number — The minimum length of the axis, in pixels. The axis can be longer than this value, but not shorter.

Returns
AxisLabelSet — An array of AxisLabel objects.

invertTransform

()method 
public function invertTransform(value:Number):Object

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Maps a position along the axis back to a numeric data value.

Parameters

value:Number — The bound of the axis. This parameter should be between 0 and 1, with 0 representing the minimum bound of the axis, and 1 the maximum.

Returns
Object — An object containing the transformed value.

mapCache

()method 
public function mapCache(cache:Array, field:String, convertedField:String, indexValues:Boolean = false):void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Converts a set of values of arbitrary type to a set of numbers that can be transformed into screen coordinates.

Parameters

cache:Array — An Array of objects where converted values are read from and stored.
 
field:String — The field of the objects in the cache Array containing the pre-converted values.
 
convertedField:String — The field of the objects in the cache Array where converted values should be stored.
 
indexValues:Boolean (default = false) — This parameter is true if the values being mapped are index values, and false if they are natural data values.

preferDropLabels

()method 
public function preferDropLabels():Boolean

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Determines how the axis handles overlapping labels. Typically, numeric ranges return true, while discrete value-based ranges do not. You can can override this property by setting it directly on the axis.

Returns
Booleantrue if labels can be dropped without loss of data; otherwise, false.

reduceLabels

()method 
public function reduceLabels(intervalStart:AxisLabel, intervalEnd:AxisLabel):AxisLabelSet

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Invoked when an AxisRenderer is unable to cleanly render the labels without overlap, and would like the Axis object to reduce the set of labels. The method is passed the two labels that are overlapping.

Parameters

intervalStart:AxisLabel — The start of the interval where labels overlap.
 
intervalEnd:AxisLabel — The end of the interval where labels overlap.

Returns
AxisLabelSet — A new label set that resolves the overlap by reducing the number of labels.

transformCache

()method 
public function transformCache(cache:Array, field:String, convertedField:String):void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Maps a set of values from data space to screen space.

Parameters

cache:Array — An Array of objects where mapped values are read from and stored.
 
field:String — The field of the objects in the cache Array containing the pre-mapped values.
 
convertedField:String — The field of the objects in the cache Array where mapped values should be stored.

update

()method 
public function update():void

Language Version: ActionScript 3.0
Product Version: Flex 3
Runtime Versions: Flash Player 9, AIR 1.1

Updates the chart. This can be called multiple times per frame.

HLOCChartExample.mxml
<?xml version="1.0"?>
<!-- Simple example to demonstrate the HLOCChart control. -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">
    <fx:Script>
        <![CDATA[          
        import mx.collections.ArrayCollection;

        [Bindable]
        private var stockDataAC:ArrayCollection = new ArrayCollection( [
            { Date: "25-Jul", Open: 40.55,  High: 40.75, Low: 40.24, Close:40.31},
            { Date: "26-Jul", Open: 40.15,  High: 40.78, Low: 39.97, Close:40.34},
            { Date: "27-Jul", Open: 40.38,  High: 40.66, Low: 40, Close:40.63},
            { Date: "28-Jul", Open: 40.49,  High: 40.99, Low: 40.3, Close:40.98},
            { Date: "29-Jul", Open: 40.13,  High: 40.4, Low: 39.65, Close:39.95},
            { Date: "1-Aug", Open: 39.00,  High: 39.50, Low: 38.7, Close:38.6}, 
            { Date: "2-Aug", Open: 38.68,  High: 39.34, Low: 37.75, Close:38.84}, 
            { Date: "3-Aug", Open: 38.76,  High: 38.76, Low: 38.03, Close:38.12}, 
            { Date: "4-Aug", Open: 37.98,  High: 37.98, Low: 36.56, Close:36.69},                       
            { Date: "5-Aug", Open: 36.61,  High: 37, Low: 36.48, Close:36.86} ]); 
        ]]>
    </fx:Script>

    <fx:Declarations>
        <!-- Define custom Stroke for the wick and ticks. -->
        <mx:SolidColorStroke id="s1" color="0x000000" weight="5" joints="bevel" caps="square"/>
    </fx:Declarations>

    <mx:Panel title="HLOCChart Control Example" height="100%" width="100%">
        <mx:HLOCChart id="hlocchart" height="100%" width="100%"
            paddingRight="5" paddingLeft="5" 
            showDataTips="true" dataProvider="{stockDataAC}">
            
            <mx:verticalAxis>
                <mx:LinearAxis id="vaxis" baseAtZero="false" title="Price"/>
            </mx:verticalAxis>

            <mx:horizontalAxis>
                <mx:CategoryAxis id="haxis" categoryField="Date" title="Date"/>
            </mx:horizontalAxis>

            <mx:horizontalAxisRenderers>
                <mx:AxisRenderer axis="{haxis}" canDropLabels="true"/>
            </mx:horizontalAxisRenderers>

            <mx:series>
                <mx:HLOCSeries 
                    openField="Open" 
                    highField="High" 
                    lowField="Low" 
                    closeField="Close"
                    stroke="{s1}"
                    openTickStroke="{s1}"
                    closeTickStroke="{s1}"
                    openTickLength="7"
                    closeTickLength="7"
                />
            </mx:series>
        </mx:HLOCChart>
    </mx:Panel>
</s:Application>