Using DataTip objects
The values displayed in the DataTip depends on the chart type, but typically it displays the names of the fields and the values of the data from the data provider.
The following image shows a simple DataTip:
To enable DataTip objects, set the value of the chart control's showDataTips property to true, as the following example shows:
<?xml version="1.0"?>
<!-- charts/EnableDataTips.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
public var expenses:ArrayCollection = new ArrayCollection([
{Month:"Jan", Profit:2000, Expenses:1500},
{Month:"Feb", Profit:1000, Expenses:200},
{Month:"Mar", Profit:1500, Expenses:500}
]);
]]></mx:Script>
<mx:Panel title="Bar Chart">
<mx:BarChart id="myChart"
dataProvider="{expenses}"
showDataTips="true"
>
<mx:verticalAxis>
<mx:CategoryAxis
dataProvider="{expenses}"
categoryField="Month"
/>
</mx:verticalAxis>
<mx:series>
<mx:BarSeries
yField="Month"
xField="Profit"
displayName="Profit"
/>
<mx:BarSeries
yField="Month"
xField="Expenses"
displayName="Expenses"
/>
</mx:series>
</mx:BarChart>
</mx:Panel>
<mx:Legend dataProvider="{myChart}"/>
</mx:Application>
The executing SWF file for the previous example is shown below:
To change the styles of the DataTip, you can use the DataTip type selector in an <mx:Style> block or in an external CSS file. The following example applies a new style to the text in the DataTip:
<?xml version="1.0"?>
<!-- charts/DataTipStyles.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Style>
DataTip {
fontFamily: "Arial";
fontSize: 12;
fontWeight:bold;
fontStyle:italic;
}
</mx:Style>
<mx:Script><![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
public var expenses:ArrayCollection = new ArrayCollection([
{Month:"Jan", Profit:2000, Expenses:1500},
{Month:"Feb", Profit:1000, Expenses:200},
{Month:"Mar", Profit:1500, Expenses:500}
]);
]]></mx:Script>
<mx:Panel title="Bar Chart">
<mx:BarChart id="myChart"
dataProvider="{expenses}"
showDataTips="true"
>
<mx:verticalAxis>
<mx:CategoryAxis
dataProvider="{expenses}"
categoryField="Month"
/>
</mx:verticalAxis>
<mx:series>
<mx:BarSeries
yField="Month"
xField="Profit"
displayName="Profit"
/>
<mx:BarSeries
yField="Month"
xField="Expenses"
displayName="Expenses"
/>
</mx:series>
</mx:BarChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
Customizing the text inside a DataTip object
To make the information in the DataTip more understandable to users, you can define the series of your chart with names that are easily understood. Adobe® Flash® Player or Adobe® AIR™ displays this name in the DataTip, as the following image shows:
The following example names the data series by using the displayName property of the series:
<?xml version="1.0"?>
<!-- charts/DataTipsDisplayName.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
public var expenses:ArrayCollection = new ArrayCollection([
{Month:"Jan", Profit:2000, Expenses:1500},
{Month:"Feb", Profit:1000, Expenses:200},
{Month:"Mar", Profit:1500, Expenses:500}
]);
]]></mx:Script>
<mx:Panel title="Bar Chart">
<mx:BarChart id="myChart"
dataProvider="{expenses}"
showDataTips="true"
>
<mx:verticalAxis>
<mx:CategoryAxis
dataProvider="{expenses}"
categoryField="Month"
/>
</mx:verticalAxis>
<mx:series>
<mx:BarSeries
yField="Month"
xField="Profit"
displayName="Profit"
/>
<mx:BarSeries
yField="Month"
xField="Expenses"
displayName="Expenses"
/>
</mx:series>
</mx:BarChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
You can also name the axis to display labels in the DataTip by using the displayName property. When the axis has a name, this name appears in the DataTip in italic font before the label data, as the following image shows:
In some cases, you add an axis solely for the purpose of adding the label to the DataTip. The following example names both axes so that both data points are labeled in the DataTip:
<?xml version="1.0"?>
<!-- charts/DataTipsAxisNames.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
public var expenses:ArrayCollection = new ArrayCollection([
{Month:"Jan", Profit:2000, Expenses:1500},
{Month:"Feb", Profit:1000, Expenses:200},
{Month:"Mar", Profit:1500, Expenses:500}
]);
]]></mx:Script>
<mx:Panel title="Bar Chart">
<mx:BarChart id="myChart"
dataProvider="{expenses}"
showDataTips="true"
>
<mx:verticalAxis>
<mx:CategoryAxis
dataProvider="{expenses}"
categoryField="Month"
displayName="Month"
/>
</mx:verticalAxis>
<mx:horizontalAxis>
<mx:LinearAxis displayName="Amount"/>
</mx:horizontalAxis>
<mx:series>
<mx:BarSeries
yField="Month"
xField="Profit"
displayName="Profit"
/>
<mx:BarSeries
yField="Month"
xField="Expenses"
displayName="Expenses"
/>
</mx:series>
</mx:BarChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
Showing multiple DataTip objects
You can display more than one DataTip by using the dataTipMode property on the chart control. The display options are single and multiple. When dataTipMode is set to multiple, the chart displays all DataTip objects within range of the cursor. The following example sets the value of a ColumnChart control's dataTipMode property to multiple:
<?xml version="1.0"?>
<!-- charts/DataTipsMultiple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
public var expenses:ArrayCollection = new ArrayCollection([
{Month:"Jan", Profit:2000, Expenses:1500},
{Month:"Feb", Profit:1000, Expenses:200},
{Month:"Mar", Profit:1500, Expenses:500}
]);
]]></mx:Script>
<mx:Panel title="Bar Chart">
<mx:BarChart id="myChart"
dataProvider="{expenses}"
showDataTips="true"
mouseSensitivity="50"
dataTipMode="multiple"
>
<mx:verticalAxis>
<mx:CategoryAxis
dataProvider="{expenses}"
categoryField="Month"
/>
</mx:verticalAxis>
<mx:series>
<mx:BarSeries
yField="Month"
xField="Profit"
displayName="Profit"
/>
<mx:BarSeries
yField="Month"
xField="Expenses"
displayName="Expenses"
/>
</mx:series>
</mx:BarChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
The following example shows DataTip objects when the dataTipMode property is set to multiple:
The default value of dataTipMode depends on the chart type. Its setting is based on the likelihood that there are overlapping DataTip objects in that chart type. The default value of the dataTipMode property for the following chart types is single:
The default value is multiple for the dataTipMode property for all other chart types.
To determine the size of the interactive area around a data point, you set the mouseSensitivity property. The mouseSensitivity property configures the distance, in pixels, around the data points where Flex reacts to mouse events such as click and mouseOver. With this property, you can trigger DataTip objects to appear when the user moves the mouse pointer near the data point rather than onto the data point. For more information, see Changing mouse sensitivity.
You can also show all the available data tips on a chart at one time by setting the value of the chart control's showAllDataTips property to true. The result is that all data tips are visible at all times. When you do this, you typically set the value of the showDataTips property to false so that a second data tip does not appear when you mouse over a chart item.
Customizing DataTip values
You can customize the text displayed in a DataTip by using the dataTipFunction callback function. When you specify a dataTipFunction callback function, you can access the data of the DataTip before Flex renders it and customizes the text.
The argument to the callback function is a HitData object. As a result, you must import mx.charts.HitData when using a DataTip callback function.
Flex displays whatever the callback function returns in the DataTip box. You must specify a String as the callback function's return type.
The following example defines a new callback function, dtFunc, that returns a formatted value for the DataTip:
<?xml version="1.0"?>
<!-- charts/CustomDataTips.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
<mx:Script><![CDATA[
import mx.charts.HitData;
import mx.collections.ArrayCollection;
[Bindable]
public var expenses:ArrayCollection = new ArrayCollection([
{Month:"Jan", Profit:2000, Expenses:1500},
{Month:"Feb", Profit:1000, Expenses:200},
{Month:"Mar", Profit:1500, Expenses:500}
]);
public function dtFunc(hd:HitData):String {
return hd.item.Month + ":<B>$" +
hd.item.Profit + "</B>";
}
]]></mx:Script>
<mx:Panel title="Bar Chart">
<mx:BarChart id="myChart"
dataProvider="{expenses}"
showDataTips="true"
dataTipFunction="dtFunc"
>
<mx:verticalAxis>
<mx:CategoryAxis
dataProvider="{expenses}"
categoryField="Month"
displayName="Month"
/>
</mx:verticalAxis>
<mx:horizontalAxis>
<mx:LinearAxis displayName="Amount"/>
</mx:horizontalAxis>
<mx:series>
<mx:BarSeries
yField="Month"
xField="Profit"
displayName="Profit"
/>
<mx:BarSeries
yField="Month"
xField="Expenses"
displayName="Expenses"
/>
</mx:series>
</mx:BarChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
You can also use the HitData object to get information about the series in which that data item appears. To do this, you cast the HitData object to a Series class, as the following example shows:
<?xml version="1.0"?>
<!-- charts/HitDataCasting.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize=
"init()">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection;
import mx.charts.HitData;
import mx.charts.series.ColumnSeries;
[Bindable]
public var dataSet:ArrayCollection = new ArrayCollection([
{Month:"Jan", Expenses:1500, Income:1590},
{Month:"Feb", Expenses:1200, Income:1300},
{Month:"Mar", Expenses:750, Income:900}
]);
public var b:Boolean = true;
public function myDataTipFunction(e:HitData):String {
var s:String;
s = ColumnSeries(e.element).displayName + "\n";
s += "Profit: $" + (e.item.Income - e.item.Expenses);
return s;
}
]]></mx:Script>
<mx:Panel title="Casting HitData Objects">
<mx:ColumnChart id="myChart"
dataProvider="{dataSet}"
showDataTips="true"
dataTipFunction="myDataTipFunction"
>
<mx:horizontalAxis>
<mx:CategoryAxis categoryField="Month"/>
</mx:horizontalAxis>
<mx:series>
<mx:ColumnSeries
yField="Expenses"
displayName="Expenses '06"
/>
<mx:ColumnSeries
yField="Income"
displayName="Income '06"
/>
</mx:series>
</mx:ColumnChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
The series item is also accessible from the HitData object in a custom DataTip function. The chartItem property refers to an instance of a subclass of the ChartItem class. The type depends on the series type; for example, the chartItem for a ColumnSeries is an instance of the ColumnSeriesItem class.
In the following example, the yValue of the ColumnSeriesItem represents the percentage which a series takes up in a 100% chart:
<?xml version="1.0"?>
<!-- charts/HitDataCastingWithPercent.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" initialize=
"init()">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection;
import mx.charts.HitData;
import mx.charts.series.ColumnSeries;
import mx.charts.series.items.ColumnSeriesItem;
[Bindable]
public var dataSet:ArrayCollection = new ArrayCollection([
{Month:"Jan", Income:1500, Profit:90},
{Month:"Feb", Income:1200, Profit:100},
{Month:"Mar", Income:750, Profit:150}
]);
public var b:Boolean = true;
public function myDataTipFunction(e:HitData):String {
var s:String;
s = "<B>" + ColumnSeries(e.element).displayName + "</B>\n";
s += "<I>Income:</I> <FONT COLOR='#339966'>$" +
e.item.Income + "</FONT>\n";
s += "<I>Expenses:</I> <FONT COLOR='#FF0000'>$" +
(e.item.Income - e.item.Profit) + "</FONT>\n";
s += "------------------------\n";
s += "<I>Profit:</I> $" + e.item.Profit + "\n";
// The value of the Income will always be 100%,
// so exclude adding that to the DataTip. Only
// add percent when the user gets the Profit DataTip.
var percentValue:Number =
Number(ColumnSeriesItem(e.chartItem).yValue);
if (percentValue < 100) {
s += "Profit was equal to about <B>" +
Math.round(percentValue) + "</B>% of the income.\n";
}
return s;
//return e.item.Month + ":<B>$" + e.item.Profit + "</B>";
}
]]></mx:Script>
<mx:Panel title="Accessing ChartItems from HitData Objects">
<mx:ColumnChart id="myChart"
dataProvider="{dataSet}"
type="100%"
dataTipFunction="myDataTipFunction"
showDataTips="true"
>
<mx:horizontalAxis>
<mx:CategoryAxis categoryField="Month"/>
</mx:horizontalAxis>
<mx:series>
<mx:ColumnSeries
yField="Profit"
displayName="Profit '06"
/>
<mx:ColumnSeries
yField="Income"
displayName="Income '06"
/>
</mx:series>
</mx:ColumnChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
For more information on using the HitData object of chart events, see Using the HitData object.
The DataTip callback function can return simple HTML for formatted DataTip objects. Flex supports a small subset of HTML tags including <FONT>, <B>, <I>, and <BR>.
Creating custom DataTip renderers
You can create a custom class that defines the appearance and content of the data tip. This class must implement the IFlexDisplayObject and IDataRenderer interfaces.
You typically create a custom ActionScript class that extends DataTip, and override the createChildren() and updateDisplayList() methods. In the createChildren() method, you create an instance of the TextField class. In the updateDisplayList() method, you add text to the new text field, and you define the box for the data tip. The chart assigns the custom data tip's data property to be the HitData structure for the data point.
The following example class creates a custom data tip.
// charts/MyDataTip.as
package {
import mx.charts.chartClasses.DataTip;
import mx.charts.*;
import flash.display.*;
import flash.geom.Matrix;
import flash.text.TextField;
public class MyDataTip extends DataTip {
// The title is renderered in a TextField.
private var myText:TextField;
public function MyDataTip() {
super();
}
override protected function createChildren():void{
super.createChildren();
myText = new TextField();
}
override protected function updateDisplayList(w:Number, h:Number):void {
super.updateDisplayList(w, h);
// The data property provides access to the data tip's text.
if(data.hasOwnProperty('text')) {
myText.text = data.text;
} else {
myText.text = data.toString();
}
this.setStyle("textAlign","center");
var g:Graphics = graphics;
g.clear();
var m:Matrix = new Matrix();
m.createGradientBox(w+100,h,0,0,0);
g.beginGradientFill(GradientType.LINEAR,[0xFF0000,0xFFFFFF],
[.1,1],[0,255],m,null,null,0);
g.drawRect(-50,0,w+100,h);
g.endFill();
}
}
}
To use the custom data tip, you set the value of the dataTipRenderer style property of the chart control to the custom class. The following sample application applies the custom data tip to the chart control.
<?xml version="1.0"?>
<!-- charts/CustomDataTipRenderer.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" creationComplete="applyCustomDataTips()">
<mx:Script><![CDATA[
import mx.collections.ArrayCollection;
[Bindable]
public var expenses:ArrayCollection = new ArrayCollection([
{Month:"Jan", Profit:2000, Expenses:1500},
{Month:"Feb", Profit:1000, Expenses:200},
{Month:"Mar", Profit:1500, Expenses:500}
]);
private function applyCustomDataTips():void {
myChart.setStyle("dataTipRenderer",MyDataTip);
}
]]></mx:Script>
<mx:Panel title="Bar Chart">
<mx:BarChart id="myChart"
dataProvider="{expenses}"
showDataTips="true"
>
<mx:verticalAxis>
<mx:CategoryAxis
dataProvider="{expenses}"
categoryField="Month"
/>
</mx:verticalAxis>
<mx:series>
<mx:BarSeries
yField="Month"
xField="Profit"
displayName="Profit"
/>
<mx:BarSeries
yField="Month"
xField="Expenses"
displayName="Expenses"
/>
</mx:series>
</mx:BarChart>
<mx:Legend dataProvider="{myChart}"/>
</mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:
If you want to prevent the data tip's box from displaying when you mouse over a chart item, you can set the dataTipRenderer style property to a dummy class, such as ProgrammaticSkin; for example:
myChart.setStyle("dataTipRenderer",mx.skins.ProgrammaticSkin);