Using DataTip objects

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 -->
<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="Bar Chart">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
     <mx:BarChart id="myChart"
        dataProvider="{srv.lastResult.data.result}"
        showDataTips="true">
        <mx:verticalAxis>
           <mx:CategoryAxis 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}"/>
  </s:Panel>
</s: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 -->
<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="Bar Chart">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
         <mx:BarChart id="myChart" 
            dataProvider="{srv.lastResult.data.result}" 
            showDataTips="true">
            <mx:verticalAxis>
               <mx:CategoryAxis 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}"/>
  </s:Panel>
</s:Application>
The executing SWF file for the previous example is shown below:

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 -->
<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="Bar Chart">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
     <mx:BarChart id="myChart" 
        dataProvider="{srv.lastResult.data.result}" 
        showDataTips="true" 
        mouseSensitivity="50" 
        dataTipMode="multiple">
        <mx:verticalAxis>
           <mx:CategoryAxis 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}"/>
  </s:Panel>
</s: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:

• BarChart

• CandlestickChart

• ColumnChart

• HLOCChart

• PieChart

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.

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

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

     public function dtFunc(hd:HitData):String {
        return hd.item.month + ": " + 
        "<B>$" + hd.item.profit + "</B>";
     }
  ]]></fx:Script>

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

  <s:Panel title="Bar Chart">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
     <mx:BarChart id="myChart" 
        dataProvider="{srv.lastResult.data.result}" 
        showDataTips="true" 
        dataTipFunction="dtFunc">
        <mx:verticalAxis>
           <mx:CategoryAxis 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}"/>
  </s:Panel>
</s: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 -->
<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>

  <fx:Script><![CDATA[
     import mx.charts.HitData;
     import mx.charts.series.ColumnSeries;

     public var b:Boolean = true;

     public function myDataTipFunction(e:HitData):String {
        var s:String;
        s = ColumnSeries(e.element).displayName + "\n";
        s += "Profit: $" + (e.item.profit - e.item.expenses);
        return s;
     }

  ]]></fx:Script>

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

  <s:Panel title="Casting HitData Objects">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
     <mx:ColumnChart id="myChart" 
        dataProvider="{srv.lastResult.data.result}"
        showDataTips="true" 
        dataTipFunction="myDataTipFunction">
        <mx:horizontalAxis>
           <mx:CategoryAxis categoryField="month"/>
        </mx:horizontalAxis>
        <mx:series>
           <mx:ColumnSeries
                yField="profit"
                displayName="Income '09"/>
           <mx:ColumnSeries
                yField="expenses"
                displayName="Expenses '09"/>
        </mx:series>
     </mx:ColumnChart>
     <mx:Legend dataProvider="{myChart}"/>
  </s:Panel>
</s: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 -->
<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>

  <fx:Script><![CDATA[
     import mx.charts.HitData;
     import mx.charts.series.ColumnSeries;
     import mx.charts.series.items.ColumnSeriesItem;

     public var b:Boolean = true;

     public function myDataTipFunction(e:HitData):String {

        var s:String;
        s = "<B>" + ColumnSeries(e.element).displayName + "</B>\n";

        s += "<I>Profit:</I> <FONT COLOR='#339966'>$" + 
            e.item.profit + "</FONT>\n";
        s += "<I>Expenses:</I> <FONT COLOR='#FF0000'>$" + 
            e.item.expenses + "</FONT>\n";
        s += "------------------------\n";
        s += "<I>Difference:</I> $" + (e.item.profit - e.item.expenses) + "\n";

        // The value of the Profit will always be 100%, 
        // so exclude adding that to the DataTip. Only 
        // add percent when the user gets the Amount 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 total.\n";
        }
        return s;
     }
  ]]></fx:Script>

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

  <s:Panel title="Accessing ChartItems from HitData Objects">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
     <mx:ColumnChart id="myChart" 
        dataProvider="{srv.lastResult.data.result}" 
        type="100%"
        dataTipFunction="myDataTipFunction" 
        showDataTips="true">
        <mx:horizontalAxis>
           <mx:CategoryAxis categoryField="month"/>
        </mx:horizontalAxis>
        <mx:series>
           <mx:ColumnSeries 
                yField="profit" 
                displayName="Profit '09"/>
           <mx:ColumnSeries 
                yField="expenses" 
                displayName="Expenses '09"/>
        </mx:series>
     </mx:ColumnChart>
     <mx:Legend dataProvider="{myChart}"/>
  </s:Panel>
</s: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 render simple HTML for formatted DataTip objects. Flex supports a small subset of HTML tags including <FONT>, <B>, <I>, and <BR>.

You can create a custom class that defines the appearance 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 updateDisplayList() method. In the updateDisplayList() method, you define the appearance of the box for the data tip and apply styles that apply to the text for the data tip.

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;
    
    public class MyDataTip extends DataTip {

        public function MyDataTip() {
            super();            
        }       
        
        override protected function updateDisplayList(w:Number, h:Number):void {
            super.updateDisplayList(w, h);
            
            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 -->
<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();applyCustomDataTips();"
    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>

  <fx:Script><![CDATA[
    private function applyCustomDataTips():void {
        myChart.setStyle("dataTipRenderer",MyDataTip);    
    }
  ]]></fx:Script>

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

  <s:Panel title="Bar Chart">
        <s:layout>
            <s:VerticalLayout/>
        </s:layout>
     <mx:BarChart id="myChart" 
        dataProvider="{srv.lastResult.data.result}" 
        showDataTips="true">
        <mx:verticalAxis>
           <mx:CategoryAxis 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}"/>
  </s:Panel>
</s: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);

If you want to change the text of the data tip, you use the dataTipFunction callback function on the chart control, as described in Customizing DataTip values.