SChartCrosshair Class Reference

Inherits from UIView
Conforms to SChartCrosshair
Declared in SChartCrosshair.h
Availability Standard
Premium
Related samples BarChart
LineChart

Overview

The SChartCrosshair provides a small circle target with lines that extend to the axis. This is accompanied by a tooltip object - nominally a UIView. The default implementation for the tooltip is provided by SChartCrosshairTooltip. For data points with multiple values at a single point, another implementation, SChartCrosshairMultiValueTooltip, has also been provided.

The crosshair is enabled with a tap-and-hold gesture and will lock to the nearest series to pan through the values. On a line series the values will be interpolated between data points, on all other series types the crosshair will jump from data point to data point. Note that line series interpolation can be switched off by setting interpolatePoints to NO.

In order for a crosshair to be displayed on a chart series, the series must have its [SChartSeries crosshairEnabled] property set to YES. This defaults to NO, so you will need to set this property on the series in your chart.

More information about using SChartCrosshair can be found in the user guide, and in our tutorials ‘Customizing that Crosshair’ and ‘Data streaming, crosshairs and custom tooltips in ShinobiCharts’.

An alternative crosshair implementation, SChartSeriesCrosshair, has also been provided.

Warning: Crosshairs are not currently supported on radial charts.

Properties

chart

The crosshair holds a reference to the chart which contains it.

@property (nonatomic, weak) ShinobiChart *chart

Declared In

SChartCrosshair.h

interpolatePoints

If set to YES the crosshair will move smoothly between points when tracking a line series.

@property (nonatomic) BOOL interpolatePoints

Discussion

Otherwise the crosshair will jump from point to point as it tracks.

By default, this property is set to YES.

Declared In

SChartCrosshair.h

lineDrawer

Allows the user to customise the crosshair line by implementing the SChartCrosshairLineDrawer protocol.

@property (nonatomic, retain) id<SChartCrosshairLineDrawer> lineDrawer

Discussion

By default, this will use implementation from SChartTargetLineDrawer.

Declared In

SChartCrosshair.h

mode

This describes whether the crosshair is in floating mode or not.

@property (nonatomic) SChartCrosshairMode mode

Discussion

The mode is defined with the following options:

  • SChartCrosshairModeSingleSeries: Configures the crosshair to lock to a single series, and display on the closest data point in that series only.
  • SChartCrosshairModeFloating: Configures the crosshair to display on the closest data point.

Declared In

SChartCrosshair.h

outOfRangeBehavior

Defines the behavior of the crosshair when it goes out of range.

@property (nonatomic) SChartCrosshairOutOfRangeBehavior outOfRangeBehavior

Discussion

The crosshair has different behaviors for when it goes out of range. In this context, “out of range” refers to the case when a series goes off the screen - i.e. it is out of range on one axis, but not the other.

  • SChartCrosshairOutOfRangeBehaviorKeepAtEdge: Configures the crosshair to move along the edge of the canvas until the series comes back into range
  • SChartCrosshairOutOfRangeBehaviorHide: Configures the crosshair to hide, but continue to track the series until it comes back in range.
  • SChartCrosshairOutOfRangeBehaviorRemove: Configures the crosshair to remove itself entirely, leaving the chart open for panning or tracking a new series.

By default, the crosshair is set to SChartCrosshairRangeBehaviorHide.

Declared In

SChartCrosshair.h

style

The SChartCrosshairStyle object manages the look of the crosshair.

@property (nonatomic, retain) SChartCrosshairStyle *style

Discussion

The default style for the crosshair is defined in the chart theme. If you wish to modify the look of the crosshair later on, you can set the properties on this object to achieve the desired look.

Declared In

SChartCrosshair.h

tooltip

The tooltip which presents the current data values to the user.

@property (nonatomic, retain) SChartCrosshairTooltip *tooltip

Discussion

By default, this will be an instance of SChartCrosshairTooltip. You can also override this class to present the crosshair data in a custom way.

Declared In

SChartCrosshair.h

trackingPoint

Configures the crosshair to track a particular data point on the chart.

@property (nonatomic, assign) SChartPoint trackingPoint

Discussion

If this property isn’t set, the crosshair will lock to the nearest data point on the nearest series in the chart when it is drawn.

Declared In

SChartCrosshair.h

trackingSeries

Configures the crosshair to track a particular series on the chart.

@property (nonatomic, retain, nullable) SChartMappedSeries *trackingSeries

Discussion

If this property isn’t set, the crosshair will lock to the nearest series on the chart when it is drawn.

Warning: The class of this property has been changed from SChartCartesianSeries to SChartMappedSeries.

Declared In

SChartCrosshair.h

Instance Methods

crosshairMovedInsideRange

This method is called when the crosshair moves while inside the visible range of the chart.

- (void)crosshairMovedInsideRange

Declared In

SChartCrosshair.h

crosshairMovedOutOfRange

This method is called when the crosshair moves out of the visible range of the chart.

- (void)crosshairMovedOutOfRange

Discussion

The behaviour of the crosshair at this point is defined by its mode property.

Declared In

SChartCrosshair.h

crosshairShouldKeepTracking

Returns whether the crosshair should keep tracking. If this is the case, the crosshair should provide a series to track, using its trackingSeries property.

- (BOOL)crosshairShouldKeepTracking

Declared In

SChartCrosshair.h

crosshairTrackingFailed

This method informs the crosshair that a gesture was performed which failed to select any series.

- (void)crosshairTrackingFailed

Discussion

The default behavior in this case is to remove the crosshair.

Declared In

SChartCrosshair.h

drawCrosshairLines

Performs the drawing of the lines and the target circle element of the crosshair.

- (void)drawCrosshairLines

Discussion

Override this function to provide custom lines or other drawn elements.

Declared In

SChartCrosshair.h

initWithChart:

Initializes and returns a newly allocated crosshair object, which is associated with the specified chart.

- (id)initWithChart:(ShinobiChart *)parentChart

Declared In

SChartCrosshair.h

moveToFloatingPixelPosition:

Moves the crosshair to the specified pixel coordinates.

- (void)moveToFloatingPixelPosition:(CGPoint)floatingCoords

Parameters

floatingCoords

The pixel coordinates to which to move the crosshair.

Declared In

SChartCrosshair.h

moveToFloatingPosition:onXAxis:onYAxis:

Moves the crosshair to the coordinates on the chart corresponding to the specified data point relative to the specified axes.

- (void)moveToFloatingPosition:(SChartPoint)point onXAxis:(SChartAxis *)xAxis onYAxis:(SChartAxis *)yAxis

Parameters

point

The data point to which to move the crosshair.

xAxis

The x axis with which the data point is associated. The x value of the data point will be mapped to this axis.

yAxis

The y axis with which the data point is associated. The y value of the data point will be mapped to this axis.

Declared In

SChartCrosshair.h

moveToPosition:andDisplayDataPoint:fromSeries:andSeriesDataPoint:

This method is called when the crosshair changes position.

- (void)moveToPosition:(SChartPoint)coords andDisplayDataPoint:(SChartPoint)dataPoint fromSeries:(SChartMappedSeries *)series andSeriesDataPoint:(id<SChartData>)dataseriesPoint

Parameters

coords

The location on the chart where the crosshair should appear, in points.

dataPoint

The crosshair tooltip will display the value of this data point. This can either be an interpolated point, or the nearest actual point on the series, depending on the configuration of the crosshair.

series

The series on the chart which the crosshair is locked to.

dataseriesPoint

This parameter is used by SChartCrosshairMultiValueTooltip. In this case, the tooltip will display the values contained in this point rather than the value of dataPoint. For other types of tooltip, this parameter is ignored.

Discussion

Warning: The ‘series’ parameter has been changed from class SChartCartesianSeries to SChartMappedSeries.

Declared In

SChartCrosshair.h

removeCrosshair

Hides the crosshair (with lines and tooltip) on the chart.

- (BOOL)removeCrosshair

Discussion

This method is called by the chart when the crosshair should be dismissed. Override this method to control the display of the crosshair in subclasses.

Declared In

SChartCrosshair.h

setDefaultTooltip

Sets the current tooltip element of the crosshair to be an instance of the default base-class - SChartCrosshairTooltip.

- (void)setDefaultTooltip

Declared In

SChartCrosshair.h

shouldDrawCrosshairLinesForPoint:inFrame:

Returns YES if the crosshair should draw its tracking lines to the specified point, given the specified frame.

- (BOOL)shouldDrawCrosshairLinesForPoint:(CGPoint)point inFrame:(CGRect)frame

Discussion

This defaults to a simple bounds check - whether the point is inside the frame.

Declared In

SChartCrosshair.h

showCrosshair

Displays the crosshair (with lines and tooltip) on the chart.

- (void)showCrosshair

Discussion

This method is called by the chart when the crosshair should be displayed. Override this method to control the display of the crosshair in subclasses.

Declared In

SChartCrosshair.h