Search code examples
apache-flexchartsflex4flex3flex-charting

How do DataTips work in Flex charting?

DataTips in Flex charting are a poorly documented and little-understood feature.

There are three parts:

  • the DataTip, by default a box with text inside
  • the DataTipTarget, by default a bulls-eye circle over the series' point
  • the Callout, the line from dataTipTarget to the DataTip box

How are these three elements created/drawn and how can they be customized?

See also my answer on how to properly customize the rendering of the DataTipTargets and the Callout lines.

Solution

  • It turns out that the dataTipRenderer style from the ChartBase class defaults to DataTip.

    DataTip is an IDataRenderer and therefore can act as a renderer. However, the method DataTip.updateDisplayList(w,h) does not draw the circle at the data point. It draws a rectangle with HTML-able text inside.

    So what, then, draws the elusive bulls-eyes?

    Now I did some digging, some Very Deep digging, and I have found the answers. I will document them here for others.

    My SDK version is 4.1.0.

    The code that renders the circle data point upon hover, which is the default, is not a renderer as we thought, but in fact a function within the mx.charts.chartClasses.ChartBase class, line 3873:

    /**
 *  Defines the locations of DataTip objects on the chart.
 *  This method ensures that DataTip objects do not overlap each other
 *  (if multiple DataTip objects are visible) or overlap their target data items.
 *  
 *  @langversion 3.0
 *  @playerversion Flash 9
 *  @playerversion AIR 1.1
 *  @productversion Flex 3
 */
protected function positionDataTips():void

    There's a similar function positionAllDataTips() in the same class.

    There is a simple boolean style on ChartBase, showDataTipTargets, that when set to false will disable the drawing of the circle on the line when hovering.

    The datatip targets are rendered within the positionDataTips() function of ChartBase (starting at line 4204).

    Once I figured out that showDataTipTargets is related to this, I was able to answer another question. There you can find a detailed explanation of how to customize the DataTipTarget

    The ChartBase boolean property, showDataTips, toggles the rendering of datatip BOXES only. They are rendered using the style dataTipRenderer, and the text of the datatip box is created using property dataTipFunction.

    To summarize, DataTips on charts can be understood as the following:

    • ChartBase.getStyle("showDataTipTargets"):Boolean will toggle the visibility of the default circle that is rendered upon hovering over a point.
      • In order to actually make changes to the rendering of the DataTip Targets, you must override/modify the way they are drawn in ChartBase.positionDataTips() function
    • The DataTip boxes are handled separately
      • ChartBase.showDataTips:Boolean will toggle the visibility of DataTips and DataTipTargets for the entire chart
      • ChartBase.getStyle("dataTipRenderer"):Class will handle the graphical rendering of the DataTip box only.
      • The dataTipRenderer will use the string returned by ChartBase.dataTipFunction:Function to display the data.
      • The convention that should be followed is:
        • A custom dataTipRenderer should handle the graphics/drawing of a DataTip
        • A custom dataTipFunction should handle the formatting of the text of the data for a given point
    • The callout line, which is the optional line drawn from DataTipTarget to DataTip box, can be enabled and customized by setting ChartBase.getStyle(“dataTipCalloutStroke”):IStroke.