SChartSeries Class Reference

Inherits from NSObject
Conforms to SChartLegendItem
Declared in SChartSeries.h
Availability Standard
Premium
Related samples

Overview

SChartSeries manages the display of a data series on a ShinobiChart. It contains a set of data points.

There are various things which you can do to configure the behavior and appearance of a chart series:

  • A series can optionally use animations when it appears and disappears on the chart. You can set whether animation should be enabled, and if so, you can configure the animations which the series uses.
  • You can configure whether the series is selectable, and if so, its behavior when it is selected.
  • The series contains instances of SChartSeriesStyle, or one of its sub-classes, to manage its appearance. Tweaking these style objects allows you to change the look of the series on the chart.
  • You can update the representation of the series in the chart legend, and whether the chart crosshair is enabled for the series.

We have created sub-classes of SChartSeries for each of the concrete types of chart series which are available on a chart. These are:

  • SChartLineSeries draws data points and connects them, in the order given, using a line. The display of individual points may be enabled or disabled as required. Similarly the area fill under the line may be enabled or disabled as required to form area series.

Line/Area Series

Scatter Series

  • SChartBubbleSeries draws bubbles that are placed at the x and y values of the data. A third property, Area, controls the magnitude of the bubble at each point. Use SChartBubbleDataPoint for this series.

Bubble Series

Column Series

Bar Series

  • SChartBandSeries draws two lines (high and low) and can shade the area between them. (Premium Edition only).

Band Series

  • SChartCandleStickSeries draws candlestick data points (Premium Edition only).

CandleStick Series

  • SChartOHLCSeries draws Open High Low Close data points (Premium Edition only).

OHLC Series

  • SChartStepLineSeries draws a line chart where the connecting line will only travel in a vertical or horizontal direction to connect the data points.

Step Line Series

Pie Series

Donut Series

Series are always drawn in order with the lowest series index first. This means that higher numbered series sit on top and potentially obscure lower numbered series.

More information about using SChartSeries can be found in the user guide.

Properties

_selectedStyle

Manages the appearance of the chart series when it is selected.

@property (nonatomic, retain) SChartSeriesStyle *_selectedStyle

Discussion

Style settings in this object will be applied when the series is marked as selected (or a point is selected).

The default settings of the style are inherited from the chart theme. You can tweak the appearance of the series by modifying the style.

Declared In

SChartSeries.h

_style

Manages the appearance of the chart series on the chart.

@property (nonatomic, retain) SChartSeriesStyle *_style

Discussion

The default settings of the style are inherited from the chart theme. You can tweak the appearance of the series by modifying the style.

Declared In

SChartSeries.h

crosshairEnabled

Display a tooltip with connecting lines after the user taps-and-holds.

@property (nonatomic) BOOL crosshairEnabled

Discussion

For line series, the tooltip will appear on the nearest series and interpolate values between data points. For column/bar series the crosshair will snap to the nearest column or bar. Once a crosshair is visible it is locked to that current series. It will ignore other series until it is dismissed and re-established on a different series. To dismiss the crosshair the user performs a single tap on the chart. By default, this property is set to NO.

Warning: Currently, animation is not supported on radial series (SChartRadialLineSeries).

Declared In

SChartSeries.h

dataSeries

SChartDataSeries gives you access to the set of data points in the series.

@property (nonatomic, retain) SChartDataSeries *dataSeries

Discussion

It contains the data values only, it is not concerned with the appearance of the series on the chart. The data series is provided to allow you to query the data values in the series, you should not try and use this to modify the series. If you wish to modify the data in the series, you should update the chart datasource, and then call [ShinobiChart reloadData].

Declared In

SChartSeries.h

hidden

Dictates whether or not a series is hidden on the chart.

@property (nonatomic) BOOL hidden

Discussion

If the hidden property of a chart series is set to YES, then the series will not be drawn on the chart. If this property is set to NO, the series will be drawn as usual. By default, this property is set to NO.

NOTE: In a future version this will no longer trigger an animation on the series, instead use the chart’s animationTracker methods: showSeries:animation:completion: or hideSeries:animation:completion:.

Declared In

SChartSeries.h

legendItem

The object responsible for providing the title and SChartLegendSymbol item for representing this symbol in the legend.

@property (nonatomic, assign) id<SChartLegendItem> legendItem

Discussion

By default, this property is set to the series itself.

Declared In

SChartSeries.h

numberOfDataPointsPerBin

The number of datapoints that are rendered in a single pass. As render passes are expensive, this defaults to the number of datapoints in this series (this is only populated after a data load).

@property (nonatomic, retain) NSNumber *numberOfDataPointsPerBin

Discussion

Note that if your use-cases makes heavy use of appending and/or removing datapoints, then you may want to lower this, so a smaller “bin” / fewer datapoints need to be re-rendered per append/remove.

Declared In

SChartSeries.h

orientation

The orientation of the chart axis which is associated with the series.

@property (nonatomic, assign) SChartSeriesOrientation orientation

Discussion

It is defined as follows:

  • SChartSeriesOrientationHorizontal: Configures the orientation of the chart axis which is associated with the series to be horizontal. Thus the controlled variable will be drawn on the x-axis, while the measured variable will be drawn on the y-axis.
  • SChartSeriesOrientationVertical: Configures the orientation of the chart axis which is associated with the series to be vertical. Thus the controlled variable will be drawn on the y-axis, while the measured variable will be drawn on the x-axis.

For example, the orientation for column series is SChartSeriesOrientationHorizontal, and the orientation for bar series is SChartSeriesOrientationVertical.

Declared In

SChartSeries.h

selected

Whether or not the series is selected

@property (nonatomic, assign) BOOL selected

Declared In

SChartSeries.h

selectedDataPoints

A set of selected datapoints.

@property (nonatomic, strong) NSSet<id<SChartData> > *selectedDataPoints

Discussion

This is kept up to date with the datapoints that are selected on screen.

This can be set by the user to programmatically select datapoints.

Declared In

SChartSeries.h

selectionMode

Defines what should be selected when the user taps the chart.

@property (nonatomic) SChartSelection selectionMode

Discussion

This property defines how the series will respond when a tap gesture indicates a point on this series.

The selection modes are defined as follows:

  • SChartSelectionNone: Configures this series to select nothing when it is tapped.
  • SChartSelectionPoint: Configures this series to select a point when it is tapped.
  • SChartSelectionSeries: Configures this series to select the series when it is tapped.

There is an important effect of choosing SChartSelectionNone - this option will remove this series from the algorithm that searches for the nearest point to the tap. Hence, a user may tap near to this series - but the algorithm will select a different series based upon its proximity.

Warning: Currently selection isn’t supported for radial series (SChartRadialLineSeries). Furthermore, selection is handled seperately for pie/donut series - selectionMode, toggleSelection, and togglePointSelection are only applicable to cartesian series.

Declared In

SChartSeries.h

showInLegend

Whether or not the series should be represented in the legend

@property (nonatomic, assign) BOOL showInLegend

Discussion

By default, this property is set to YES.

Declared In

SChartSeries.h

title

The title of the series to be displayed in the legend.

@property (nonatomic, retain) NSString *title

Declared In

SChartSeries.h

togglePointSelection

Dictates whether the series should only allow only one selected point at a time.

@property (nonatomic) BOOL togglePointSelection

Discussion

If this is set to NO, the series will de-select all other points in this series before selecting the tapped point. Setting YES will allow multiple points to be selected (“toggled”) as they are tapped. NOTE: This is per series and will allow multiple points to be selected across series regardless of value. To enable single point selection across all of the series for the chart, use the chart delegate.

By default, this property is set to NO.

Declared In

SChartSeries.h

toggleSelection

Dictates whether the chart should allow other series to be selected simultaneously.

@property (nonatomic) BOOL toggleSelection

Discussion

If this is set to NO, the chart will de-select all other series before selecting the tapped series. Setting YES will allow multiple series to be selected (“toggled”) as they are tapped.

By default, this property is set to NO.

Declared In

SChartSeries.h

Instance Methods

centreXOfDataPointAtIndex:onChart:

Returns, in data terms, the x component of the point upon which the datapoint at the given index is centered.

- (id)centreXOfDataPointAtIndex:(NSInteger)index onChart:(ShinobiChart *)chart

Discussion

Warning: Currently, this method is not supported on radial series (SChartRadialLineSeries).

Declared In

SChartSeries.h

centreYOfDataPointAtIndex:onChart:

Returns, in data terms, the y component of the point upon which the datapoint at the given index is centered.

- (id)centreYOfDataPointAtIndex:(NSInteger)index onChart:(ShinobiChart *)chart

Discussion

Warning: Currently, this method is not supported on radial series (SChartRadialLineSeries).

Declared In

SChartSeries.h

comparatorForValueKeys

If the chart ever needs to know about the order in which the value-keys belonging to this series should be used then this method is called for an appropriate comparator.

- (NSComparator)comparatorForValueKeys

Discussion

For example, an SChartCrosshairMultiValueTooltip needs to know the order in which to display its dictionary of key-value pairs.

Declared In

SChartSeries.h

heightOfDataPointAtIndex:onChart:

Returns the width, in data terms, of the datapoint at the given index.

- (id)heightOfDataPointAtIndex:(NSInteger)index onChart:(ShinobiChart *)chart

Discussion

Warning: Currently, this method is not supported on radial series (SChartRadialLineSeries).

Declared In

SChartSeries.h

primarySeriesColorForDatapoint:

Extracts the predominant color of the series for a specified datapoint.

- (nullable UIColor *)primarySeriesColorForDatapoint:(id<SChartData>)datapoint

Parameters

datapoint

The datapoint for which we want to retrieve the primary color

Return Value

The primary color associated with the specfied datapoint

Declared In

SChartSeries.h

resetForReuse

Resets the chart series for reuse when the data in the chart is reloaded.

- (void)resetForReuse

Discussion

By default, this clears the data points in the chart series, while leaving the styling, animation and any other series properties intact. If you subclass SChartSeries, you should add any custom implementation you require to the subclass.

Declared In

SChartSeries.h

stringForKey:withDataPoint:

This method returns a string value that will represent the key of a given datapoint.

- (NSString *)stringForKey:(NSString *)key withDataPoint:(id<SChartData> _Nullable)dataPoint

Parameters

key

The key that needs a string representation.

dataPoint

The data point that the key corresponds to.

Return Value

A string that will be used to represent the given key for a data point.

Discussion

The multi value tooltip uses this method to decide what string to use in its labels for the key of a given datapoint.

Declared In

SChartSeries.h

stringForValueWithKey:withDataPoint:usingAxis:

This method returns a string value that will represent the value of a given data point based on its key.

- (NSString *)stringForValueWithKey:(NSString *)key withDataPoint:(id<SChartData>)dataPoint usingAxis:(SChartAxis *_Nullable)axis

Parameters

key

The key that corresponds to the value needing a string representation.

dataPoint

The data point that the value corresponds to.

The

axis that the value corresponds to, where nil represents an axis independent value.

Return Value

A string that will be used to represent a value for a data point.

Discussion

This relies on the data point responding to the appropriate optional method (sChartValueForKey:, sChartXValueForKey: or sChartYValueForKey:).

Declared In

SChartSeries.h

valueKeys

Used for data points which contain values that are independent of axes (e.g. Bubble data points). Returns the keys for the axis independent values of the data point.

- (NSArray<NSString *> *)valueKeys

Declared In

SChartSeries.h

widthOfDataPointAtIndex:onChart:

Returns the width, in data terms, of the datapoint at the given index.

- (id)widthOfDataPointAtIndex:(NSInteger)index onChart:(ShinobiChart *)chart

Discussion

Warning: Currently, this method is not supported on radial series (SChartRadialLineSeries).

Declared In

SChartSeries.h

xValueKeys

Used for data points which contain multiple values (e.g. OHLC data points). Returns the keys for the x values of the data point.

- (NSArray<NSString *> *)xValueKeys

Declared In

SChartSeries.h

yValueKeys

Used for data points which contain multiple values (e.g. OHLC data points). Returns the keys for the y values of the data point.

- (NSArray<NSString *> *)yValueKeys

Declared In

SChartSeries.h