SChartDatasource Protocol Reference

Conforms to NSObject
Declared in SChartDatasource.h
Availability Standard
Premium
Related samples Area
BarChart
ColumnChart
FinancialChart
LargeDataSet
LineChart
PieChart

Overview

The SChartDatasource protocol is adopted by an object that wishes to provide data for a ShinobiChart. The data source provides the chart with the information it needs to construct the chart object. In general, styling and event response is handled by objects implementing the SChartDelegate protocol - the data source has minimal impact on the look and feel of the chart.

The required methods provide the chart with information about all of the series to be displayed on that chart - and the data for those series. The relevant chart object is always returned - to support the option of using a single object as the data source for multiple charts.

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

Instance Methods

getLabelsForRadialChartSeries:forIndex:

- (UILabel *)getLabelsForRadialChartSeries:(SChartSeries *)series forIndex:(NSInteger)sliceIndex

Discussion

Returns a UILabel corresponding to the ‘slice’ of the specified pie/donut chart series at the given index.

If this method is implemented and a non-nil UILabel is returned for a ‘slice’ in a radial chart series, that UILabel will be added to the chart.

Declared In

SChartDatasource.h

numberOfSeriesInSChart:NS_SWIFT_NAME:

Returns the number of series in the given chart. For each of these series, the chart will expect to receive a SChartSeries object from the datasource, through the sChart:seriesAtIndex: method.

- (NSInteger)numberOfSeriesInSChart:(ShinobiChart *)chart NS_SWIFT_NAME

Parameters

chart

The chart for which the datasource is providing data.

Declared In

SChartDatasource.h

sChart:dataPointAtIndex:forSeriesAtIndex:

Returns the object that represents the data point at the given index in the specified chart series.

- (id<SChartData>)sChart:(ShinobiChart *)chart dataPointAtIndex:(NSInteger)dataIndex forSeriesAtIndex:(NSInteger)seriesIndex

Parameters

chart

The chart on which the data point will be drawn.

dataIndex

The index of the data point in the chart series which contains it.

seriesIndex

The index of the series which contains the data point, in the chart.

Discussion

The number of points in each series is set by the sChart:numberOfDataPointsForSeriesAtIndex: method.

The data point can be any object that implements the SChartData protocol. We provide a set of data point classes which can be used. These are:

Declared In

SChartDatasource.h

sChart:dataPointsForSeriesAtIndex:

Returns an array containing the data points for the series at the given index.

- (NSArray<id<SChartData>> *)sChart:(ShinobiChart *)chart dataPointsForSeriesAtIndex:(NSInteger)seriesIndex

Parameters

chart

The chart which will display the data points.

seriesIndex

The index of the series in the chart.

Discussion

You can pre-create and cache the data points in an array, and present this array to the chart using this method. This is more efficient than querying the datasource for its data points one at a time.

Declared In

SChartDatasource.h

sChart:labelForSliceAtIndex:inRadialSeries:

Returns a UILabel corresponding to a ‘slice’ of a radial chart series.

- (UILabel *)sChart:(ShinobiChart *)chart labelForSliceAtIndex:(NSInteger)sliceIndex inRadialSeries:(SChartRadialSeries *)series

Parameters

chart

The chart containing the radial series.

sliceIndex

The index of the slice of interest within the specified chart series.

series

The chart series which contains the slice of interest.

Discussion

If this method is implemented and a non-nil UILabel is returned for the given ‘slice’ in the radial chart series, that UILabel will be added to the chart.

Warning: The ‘series’ parameter will change to type SChartSeries to cope with SChartRadialSeries being removed in a future release.

Declared In

SChartDatasource.h

sChart:majorTickValuesForAxis:

Returns an array of major tick mark values, to be used by the given chart axis.

- (NSArray *_Nullable)sChart:(ShinobiChart *)chart majorTickValuesForAxis:(SChartAxis *)axis

Parameters

chart

The chart containing the axis.

axis

The axis for which we are setting the major tick values.

Discussion

If this method is implemented, the major tick marks on the axis will be fixed as the values in the array. No other values will be calculated or interpolated.

Objects in the array should be instances of the class used in your data source (corresponding to the axis type), e.g. NSNumber, NSDate, etc.

Declared In

SChartDatasource.h

sChart:numberOfDataPointsForSeriesAtIndex:

Returns the number of data points in the specified series.

- (NSInteger)sChart:(ShinobiChart *)chart numberOfDataPointsForSeriesAtIndex:(NSInteger)seriesIndex

Parameters

chart

The chart on which the series will be displayed.

seriesIndex

The index of the given series in the chart, which will contain the data points.

Discussion

For each of the data points in the series, the chart will expect to receive an object that adopts the SChartData protocol. Data points will be provided to the chart either via the sChart:dataPointAtIndex:forSeriesAtIndex: method, or via the sChart:dataPointsForSeriesAtIndex: method.

Declared In

SChartDatasource.h

sChart:seriesAtIndex:

Returns the SChartSeries object at the given index in the specified chart.

- (SChartSeries *)sChart:(ShinobiChart *)chart seriesAtIndex:(NSInteger)index

Parameters

chart

The chart on which the series will be displayed.

index

The index of the given series in the chart.

Discussion

The number of SChartSeries in the chart are specified by the numberOfSeriesInSChart: method.

The order is important for some series layouts - lower index series are placed on the chart first and will be behind subsequent series.

The chart can display multiple series at any one time, however, series are only compatible with series in the same group. A list of all available series & their respective categories is available below:

This is the Cartesian group

This is the Pie/Donut group

This is the Radial group

To find out more about series compatibility read The Anatomy of the chart section of our user guide.

When you reload data on a chart, resetForReuse is called on its chart series. If you are persisting your chart series between data reloads, you should take this into account. resetForReuse clears the data points on the chart series, while leaving styling, animation and other series properties intact.

Declared In

SChartDatasource.h

sChart:xAxisForSeriesAtIndex:

Returns the x axis for this series on the chart.

- (SChartAxis *_Nullable)sChart:(ShinobiChart *)chart xAxisForSeriesAtIndex:(NSInteger)index

Parameters

chart

The chart containing the axis.

index

The index of the chart series within the chart.

Discussion

If this method is implemented the chart will look here for which axis to use when representing this series, otherwise this series will default to using the primary x axis on the chart.

Hint: This is only needed on charts with multiple axes.

Note: The SChartAxis returned should be referenced from an existing chart axis and not a new object. eg: return chart.xAxis

To specify an axis for some series and not for others, returning nil for a series index will revert to the default behaviour for that series.

Declared In

SChartDatasource.h

sChart:yAxisForSeriesAtIndex:

The y-axis for this series on the chart

- (SChartAxis *_Nullable)sChart:(ShinobiChart *)chart yAxisForSeriesAtIndex:(NSInteger)index

Parameters

chart

The chart containing the axis.

index

The index of the chart series within the chart.

Discussion

If this method is implemented the chart will look here for which axis to use when representing this series, otherwise this series will default to using the primary y axis on the chart.

Hint: This is only needed on charts with multiple axes.

Note: The SChartAxis returned should be referenced from an existing chart axis and not a new object. eg: return chart.yAxis

To specifiy an axis for some series and not for others, returning nil for a series index will revert to the default behaviour for that series.

Declared In

SChartDatasource.h

sChartInnerRadiusForDataPoint:dataPointAtIndex:forSeriesAtIndex:NS_SWIFT_NAME:

Returns the inner radius of the given data point, in points.

- (CGFloat)sChartInnerRadiusForDataPoint:(ShinobiChart *)chart dataPointAtIndex:(NSInteger)dataIndex forSeriesAtIndex:(NSInteger)seriesIndex NS_SWIFT_NAME

Parameters

chart

The chart containing the data point.

dataIndex

The index of the data point in the series which contains it.

seriesIndex

The index of the series in the chart which contains the data point.

Discussion

By default, data points on the chart are displayed as two circles, one inside the other. The inner radius of a data point defines the radius of the inner circle in its representation on the chart.

If you implement this method, and it returns a positive, non-zero value, that radius is used for the inner circle on the given data point in the specified series on the chart.

Declared In

SChartDatasource.h

sChartRadiusForDataPoint:dataPointAtIndex:forSeriesAtIndex:NS_SWIFT_NAME:

Returns the radius of the given data point, in points.

- (CGFloat)sChartRadiusForDataPoint:(ShinobiChart *)chart dataPointAtIndex:(NSInteger)dataIndex forSeriesAtIndex:(NSInteger)seriesIndex NS_SWIFT_NAME

Parameters

chart

The chart containing the data point.

dataIndex

The index of the data point in the series which contains it.

seriesIndex

The index of the series in the chart which contains the data point.

Discussion

By default, data points on the chart are displayed as two circles, one inside the other. The radius of a data point defines the radius of the outer circle in its representation on the chart.

If you implement this method, and it returns a positive, non-zero value, that radius is used for the given data point in the specified series on the chart.

If a texture is used for a datapoint, the radius will set the size of the longest dimension of the image. The shorter of the two dimensions will update to keep aspect ratio.

Declared In

SChartDatasource.h

sChartTextureForPoint:dataPointAtIndex:forSeriesAtIndex:NS_SWIFT_NAME:

Returns an image to be displayed for the specified data point in the chart.

- (UIImage *_Nullable)sChartTextureForPoint:(ShinobiChart *)chart dataPointAtIndex:(NSInteger)dataIndex forSeriesAtIndex:(NSInteger)seriesIndex NS_SWIFT_NAME

Parameters

chart

The chart containing the data point.

dataIndex

The index of the data point within the series which contains it.

seriesIndex

The index of the series in the chart which contains the data point.

Discussion

If you implement this method, and it returns a non-nil image for the specified data point, that image will be displayed for the data point in the chart.

Declared In

SChartDatasource.h