Apache Flex 4.16.1 API Reference | All Packages | All Classes | Index | Frames No Frames |
CategoryAxis

Package | mx.charts
Class | public class CategoryAxis
Inheritance | CategoryAxis AxisBase flash.events.EventDispatcher
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 Syntax Show MXML Syntax
Hide 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

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined 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
|  | chartDataProvider : Object [write-only] The data provider assigned to the enclosing chart. | AxisBase
|  | 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
|  | displayName : 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
|  | ticksBetweenLabels : Boolean Specifies the location of major tick marks on the axis, relative to the category labels. | CategoryAxis
|  | title : String The text for the title displayed along the axis. | AxisBase
|  | unitSize : Number [read-only] The size of one unit of data as represented by this axis. | AxisBase

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | CategoryAxis() Constructor. | CategoryAxis
|  | dataChanged():void Triggers events that inform the range object when the chart data has changed. | AxisBase
|  | 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
|  | formatForScreen(value:Object):String Formats values for display in DataTips. | CategoryAxis
|  | getLabelEstimate():AxisLabelSet Determines the range to estimate what the axis labels should be. | CategoryAxis
|  | getLabels(minimumAxisLength:Number):AxisLabelSet Gets the labels text that is rendered. | CategoryAxis
|  | invertTransform(value:Number):Object Maps a position along the axis back to a numeric data value. | CategoryAxis
|  | 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
|  | preferDropLabels():Boolean Determines how the axis handles overlapping labels. | CategoryAxis
|  | 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
|  | registerDataTransform(transform:DataTransform, dimensionName:String):void Each DataTransform that makes use of an axis registers itself with that axis. | AxisBase
|  | transformCache(cache:Array, field:String, convertedField:String):void Maps a set of values from data space to screen space. | CategoryAxis
|  | unregisterDataTransform(transform:DataTransform):void Each DataTransform that makes use of an axis registers itself with that axis. | AxisBase
|  | update():void Updates the chart. | CategoryAxis

Protected Methods
Show Inherited Protected Methods
Show Inherited Protected Methods

| Method | Defined By
--- | --- | ---
|  | describeData(requiredFields:uint):Array Called by the governing DataTransform to obtain a description of the data represented by this IChartElement. | AxisBase

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

         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

| `Boolean` — `true` 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.

Examples
HLOCChartExample.mxml

    <?xml version="1.0"?>
    <!--

      Licensed to the Apache Software Foundation (ASF) under one or more
      contributor license agreements.  See the NOTICE file distributed with
      this work for additional information regarding copyright ownership.
      The ASF licenses this file to You under the Apache License, Version 2.0
      (the "License"); you may not use this file except in compliance with
      the License.  You may obtain a copy of the License at

          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

    -->
    <!-- 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>

Wed Nov 15 2017, 09:50 AM +01:00