Hit-Test API

The Hit-Test API is set of virtual methods defined on BaseRenderableSeries, and overridden by some of the series types. This API is used by the RolloverModifierSeriesSelectionModifier and TooltipModifier to transform touch on screen into data-points, and determine if touch event occurs over a point or over a series.

 

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

HitTest
Copy Code
@Override
public boolean onTouch(View v, MotionEvent event) {
    touchPoint.set(event.getX(), event.getY());
    surface.translatePoint(touchPoint, surface.getRenderableSeriesArea());
    final StringBuilder stringBuilder = new StringBuilder();
    stringBuilder.append(String.format("Touch at: (%.1f, %.1f)", touchPoint.x, touchPoint.y));
    for (IRenderableSeries renderableSeries : surface.getRenderableSeries()) {
        renderableSeries.hitTest(hitTestInfo, touchPoint.x, touchPoint.y, 30);
        stringBuilder.append(String.format("\n%s - %s", renderableSeries.getClass().getSimpleName(), Boolean.toString(hitTestInfo.isHit)));
    }
    toast.setText(stringBuilder.toString());
    toast.show();
    return true;
}
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 Hit-Test Results

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

  • HitTestPoint - The coordinates of point used for Hit-Test
  • HitTestRadius - The Hit-Test radius which was used for searching of nearest data point
  • DataSeriesIndex - If data point was hit contains index of the point in DataSeries which was hit
  • PointSeriesIndex - If data point was hit contains index of the point in resampled PointSeries which was hit
  • IsHit - Boolean flag which tells wheter or not HitTestPoint was within a certain radis of point on series
  • IsWithinDataBounds - Boolean flag which tells if HitTestPoint lies between first and last X point on series
  • HitRenderableSeries - The RenderableSeries which we perform Hit-Test on

UseInterpolation Flag

The UseInterpolation flag increases the accuracy of HitTest at the expense of performance.

When used in a FastLineRenderableSeries, UseInterpolation=True will return IsHit=True if the input touch event is over the line, whereas if UseInterpolation=False, it will return IsHit=True only if the input mouse-point is over a data-point.

This is useful say if you wanted to show a tooltip only on datapoints (UseInterpolation=False), vs. anywhere on the line (UseInterpolation=True).

For other series types, such as FastCandlestickRenderableSeriesFastColumnRenderableSeriesFastMountainRenderableSeries, setting UseInterpolation=True will result in an IsHit=True when touch is ‘over the series’ as opposed to ‘over the data-points’.

NOTE: Interpolation is linear interpolation and at the time of writing, is not suitable for use by Logarithmic Axis.