Active Label Parameters

All NetCharts charts support the display of popup labels, called dwell or active labels, whenever the mouse rolls over a specified area of a chart. For example, on a barchart, the value of an individual bar can be displayed when the mouse cursor hovers over a bar for a short period of time. Alternatively, a user prompt can be displayed when the mouse hovers over a legend item.

In addition, the user can click the mouse while an active label is displayed. This results in a predefined URL being executed. This URL can serve any of three purposes:

• To replace the current HTML document with any other HTML document
  
  
• To alter the display of any named frame or window within the browser.
  
  
• To load new chart parameters from a parameter file.

Note
The drill-down capability is extremely flexible. It allows any NetCharts chart to serve as a graphical interface to additional web accessible information.

Through the following parameters, the developer can enable or disable these labels. To do so, specify the label to be displayed and specify a URL to be displayed when the label is activated.

DwellLabel   = (Label Tuple);
DwellBox     = (Region Tuple);
DwellOffset  = numericvalue;

ActiveClicks = Number;

BackgroundActiveLabel = ("Label", "URL", "Target");
HeaderActiveLabel     = ("Label", "URL", "Target");
FooterActiveLabel     = ("Label", "URL", "Target");
LeftTitleActiveLabel  = ("Label", "URL", "Target");
RightTitleActiveLabel = ("Label", "URL", "Target");

LegendActiveLabels    = ("Label1", "URL1", "Target1"),...;

BarActiveLabels       = ("Label1", "URL1", "Target1"),...;
BottomActiveLabels    = ("Label1", "URL1", "Target1"),...;
TopActiveLabels       = ("Label1", "URL1", "Target1"),...;
LeftActiveLabels      = ("Label1", "URL1", "Target1"),...;
RightActiveLabels     = ("Label1", "URL1", "Target1"),...;

ActiveLabels          = ("Label1", "URL1", "Target1"),...;
ActiveLabels[1-50]    = ("Label1", "URL1", "Target1"),...;
LineLabels[1-50]      = ("Label1", "URL1", "Target1"),...;
StockLabels[1-50]     = ("Label1", "URL1", "Target1"),...;

ON	= display a popup label over the target
OUTLINE = display an outline of the target
OFF	= don't display anything

The "OFF" mode can be used by dynamic updating servers to disable dwell processing after it has already been enabled.

The DwellOffset The DwellOffset parameter specifies the length of the sides that define the square area around a "hotspot" associated with an active label. When the mouse moves into this hotspot, an active label, if defined, will be displayed. When the mouse is clicked within this hotspot, the target URL, if defined, will be "drilled" to. By default, DwellOffset = 20, which means the hotspot for a datapoint will be a 20 by 20 pixel square centered over the data point. Set DwellOffset to something smaller to prevent overlap between the hotspots of tightly packed datapoints.

If you are using a symbol then the symbol size is added on to the dwell hotspot size to compute the dwell offset area.

See Label Parameters for more details about the other label attributes.

The DwellBox parameter is optional. If specified, it defines a box to be displayed as a background for each dwell label. The box will be automatically scaled to fit each dwell label. See Region Parameters for more details about region attributes.

All of the other active label parameters are optional and may be used to specify the dwell label for one or more data values, axis labels, legend labels or titles. In most charts, the ActiveLabels parameter is specified using a numeric ID (such as ActiveLabels1 or ActiveLabels5) to indicate which data set is being referenced. Each tuple defined in the ActiveLabels parameter is matched with the corresponding data value defined in the DataSet or equivalent parameter. If too many active labels are defined, the extra tuples are ignored. If too few are defined, the remaining data values will use the default dwell label generated.

Active Label Processing

A given active label is defined using 3 optional attributes. If the first attribute is defined, then its value will be used as the text value for the dwell label for the corresponding data value. For example, the parameter settings

DwellLabel    = ("", black, "Courier", 12);
DwellBox      = (yellow, SHADOW, 4);
DataSet1      = 12, 34, 56;
ActiveLabels1 = ("Twelve"), ("Thirty-Four"), ("Fifty-Six");

If the first attribute is not defined or is defined to be "" (the empty string), then a default label will be generated for that data value, depending on the specific chart type. Usually, the default label displays one or more of the numeric values associated with the data point.

If the first attribute is set to "OUTLINE" then instead of displaying a dwell label, an outline will be drawn around the associated item when the mouse hovers over that item. See BarChart9.html for an example using outlines for some of the active labels.

The second ActiveLabels attribute can be used to specify an arbitrary URL that is accessed whenever the user clicks the mouse over the active label. In that case, the given URL is accessed and the resulting document is displayed a specified browser frame or window. In the default case, the current document is replaced by that represented by the URL. See BarChart9.html for an example of how HTML documents can be displayed in another frame whenever the user selects a bar value or axis label.

The third ActiveLabels attribute can be used to specify the target frame or window for the given URL. If it is not defined, the current frame or window will be updated. If the keyword "LOADPARAMS" is used as the target, then the URL will be assumed to point to a NetCharts parameter file (a file containing only NetCharts parameter definitions). In that case, the file will be processed and all of parameters will be used to update the current chart. This allows users to modify the chart slightly or completely change all of the data, without creating a new chart. See DrillDown through multiple charts for an example of how LOADPARAMS can be used.

The ActiveClicks parameter specifies the number of mouse clicks needed to activate the URL that may be associated with each dwell label using the ActiveLabels parameter. This is valid only when charts are displayed as applets.

Programmatic Control

Java developers can monitor and control dwell processing through the NFDwellObserve interface. That interface allows the user to register observer methods that will be called whenever dwell labels are being displayed or erased, and when the user selects a given dwell label. The observer methods can abort normal dwell processing and perform custom processing as needed.

Java programmers can also specify if dwell processing should be performed on the UP or DOWN mouse event, using the dwellAction instance variable in the NFGraph object. By default, dwellAction is set to Event.MOUSE_DOWN. Programmers can change that to Event.MOUSE_UP to cause dwell processing to be performed when the mouse button is released. Note, in that case, the user can abort a drill-down operation simply by moving the mouse away from the dwell label before releasing the mouse button.

DwellAnimationHighlightBorderStyle

	DwellAnimationHighlightBorderStyle = (linetype, linewidth, linecolor);

Defines the border style to be applied to a datapoint when DwellAnimationStyle = HIGHLIGHT. The linewidth defaults to 1 pixel. The linecolor defaults to black.

   example: DwellAnimationHighlightBorderStyle = (DASHED,1,black);

SOLID	A solid line is displayed (default).
DOTTED	A dotted line is displayed.
DASHED	A dashed line is displayed.
DOTDASH	Alternating dots and dashes are displayed.

DwellAnimationHighlightFill

	DwellAnimationHighlightFill = color;

Defines the color used to fill a datapoint when DwellAnimationStyle = HIGHLIGHT.

   example: DwellAnimationHighlightFill = blue;

DwellAnimationStyle

	DwellAnimationStyle = HIGHLIGHT | NONE;

Defines how the chart behaves when the mouse dwells over a data point. DwellAnimation parameters are only valid for image output types (i.e. DwellAnimation does not use the applet supported SVG and SVGweb output formats).

   example: DwellAnimationStyle = HIGHLIGHT;

HIGHLIGHT

The data point is highlighted using the values specified in DwellAnimationHighlightFill and DwellAnimationHighlightBorderStyle.