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 CVN_MouseMovePlotArea message 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 CVN_MouseMovePlotArea message, 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 CChartViewer.getPlotAreaMouseX and CChartViewer.getPlotAreaMouseY 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 CChartViewer.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, CChartViewer.updateDisplay should be used to commit the drawing to the display. If the track cursor drawing code is called from the CVN_MouseMovePlotArea message 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 CVN_MouseLeavePlotArea message handler to remove the dynamic layer. A more convenient method is to use CChartViewer.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:


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.