iOS & macOS Charting Documentation - SciChart iOS & macOS Charts SDK v4.x

Hit-Test API

The Hit-Test API is a set of virtual methods defined on ISCIRenderableSeries such as:

This API is used by the SCIRolloverModifier, SCITooltipModifier, SCICursorModifier and SCISeriesSelectionModifier 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.

- (void)handleSingleTap:(UITapGestureRecognizer *)recognizer { // The touch point relative to the SCIChartSurface CGPoint location = [recognizer locationInView:recognizer.view.superview]; // Translate the touch point relative to RenderableSeriesArea (or ModifierSurface) CGPoint hitTestPoint = [self.surface translatePoint:location hitTestable:self.surface.renderableSeriesArea]; // Perform `Hit-Test` which will be stored in the `_hitTestInfo` [rSeries hitTest:_hitTestInfo at:hitTestPoint]; }
@objc fileprivate func handleSingleTap(_ recognizer: UITapGestureRecognizer) { // The touch point relative to the SCIChartSurface let location = recognizer.location(in: recognizer.view!.superview) // Translate the touch point relative to RenderableSeriesArea (or ModifierSurface) let hitTestPoint = surface.translate(location, hitTestable: surface.renderableSeriesArea) // Perform `Hit-Test` which will be stored in the `_hitTestInfo` rSeries.hitTest(_hitTestInfo, at: hitTestPoint) }
private void HandleSingleTap(UITapGestureRecognizer recognizer) { // The touch point relative to the SCIChartSurface var location = recognizer.LocationInView(recognizer.View.Superview); // Translate the touch point relative to RenderableSeriesArea (or ModifierSurface) var hitTestPoint = Surface.TranslatePoint(location, Surface.RenderableSeriesArea); // Perform `Hit-Test` which will be stored in the `_hitTestInfo` rSeries.HitTest(_hitTestInfo, hitTestPoint); }

Hit-Test API Example

NOTE: You can see hit-test in action, in our full Hit-Test API example, which be found in the SciChart iOS Examples Suite as well as on GitHub:

The Hit-Test Results

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

Property Description
SCIHitTestInfo.hitTestPoint The coordinates of a point, that is used for Hit-Test.
SCIHitTestInfo.hitTestRadius The Hit-Test radius which was used for searching of nearest data point.
SCIHitTestInfo.dataSeriesIndex If data point that was hit contains the index of the point in ISCIDataSeries which was hit.
SCIHitTestInfo.pointSeriesIndex If data point that was hit contains the index of hit test point in associated ISCISeriesRenderPassData.
SCIHitTestInfo.isHit Boolean flag which tells whether or not SCIHitTestInfo.hitTestPoint was within a certain radius of point on a series.
SCIHitTestInfo.isWithinDataBounds Boolean flag which tells if SCIHitTestInfo.hitTestPoint lies between first and last X point on series.
SCIHitTestInfo.hitRenderableSeries The ISCIRenderableSeries 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 SCITooltipModifierBase.useInterpolation property, which is available for all the inheritors such as SCITooltipModifier, for example.

Consider SCIFastLineRenderableSeries and it’s possible interpolation cases:

  • useInterpolation = NO - hit-test will return SCIHitTestInfo.isHit = YES - only if the input mouse-point is over a data-point.
  • useInterpolation = YES - hit-test will return SCIHitTestInfo.isHit = YES - 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 = NO) vs. anywhere on the line (useInterpolation= YES).

For other series types, such as SCIFastCandlestickRenderableSeries, SCIFastColumnRenderableSeries, SCIFastMountainRenderableSeries, using useInterpolation = YES will result in an isHit = YES 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.

Examples of Use of the Hit Test API

Our own source code uses the Hit-Test API to perform hit-testing when showing tooltips at a touch location. We also have published some examples of use.

iOS Chart Hit Test API Example

This example shows you how to use the Hit-Test API on tap, and reports hit results to a popup.

Hit-Test API Example

NOTE: The full Hit-Test API example can be found in the SciChart iOS Examples Suite as well as on GitHub: Obj-C / SWIFT Example.