RenderableSeries Hit-Test API

The Hit-Test API is set of functions defined on the BaseRenderableSeries class, and overridden by some of the series types. This API is used internally by tooltips (see RolloverModifier) to transform mouse clicks on screen into data-points, and determine if mouse event occurs over a point or over a series. You can use the same API to determine if a click or touch event was over a series, and take appropriate action.

To call the Hit-Test method, use the following code from example from our Example Suite:

HitTest	Copy Code
// Create a SciChartSurface with X,Y axis const { wasmContext, sciChartSurface } = await SciChartSurface.create(divElementId); sciChartSurface.xAxes.add(new NumericAxis(wasmContext)); sciChartSurface.yAxes.add(new NumericAxis(wasmContext)); // Create a Line Series with XyDataSeries and some data const lineSeries = new FastLineRenderableSeries(wasmContext); lineSeries.dataSeries = new XyDataSeries(wasmContext, { dataSeriesName: "Line Series", xValues: [0,1,2], yValues: [3,4,5] }); // Add the line series to the SciChartSurface sciChartSurface.renderableSeries.add(lineSeries); // add an event listener for mouse down. You can access the actual SciChartSurface canvas as // follows, or find element by ID=divElementId in the dom sciChartSurface.domCanvas2D.addEventListener("mousedown", (mouseEvent: MouseEvent) => { // call renderableSeries.hitTestProvider.hitTest passing in the mouse point // other parameters determine the type of hit-test operation to perform const hitTestInfo = lineSeries.hitTestProvider.hitTest( new Point(mouseEvent.offsetX, mouseEvent.offsetY), ENearestPointLogic.NearestPoint2D, HIT_TEST_RADIUS, false); // Log the result to console. HitTestInfo contains information about the hit-test operation console.log(`${hitTestInfo.dataSeriesName} hit test result: ` + `MouseCoord=(${hitTestInfo.xCoord}, ${hitTestInfo.yCoord}) ` + `IsHit? ${hitTestInfo.isHit} ` + `Result=(${hitTestInfo.xValue}, ${hitTestInfo.yValue}) ` ); });

HitTest

Copy Code

// Create a SciChartSurface with X,Y axis
const { wasmContext, sciChartSurface } = await SciChartSurface.create(divElementId);
sciChartSurface.xAxes.add(new NumericAxis(wasmContext));
sciChartSurface.yAxes.add(new NumericAxis(wasmContext));
// Create a Line Series with XyDataSeries and some data
const lineSeries = new FastLineRenderableSeries(wasmContext);
lineSeries.dataSeries = new XyDataSeries(wasmContext, {
    dataSeriesName: "Line Series",
    xValues: [0,1,2],
    yValues: [3,4,5]
});
// Add the line series to the SciChartSurface
sciChartSurface.renderableSeries.add(lineSeries);
// add an event listener for mouse down. You can access the actual SciChartSurface canvas as
// follows, or find element by ID=divElementId in the dom
sciChartSurface.domCanvas2D.addEventListener("mousedown", (mouseEvent: MouseEvent) => {

    // call renderableSeries.hitTestProvider.hitTest passing in the mouse point
    // other parameters determine the type of hit-test operation to perform
    const hitTestInfo = lineSeries.hitTestProvider.hitTest(
        new Point(mouseEvent.offsetX, mouseEvent.offsetY),
        ENearestPointLogic.NearestPoint2D,
        HIT_TEST_RADIUS,
        false);
    // Log the result to console. HitTestInfo contains information about the hit-test operation
    console.log(`${hitTestInfo.dataSeriesName} hit test result: ` +
        `MouseCoord=(${hitTestInfo.xCoord}, ${hitTestInfo.yCoord}) ` +
        `IsHit? ${hitTestInfo.isHit} ` +
        `Result=(${hitTestInfo.xValue}, ${hitTestInfo.yValue}) `
    );
});

NOTE: You must transform any touch events into the coordinate space of the main chart area. Without this, all hit-test results will be inaccurate.

The HitTest API Call

The Hit-Test API can be called by invoking hitTest() on BaseRenderableSeries.hitTestProvider. A link to the function on TypeDoc can be found here.

Example Title	Copy Code
/** * @description Performs a hit-test at the specific mouse point (X,Y coordinate on the parent SciChartSurface), * returning a HitTestInfo type with the results * @param point The mouse point on the parent SciChartSurface * @param logic Logic to find nearest point * @param hitTestRadius The radius in pixels to determine whether a mouse is over a data-point * @param interpolate If true, use interpolation to perform a hit-test between data-points, or on the area if * a FastMountainRenderableSeries, FastColumnRenderableSeries or FastCandlestickRenderableSeries */ hitTest(point: Point, logic: ENearestPointLogic, hitTestRadius: number, interpolate: boolean): HitTestInfo;

Example Title

Copy Code

/**
 * @description Performs a hit-test at the specific mouse point (X,Y coordinate on the parent SciChartSurface),
 * returning a HitTestInfo type with the results
 * @param point The mouse point on the parent SciChartSurface
 * @param logic Logic to find nearest point
 * @param hitTestRadius The radius in pixels to determine whether a mouse is over a data-point
 * @param interpolate If true, use interpolation to perform a hit-test between data-points, or on the area if
 * a FastMountainRenderableSeries, FastColumnRenderableSeries or FastCandlestickRenderableSeries
 */
hitTest(point: Point, logic: ENearestPointLogic, hitTestRadius: number, interpolate: boolean): HitTestInfo;

The Hit-Test Results

The HitTestInfo which is used for Hit-Test contains some useful properties to determine what point was touched.

xCoord, yCoord: The coordinates of the hit-test result
dataSeriesName: The name of the dataseries that was hit
dataSeriesIndex: the index to the dataseries that was hit
isHit: Whether a series was hit or not

More info can be found at the TypeDoc website for this function call.