Hit-Test API
The Hit-Test API is a set of virtual methods defined on IRenderableSeries such as:
- hitTest(renderableSeries.hitTest.HitTestInfo hitTestResult, float x, float y)
- hitTest(renderableSeries.hitTest.HitTestInfo hitTestResult, float x, float y, float hitTestRadius)
- verticalSliceHitTest(renderableSeries.hitTest.HitTestInfo hitTestResult, float x, float y)
This API is used by the RolloverModifier, TooltipModifier, CursorModifier and SeriesSelectionModifier 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:
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. You can learn more about it in the Axis APIs - Convert Pixel to Data coordinates article.
boolean onTouch(View v, MotionEvent event) {
final SciChartSurface surface = (SciChartSurface) v;
// The touch point relative to the ChartSurface
touchPoint.set(event.getX(), event.getY());
// Translate the touch point relative to RenderableSeriesArea (or ModifierSurface)
surface.translatePoint(touchPoint, surface.getRenderableSeriesArea());
for (IRenderableSeries renderableSeries : surface.getRenderableSeries()) {
// Perform `Hit-Test` which will be stored in the `_hitTestInfo`
renderableSeries.hitTest(hitTestInfo, touchPoint.x, touchPoint.y);
}
return true;
}
Note
You can see hit-test in action, in our full Hit-Test API example, which be found in the SciChart Android Examples Suite as well as on GitHub:
The Hit-Test Results
The HitTestInfo which is used for Hit-Test contains some useful properties to determine what point was touched.
Property | Description |
---|---|
hitTestPoint | The coordinates of a point, that is used for Hit-Test. |
hitTestRadius | The Hit-Test radius which was used for searching of nearest data point. |
dataSeriesIndex | If data point that was hit contains the index of the point in IDataSeries<TX,TY> which was hit. |
pointSeriesIndex | If data point that was hit contains the index of hit test point in associated ISeriesRenderPassData. |
isHit | Boolean flag which tells whether or not hitTestPoint was within a certain radius of point on a series. |
isWithinDataBounds | Boolean flag which tells if hitTestPoint lies between first and last X point on series. |
hitRenderableSeries | The IRenderableSeries which we perform Hit-Test on. |
UseInterpolation Flag
The UseInterpolation flag increases the accuracy of the Hit-Test at the expense of performance. You can modify its value via the useInterpolation property, which is available for all the inheritors such as TooltipModifier, for example.
Consider FastLineRenderableSeries and it's possible interpolation cases:
useInterpolation = false
- hit-test will return isHit = true - only if the input mouse-point is over a data-point.useInterpolation = true
- hit-test will return isHit = true - if the input touch event is over the line.
This is useful say if you wanted to show a tooltip only on data-points (useInterpolation = false
) vs. anywhere on the line (useInterpolation= true
).
For other series types, such as FastCandlestickRenderableSeries, FastColumnRenderableSeries, FastMountainRenderableSeries, using useInterpolation = false
will result in an isHit = true
when touch is over the series as opposed to over the data-points.
Note
The interpolation is linear and linear only at the time of writing, it is not suitable for use by Logarithmic Axis.