About the NumericAxis class
The NumericAxis class maps a set of continuous numerical values (such as sales volume, revenue, or profit) to coordinates on the screen. You do not typically use the NumericAxis base class directly. Instead, you use the following subclasses when you define your axis:
These classes give you significant control over how to set the appearance and values of elements such as labels and tick marks along the axis.
You can use the parseFunction property to specify a custom method that formats the data points in your chart. This property is supported by all subclasses of the NumericAxis class. For a detailed description of using this property with the DateTimeAxis, see Using the parseFunction property.
If you want to change the values of the labels, use the labelFunction property of the NumericAxis class. For more information, see Defining axis labels.
About the LinearAxis subclass
The LinearAxis subclass is the simplest of the three NumericAxis subclasses. It maps numeric values evenly between minimum and maximum values along a chart axis. By default, Flex determines the minimum, maximum, and interval values from the charting data to fit all of the chart elements on the screen. You can also explicitly set specific values for these properties. The following example sets the minimum and maximum values to 10 and 100, respectively:
<?xml version="1.0"?>
<!-- charts/LinearAxisSample.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script>
<![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
public var stocks:ArrayCollection = new ArrayCollection([
{date:"2005/8/4", SMITH:37.23},
{date:"2005/8/5", SMITH:56.53},
{date:"2005/8/6", SMITH:17.67},
{date:"2005/8/7", SMITH:27.72},
{date:"2005/8/8", SMITH:85.23}
]);
]]>
</mx:Script>
<mx:Panel title="LineChart control with a linear axis">
<mx:LineChart id="myChart"
dataProvider="{stocks}"
showDataTips="true"
height="300"
width="400"
>
<mx:verticalAxis>
<mx:LinearAxis
title="linear axis"
minimum="10"
maximum="100"
interval="10"
/>
</mx:verticalAxis>
<mx:horizontalAxis>
<mx:CategoryAxis categoryField="date"/>
</mx:horizontalAxis>
<mx:series>
<mx:LineSeries
yField="SMITH"
displayName="SMITH close"
/>
</mx:series>
</mx:LineChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
About the LogAxis subclass
The LogAxis subclass is similar to the LinearAxis subclass, but it maps values to the axis logarithmically rather than linearly. You use a LogAxis object when the data in your chart has such a wide range that clusters of data points are lost to scale. LogAxis data also cannot be rendered if it is negative. For example, if you track the stock price of a successful company since 1929, it is useful to represent the data logarithmically rather than linearly so that the chart is readable.
When you use a LogAxis object, you set a multiplier that defines the values of the labels along the axis. You set the multiplier with the interval property. Values must be even powers of 10, and must be greater than or equal to 0. A value of 10 generates labels at 1, 10, 100, and 1000. A value of 100 generates labels at 1, 100, and 10,000. The default value of the interval property is 10. The LogAxis object rounds the interval to an even power of 10, if necessary.
As with the vertical and horizontal axes, you can also set the minimum and maximum values of a LogAxis object, as the following example shows:
<?xml version="1.0"?>
<!-- charts/LogAxisSample.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script>
<![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
public var stocks:ArrayCollection = new ArrayCollection([
{date:"2005/8/4", SMITH:37.23, DECKER:1500},
{date:"2005/8/5", SMITH:56.53, DECKER:1210},
{date:"2005/8/6", SMITH:17.67, DECKER:1270},
{date:"2005/8/7", SMITH:27.72, DECKER:1370},
{date:"2005/8/8", SMITH:85.23, DECKER:1530}
]);
]]>
</mx:Script>
<mx:Panel title="LineChart control with a logarithmic axis">
<mx:LineChart id="myChart"
dataProvider="{stocks}"
showDataTips="true"
height="300"
width="400"
>
<mx:verticalAxis>
<mx:LogAxis title="log axis"
interval="10"
minimum="10"
maximum="10000"
/>
</mx:verticalAxis>
<mx:horizontalAxis>
<mx:CategoryAxis categoryField="date"/>
</mx:horizontalAxis>
<mx:series>
<mx:LineSeries yField="DECKER" displayName="DECKER close"/>
<mx:LineSeries yField="SMITH" displayName="SMITH close" />
</mx:series>
</mx:LineChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
About the DateTimeAxis subclass
The DateTimeAxis subclass maps time-based values to a chart axis. The DateTimeAxis subclass calculates the minimum and maximum values to align with logical date and time units (for example, the nearest hour or the nearest week). The DateTimeAxis subclass also selects a time unit for the interval so that the chart renders a reasonable number of labels.
The dataUnits property of the DateTimeAxis subclass specifies how Flex should interpret the Date objects. Flex determines this property by default, but you can override it. To display data in terms of days, set the dataUnits property to days, as the following example shows:
<mx:DateTimeAxis dataUnits="days"/>
Valid values for the dataUnits property are milliseconds, seconds, minutes, hours, days, weeks, months, and years.
When assigning appropriate label units, a DateTimeAxis object does not assign any unit smaller than the units represented by the data. If the dataUnits property is set to days, the chart does not render labels for every hour, no matter what the minimum or maximum range is. To achieve this, you must set the value explicitly.
When using the DateTimeAxis class, you can filter out units when you set the dataUnits property to days. This lets you create a chart that shows a "work week" or some other configuration that omits certain days of the week. For more information, see Omitting days on a DateTimeAxis object.
Some series use the value of the dataUnits property to affect their rendering. Specifically, most columnar series (such as Column, Bar, Candlestick, and HLOC controls) use the value of dataUnits to determine how wide to render their columns. If, for example, the ColumnChart control's horizontal axis has its labels set to weeks and dataUnits set to days, the ColumnChart control renders each column at one-seventh the distance between labels.
Data points on the DateTimeAxis object support the Date, String, and Number data types.
- Date: If the value of the data point is an instance of a Date object, it already represents an absolute date-time value and needs no interpretation. To pass a Date object as a data value, use the parseFunction property of the DateTimeAxis subclass. The parseFunction property returns a Date object. For more information, see Using the parseFunction property.
- String: You can use any format that the Date.parse() method supports. The supported formats are:
- Day Month DD Hours:Minutes:Seconds GMT Year (for example, Tue Feb 1 12:00:00 GMT-0800 2005)
- Day Month DD YYYY Hours:Minutes:Seconds AM|PM (for example, Tue Feb 1 2005 12:00:00 AM)
- Day Month DD YYYY (for example, Tue Feb 1 2005)
- MM/DD/YYYY (for example, 02/01/2005)
You can also write custom logic that uses the parseFunction property of the DateTimeAxis to take any data type and return a Date. For more information, see Using the parseFunction property.
- Number: If you use a number, it is assumed to be the number of milliseconds since Midnight, 1/1/1970; for example, 543387600000. To get this value on an existing Date object, use the Date object's getTime() method.
The following example uses a String value for the date that matches the MM/DD/YYYY pattern and specifies that the dates are displayed in units of days:
<?xml version="1.0"?>
<!-- charts/DateTimeAxisSample.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="450" height="300">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection
[Bindable]
public var deck:ArrayCollection = new ArrayCollection([
{date:"08/01/2005", close:42.71},
{date:"08/02/2005", close:42.99},
{date:"08/03/2005", close:42.65}
]);
]]></mx:Script>
<mx:Panel title="Sample DateTimeAxis">
<mx:LineChart id="myChart"
dataProvider="{deck}"
showDataTips="true"
>
<mx:horizontalAxis>
<mx:DateTimeAxis dataUnits="days"/>
</mx:horizontalAxis>
<mx:series>
<mx:LineSeries
yField="close"
xField="date"
displayName="DECK"
/>
</mx:series>
</mx:LineChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
Using the parseFunction property
You use the parseFunction property of the DateTimeAxis object to specify a method that customizes the value of the data points. With this property, you specify a method that accepts a value and returns a Date object. The Date object is then used in the DateTimeAxis object of the chart. This lets you provide customizable input strings and convert them to Date objects, which Flex can then interpret for use in the DateTimeAxis.
The parsing method specified by the parseFunction property is called every time a value for the DateTimeAxis must be calculated. It is called each time a data point is encountered when the user interacts with the chart. Consequently, Flex might call the parsing method often, which can degrade an application's performance. Therefore, you should try to keep the amount of code in the parsing method to a minimum.
Flex passes only one parameter to the parsing method. This parameter is the value of the data point that you specified for the series. Typically, it is a String representing some form of a date. You cannot override this parameter or add additional parameters.
The following example shows a parsing method that creates a Date object from String values in the data provider that match the "YYYY, MM, DD" pattern:
<?xml version="1.0"?>
<!-- charts/DateTimeAxisParseFunction.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
public var ABC:ArrayCollection = new ArrayCollection([
{date:"2005, 8, 1", close:42.71},
{date:"2005, 8, 2", close:42.99},
{date:"2005, 8, 3", close:44}
]);
public function myParseFunction(s:String):Date {
// Get an array of Strings from the
// comma-separated String passed in.
var a:Array = s.split(",");
// Trace out year, month, and day values.
trace("y:" + a[0]);
trace("m:" + a[1]);
trace("d:" + a[2]);
// To create a Date object, you pass "YYYY,MM,DD",
// where MM is zero-based, to the Date() constructor.
var newDate:Date = new Date(a[0],a[1]-1,a[2]);
return newDate;
}
]]></mx:Script>
<mx:Panel title="DateTimeAxis with parseFunction">
<mx:LineChart id="myChart"
dataProvider="{ABC}"
showDataTips="true"
>
<mx:horizontalAxis>
<mx:DateTimeAxis
dataUnits="days"
parseFunction="myParseFunction"
/>
</mx:horizontalAxis>
<mx:series>
<mx:LineSeries
yField="close"
xField="date"
displayName="ABC"
/>
</mx:series>
</mx:LineChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
Formatting DateTimeAxis labels
When assigning the units to display along the axis, the DateTimeAxis object uses the largest unit allowed to render a reasonable number of labels. The following table describes the default label format and the minimum range for each unit type:
|
Unit |
Label format |
Minimum range |
|---|---|---|
|
Years |
YYYY |
If the minimum and maximum values span at least 2 years. |
|
Months |
MM/YY |
Spans at least 2 months. |
|
Weeks |
DD/MM/YY |
Spans at least 2 weeks. |
|
Days |
DD/MM/YY |
Spans at least 1 day. |
|
Hours |
HH:MM |
Spans at least 1 hour. |
|
Minutes |
HH:MM |
Spans at least 1 minute. |
|
Seconds |
HH:MM:SS |
Spans at least 1 second. |
|
Milliseconds |
HH:MM:SS:mmmm |
Spans at least 1 millisecond. |
You can restrict the list of valid units for a particular chart instance to a subset that makes sense for the use case. As with a LinearAxis object, you can specify minimum, maximum, and interval values for a DateTimeAxis object.
When rounding off values, the DateTimeAxis object determines if values passed to it should be displayed in the local time zone or UTC. You can set the displayLocalTime property to true to instruct the DateTimeAxis object to treat values as local time values. The default value is false.
To change the values of the labels, use the labelFunction property of the DateTimeAxis object. This property is inherited from the NumericAxis class and is described in Defining axis labels.
Setting minimum and maximum values on a DateTimeAxis
You can define the range of values that any axis uses by setting the values of the minimum and maximum properties on that axis. For the DateTimeAxis class, however, you must use Date objects and not Numbers or Strings to define that range. To do this, you create bindable Date objects and bind the values of the minimum and maximum properties to those objects.
When creating Date objects, remember that the month parameter in the constructor is zero-based. The following example sets the minimum date for the axis to the first day of December 2006, and the maximum date for the axis to the first day of February 2007. The result is that Flex excludes the first and last data points in the ArrayCollection because those dates fall outside of the range set on the axis:
<?xml version="1.0"?>
<!-- charts/DateTimeAxisRange.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="450"
height="300">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection;
// To create a Date object, you pass "YYYY,MM,DD",
// where MM is zero-based, to the Date() constructor.
[Bindable]
public var minDate:Date = new Date(2006, 11, 1);
[Bindable]
public var maxDate:Date = new Date(2007, 1, 1);
[Bindable] public var myData:ArrayCollection = new
ArrayCollection([
{date: "11/03/2006", amt: 12345},
{date: "12/02/2006", amt: 54331},
{date: "1/03/2007", amt: 34343},
{date: "2/05/2007", amt: 40299}
]);
]]></mx:Script>
<mx:Panel title="DateTimeAxis with range">
<mx:ColumnChart id="myChart"
dataProvider="{myData}"
showDataTips="true"
>
<mx:horizontalAxis>
<mx:DateTimeAxis
dataUnits="months"
minimum="{minDate}"
maximum="{maxDate}"
/>
</mx:horizontalAxis>
<mx:series>
<mx:ColumnSeries
yField="amt"
xField="date"
displayName="My Data"
/>
</mx:series>
</mx:ColumnChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
You can also represent the range of dates in MXML by using the following syntax:
<mx:horizontalAxis>
<mx:DateTimeAxis dataUnits="months">
<mx:minimum>
<mx:Date fullYear="2005" month="11" date="1"/>
</mx:minimum>
<mx:maximum>
<mx:Date fullYear="2007" month="1" date="1"/>
</mx:maximum>
</mx:DateTimeAxis>
</mx:horizontalAxis>
Omitting days on a DateTimeAxis object
You can exclude particular days or ranges of days from a chart. This lets you create charts that show only the days of the work week or that exclude other days of the week for other reasons.
For example, if you create a LineChart control that shows a stock price over the course of an entire month, the source data typically includes pricing data only for Monday through Friday. Values for the weekend days are typically not in the data. So, the chart control extrapolates values by extending the line through the weekend days on the chart, which makes it appear as though there is data for those days. If you disable the weekend days, the chart control removes those days from the chart and the line draws only the days that are not disabled. There is no breakage or other indicator that there are omitted days.
To disable days of the week or ranges of days in your charts, you must set the dataUnits property of the DateTimeAxis object to days. You then use the disabledDays or disabledRanges properties of the DateTimeAxis object.
The value of the disabledDays property of DateTimeAxis is an Array of numbers. These numbers correspond to days of the week, with 0 being Sunday, 1 being Monday, and so on, up until 6 being Saturday.
The following example excludes Saturdays and Sundays from the chart by setting the value of the disabledDays property to an Array that contains 0 and 6:
<?xml version="1.0"?>
<!-- charts/WorkWeekAxis.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="450" height="300">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection
[Bindable]
public var deck:ArrayCollection = new ArrayCollection([
{date:"08/01/2007", close:42},
{date:"08/02/2007", close:43},
{date:"08/03/2007", close:43},
{date:"08/06/2007", close:42},
{date:"08/07/2007", close:38},
{date:"08/08/2007", close:37},
{date:"08/09/2007", close:39},
{date:"08/10/2007", close:41},
{date:"08/13/2007", close:45},
{date:"08/14/2007", close:47},
{date:"08/15/2007", close:48},
{date:"08/16/2007", close:42},
{date:"08/17/2007", close:43},
{date:"08/20/2007", close:45},
{date:"08/21/2007", close:50},
{date:"08/22/2007", close:51},
{date:"08/23/2007", close:55},
{date:"08/24/2007", close:51},
{date:"08/27/2007", close:49},
{date:"08/28/2007", close:51},
{date:"08/29/2007", close:50},
{date:"08/30/2007", close:49},
{date:"08/31/2007", close:54}
]);
private function myParseFunction(s:String):Date {
var a:Array = s.split("/");
var newDate:Date = new Date(a[2],a[0]-1,a[1]);
return newDate;
}
/* Create an Array that specifies which days to exclude.
0 is Sunday and 6 is Saturday. */
[Bindable]
private var offDays:Array = [0,6];
]]></mx:Script>
<mx:Panel title="WorkWeekAxis Example">
<mx:LineChart id="myChart"
dataProvider="{deck}"
showDataTips="true"
>
<mx:horizontalAxis>
<mx:DateTimeAxis
dataUnits="days"
parseFunction="myParseFunction"
disabledDays="{offDays}"
/>
</mx:horizontalAxis>
<mx:series>
<mx:LineSeries
yField="close"
xField="date"
displayName="DECK"
/>
</mx:series>
</mx:LineChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
To exclude a range of dates from the DateTimeAxis object, you use the disabledRanges property. This property takes an Array of Date objects or date ranges. The following example excludes August 13, and then the range of days between August 27 and August 31:
<?xml version="1.0"?>
<!-- charts/DisabledDateRanges.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="100%"
height="100%" creationComplete="init()">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection
[Bindable]
public var deck:ArrayCollection = new ArrayCollection([
{date:"08/01/2007", close:42},
{date:"08/02/2007", close:43},
{date:"08/03/2007", close:43},
{date:"08/06/2007", close:42},
{date:"08/07/2007", close:38},
{date:"08/08/2007", close:37},
{date:"08/09/2007", close:39},
{date:"08/10/2007", close:41},
{date:"08/13/2007", close:45},
{date:"08/14/2007", close:47},
{date:"08/15/2007", close:48},
{date:"08/16/2007", close:42},
{date:"08/17/2007", close:43},
{date:"08/20/2007", close:45},
{date:"08/21/2007", close:50},
{date:"08/22/2007", close:51},
{date:"08/23/2007", close:55},
{date:"08/24/2007", close:51},
{date:"08/27/2007", close:49},
{date:"08/28/2007", close:51},
{date:"08/29/2007", close:50},
{date:"08/30/2007", close:49},
{date:"08/31/2007", close:54}
]);
private function myParseFunction(s:String):Date {
var a:Array = s.split("/");
var newDate:Date = new Date(a[2],a[0]-1,a[1]);
return newDate;
}
private var d1:Date, d2:Date, d3:Date;
[Bindable]
private var offRanges:Array = new Array ([]);
private function init():void {
d1 = new Date("08/13/2007");
d2 = new Date("08/27/2007");
d3 = new Date("08/31/2007");
offRanges = [ d1, {rangeStart:d2, rangeEnd:d3} ];
}
private var series1:LineSeries;
]]></mx:Script>
<mx:Panel title="Disabled Date Ranges">
<mx:LineChart id="myChart"
dataProvider="{deck}"
showDataTips="true"
>
<mx:horizontalAxis>
<mx:DateTimeAxis
dataUnits="days"
parseFunction="myParseFunction"
disabledRanges="{offRanges}"
/>
</mx:horizontalAxis>
<mx:series>
<mx:LineSeries
id="mySeries"
yField="close"
xField="date"
displayName="DECK"
/>
</mx:series>
</mx:LineChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
The following example expands on the previous example, except it adds a DateChooser control. You can select days on the DateChooser that are then removed from the chart.
<?xml version="1.0"?>
<!-- charts/DisabledDateRangesWithDateChooser.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="100%"
height="100%" creationComplete="init()">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
public var deck:ArrayCollection = new ArrayCollection([
{date:"08/01/2007", close:42},
{date:"08/02/2007", close:43},
{date:"08/03/2007", close:43},
{date:"08/06/2007", close:42},
{date:"08/07/2007", close:38},
{date:"08/08/2007", close:37},
{date:"08/09/2007", close:39},
{date:"08/10/2007", close:41},
{date:"08/13/2007", close:45},
{date:"08/14/2007", close:47},
{date:"08/15/2007", close:48},
{date:"08/16/2007", close:42},
{date:"08/17/2007", close:43},
{date:"08/20/2007", close:45},
{date:"08/21/2007", close:50},
{date:"08/22/2007", close:51},
{date:"08/23/2007", close:55},
{date:"08/24/2007", close:51},
{date:"08/27/2007", close:49},
{date:"08/28/2007", close:51},
{date:"08/29/2007", close:50},
{date:"08/30/2007", close:49},
{date:"08/31/2007", close:54}
]);
// Define weekend days to be removed from chart.
[Bindable]
private var offDays:Array = [0,6];
[Bindable]
private var dateChooserDisabledRanges:Array = [];
private function init():void {
// Limit selectable range to August of 2007 on DateChooser.
dateChooserDisabledRanges = [
{rangeEnd: new Date(2007, 6, 31)},
{rangeStart: new Date(2007, 8, 1)}
];
// Disable weekend days on DateChooser.
dc1.disabledDays = [0, 6];
}
[Bindable]
private var offRanges:Array = new Array([]);
private function onDateChange(e:Event):void {
// Get the start and end date of the range.
var startDate:Date = e.currentTarget.selectedRanges[0].rangeStart;
var endDate:Date = e.currentTarget.selectedRanges[0].rangeEnd;
var d:Object = {rangeStart:startDate, rangeEnd:endDate};
// Add object to list of ranges to disable on chart.
offRanges.push(d);
// Refresh the chart series with the new offRanges.
var mySeries:Array = [];
mySeries.push(series1);
myChart.series = mySeries;
// Show the current ranges.
ta1.text = "";
for (var i:int = 0; i < offRanges.length; i++) {
for (var s:String in offRanges[i]) {
ta1.text += s + ":" + offRanges[i][s] + "\n";
}
}
}
private function clearAllDisabledDates():void {
offRanges = [];
dc1.selectedDate = null;
ta1.text = "";
}
]]></mx:Script>
<mx:Panel title="Disabled data ranges">
<mx:HBox>
<mx:LineChart id="myChart"
dataProvider="{deck}"
showDataTips="true"
>
<mx:horizontalAxis>
<mx:DateTimeAxis
id="dtAxis"
dataUnits="days"
disabledDays="{offDays}"
disabledRanges="{offRanges}"
/>
</mx:horizontalAxis>
<mx:verticalAxis>
<mx:LinearAxis minimum="30" maximum="60"/>
</mx:verticalAxis>
<mx:series>
<mx:LineSeries
id="series1"
yField="close"
xField="date"
displayName="DECK"
/>
</mx:series>
</mx:LineChart>
<mx:DateChooser id="dc1"
showToday="false"
click="onDateChange(event)"
displayedMonth="7"
displayedYear="2007"
disabledRanges="{dateChooserDisabledRanges}"
/>
</mx:HBox>
<mx:Legend dataProvider="{myChart}"/>
<mx:Button id="b1" label="Refresh" click="clearAllDisabledDates()"/>
<mx:TextArea id="ta1" width="600" height="400"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below: