Programmable Track Cursor (Windows)

For desktop applications, ChartDirector Programmable Track Cursor is implemented by drawing the track cursor on a "dynamic layer" of the chart. For example, drawing a horizontal line and a vertical line will create a crosshair cursor. The drawing is typically performed in a WinChartViewer.MouseMovePlotArea event handler so that the track cursor follows the mouse cursor. It is also possible to draw the track cursor at other times. For example, one may program the track cursor so that it is movable by arrow keys. In a realtime chart, the track cursor can be programmed to sweep through the chart as new data points are added.

By far the most common usage of track cursor is when the mouse is moving over the plot area of an XYChart. The WinChartViewer.MouseMovePlotArea event, which occurs when the mouse moves over the plot area, is specially designed to facilitate track cursor implementation.

A special feature of MouseMovePlotArea is that it occurs even if the mouse is slightly outside the plot area, in which case WinChartViewer.PlotAreaMouseX and WinChartViewer.PlotAreaMouseY will report as if the mouse is still on the edge of the plot area. This feature allows the user to easily position the track cursor on the edge of the plot area, at which the latest data points are often located. The margin around the plot area that would still trigger MouseMovePlotArea is configurable using WinChartViewer.setPlotAreaMouseMargin.

The "dynamic layer" can be imagined as a special layer on top of the chart for drawing updatable contents. The BaseChart.initDynamicLayer method creates the dynamic layer, or clears the dynamic layer if it has already been created. This method returns a DrawArea object for drawing lines, shapes and text on the dynamic layer.

In typical usage, the track cursor drawing code would use initDynamicLayer to get the DrawArea object for the dynamic layer, and use the DrawArea object to draw the track cursor. After the drawing is completed, WinChartViewer.updateDisplay should be used to commit the drawing to the display. If the track cursor drawing code is called from the WinChartViewer.MouseMovePlotArea event handler, the crosshair will appear to follow the mouse.

In some track cursor style, the track cursor should be removed when the mouse leaves the plot area. One way to perform this is to use BaseChart.removeDynamicLayer in the WinChartViewer.MouseLeavePlotArea event handler to remove the dynamic layer. A more convenient method is to use WinChartViewer.removeDynamicLayer to automatically remove the dynamic layer when the mouse leaves the plot area, which avoids the need to set up an extra event handler.

Very often, the track cursor is not drawn exactly at the mouse cursor position, but is drawn at the data point position nearest to the mouse cursor in the x direction. ChartDirector includes a method XYChart.getNearestXValue, which will search all data in the chart to get the x data value nearest to a given point. This value can then be used to obtain the x pixel coordinate (using XYChart.getXCoor) for drawing the track cursor. It can also be used to look up the data points (using Layer.getXIndexOf) so as to draw dots that track the data points, generate dynamic data labels, axis labels or legend entries.

ChartDirector includes a number of sample drawing routines in its sample code as follows:

Sample Code	Description
Track Line with Legend (Windows)	Demonstrates a track cursor that consists of a vertical line snapped to the nearest x data position. There are dots to highlight the nearest data points, and a dynamically updated legend showing their values.
Track Line with Data Labels (Windows)	Demonstrates a track cursor that consists of a vertical line snapped to the nearest x data position with a floating x-axis label. There are also dots to highlight the nearest data points, with labels beside them displaying their values.
Track Line with Axis Labels (Windows)	Demonstrates a track cursor that uses horizontal and vertical lines to connect the nearest data points to the x-axis and y-axis, with floating axis labels showing their values.
Track Box with Floating Legend (Windows)	Demonstrates a track cursor that consists of a rectangle enclosing the slot corresponding to the nearest x-axis label. A floating legend box that moves with the mouse cursor is used to display the data values in that slot.
Crosshair with Axis Labels (Windows)	Demonstrates a track cursor that consists of a vertical line and a horizontal line at the mouse cursor position, thereby forming a crosshair. Floating axis labels are used to display the cursor position.
Finance Chart Track Line (Windows)	This is similar to Track Line with Legend (Windows), but is modified to apply to the FinanceChart object.
Zooming and Scrolling with Track Line (1) (Windows)	Demonstrates how to apply track cursors to a Zoomable and Scrollable chart. The track cursor drawing code is similar to that in Track Line with Legend (Windows).
Zooming and Scrolling with Track Line (2) (Windows)	Demonstrates how to apply track cursors to a Zoomable and Scrollable chart. The track cursor drawing code is similar to that in Track Line with Data Labels (Windows).
Zooming and Scrolling with Viewport Control (Windows)	Demonstrates how to apply track cursors to a Zoomable and Scrollable chart. The track cursor drawing code is similar to that in Track Line with Legend (Windows).
XY Zooming and Scrolling (Windows)	Demonstrates how to apply track cursors to a Zoomable and Scrollable chart. The track cursor drawing code is similar to that in Crosshair with Axis Labels (Windows).
Real-Time Chart with Track Line (Windows)	Demonstrates how to apply track cursors to a Realtime chart. The track cursor drawing code is similar to that in Track Line with Legend (Windows).
Realtime Chart with Zooming and Scrolling (Windows)	Demonstrates how to apply track cursors to a Realtime chart. The track cursor drawing code is similar to that in Track Line with Data Labels (Windows).

Note that the above are only examples demonstrating the ChartDirector features for drawing track cursors. You may reuse them, or modify them for your own needs. You may also develop your own track cursor drawing code to implement the track cursor behaviour you want.