ChartViewer.setImageMap

Sets the image map that defines the hot spots on the chart image.

The ChartViewer control expects the image map to be in HTML image map format comprising of HTML <AREA> tags. The BaseChart.getHTMLImageMap method can be used to automatically generate image maps for charts.

The advantages of using HTML image map format is that it is easy for developers to customize the hot spots.

For example, one can create custom buttons in the chart image by drawing custom text boxes, and then create custom image maps to define the text boxes as hot spots. These custom image maps can be appended to the image maps generated by BaseChart.getHTMLImageMap using simple string concatenation.

The ChartViewer control will process the various attributes of the HTML <AREA> tags as follows:

Attribute	Description
coords	This attribute defines the position and shape of the hot spot.
href	The URL specified in this attribute will become the attributes of the hot spot. The path portion of the URL will become the path attribute, and the attributes/values of the query parameters will become the attributes/values of the hot spot. When a hot spot event occurs (eg. mouse click), the hot spot attributes will be passed to the event listener as a Hashtable.
title	This attribute defines the tool tip text to display when the mouse moves over and stops on the hot spot. If the mouse is not on top of any hot spot, the default SWING tool tip (set using setToolTipText of the JLabel class).

When the mouse pointer moves over a hot spot, it can change shape to provide user feedback. For example, it can change from an "arrow" to a "hand". The mouse pointers are configured using ChartViewer.setHotSpotCursor.

It is possible to define some hot spots as "silent" hot spots. For these hot spots, the the mouse pointer will not change shape. These are useful if the hot spots are for displaying tool tips only and not clickable.

A hot spot is considered as silent if its <AREA> tag that has no href attribute, or an href attribute with an empty path (but can still contain query parameters), or the path starts with the "~" character.

This method stores a reference to the image map string so that it can be retrieved later using ChartViewer.getImageMap. However, ChartViewer internally does not need the image map string after parsing it with this method. In systems with very limited memory (such as embedded systems), if the image map string is not needed, the ChartViewer.disposeReference may be used to dispose the reference, so that it may be garbage collected.