Image Maps, Hot Spots and CDML Tooltips

A hot spot is a region on an image that can generate mouse events and can have tooltip. For example, on a bar chart, each bar can be a hot spot. The bar can then generate mouse click and other mouse events, and can pop up a tooltip box when the mouse hovers on it.

HTML image maps are a standard way to define hot spots. It defines the hot spot regions and their associate parameters and tooltips. ChartDirector can generate HTML image maps for the charts by using BaseChart.getHTMLImageMap and other similar methods. Many of the examples that come with ChartDirector use this method to configure tooltips for the charts.

Since HTML is an open standard, you can append custom image map entries to define custom hot spots on the chart. For example, if you include your company logo on the chart, you may define a hot spot for the logo to make it clickable.

Although HTML image map comes from web technology, ChartDirector desktop controls, such as CChartViewer and QChartViewer support it as well.

The most common usage of image maps is to define tooltips for the chart objects.

In HTML image maps, tooltips are configured with the "title" attributes. For example, in BaseChart.getHTMLImageMap, the attribute title='{xLabel}: {value}' will configure the tooltip to display the x-axis label associated with the hot spot, followed by a colon and a space, and after that the data value associated with the hot spot.

By default, the tooltip will be displayed using the default tooltip mechanism of the programming framework. For a web application, it will be displayed using the tooltip mechanism provided by the browser. For a desktop application, it will be provided by the desktop GUI framework. Typically, the tooltip will be a small box with a line of text and the style is not configurable.

ChartDirector also supports enhanced CDML tooltips with rich formatting. The tooltip will be rendered by ChartDirector directly. It can include multiple fonts, colors, images, icons or even another chart, and can be semi-transparent. Unlikely the default tooltip which appears only when the mouse hovers on the hot spot for a short time, the CDML tooltip pops up instantaneously when the mouse enters the hot spot and will follow the mouse as it moves. The CDML Tooltips sample code contains a few examples of using CDML tooltips.

For desktop applications, CDML tooltips can be enabled by starting the tooltip with the <*cdml*> tag. The tooltip can them be formatted by using CDML. A simple example is:

<*cdml*><*font=bold,color=0000FF*>{xLabel}:<*/font*>; {value}

When displaying the tooltip, ChartDirector will substitute the <*cdml*> tag with the following CDML, which represents a container with white background, grey border, rounded corners and charcoal grey font color.

<*block,bgColor=F0F0F0,edgeColor=808080,margin=5,roundedCorners=3*><*font,color=222222*>

To customize the container, you may use CChartViewer.setCDMLToolTipPrefix or QChartViewer.setCDMLToolTipPrefix to configure an alternative container. You can also omit the <*cdml*> tag. In this case, the tooltip should start with a CDML tag that defines its own container. This allows different tooltips to have different container styles. ChartDirector will still consider the tooltip to be a CDML tooltip as long as it starts with a CDML tag.