SChartDatasource

@protocol SChartDatasource <NSObject>

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.

  • 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.

    Declaration

    Objective-C

    - (NSInteger)numberOfSeriesInSChart:(nonnull ShinobiChart *)chart;

    Swift

    func numberOfSeries(in chart: ShinobiChart) -> Int

    Parameters

    chart

    The chart for which the datasource is providing data.

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

    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.

    Declaration

    Objective-C

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

    Swift

    func sChart(_ chart: ShinobiChart, seriesAt index: Int) -> SChartSeries

    Parameters

    chart

    The chart on which the series will be displayed.

    index

    The index of the given series in the chart.

  • Returns the number of data points in the specified series.

    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.

    Declaration

    Objective-C

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

    Swift

    func sChart(_ chart: ShinobiChart, numberOfDataPointsForSeriesAt seriesIndex: Int) -> Int

    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.

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

    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:

    Declaration

    Objective-C

    - (nonnull id<SChartData>)sChart:(nonnull 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.

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

    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.

    Declaration

    Objective-C

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

    Swift

    optional func sChart(_ chart: ShinobiChart, majorTickValuesFor axis: SChartAxis) -> [Any]?

    Parameters

    chart

    The chart containing the axis.

    axis

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

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

    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.

    Declaration

    Objective-C

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

    Parameters

    chart

    The chart which will display the data points.

    seriesIndex

    The index of the series in the chart.

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

    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.

    Declaration

    Objective-C

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

    Swift

    optional func sChart(_ chart: ShinobiChart, textureForDataPointAtIndex dataIndex: Int, forSeriesAtIndex seriesIndex: Int) -> UIImage?

    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.

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

    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.

    Declaration

    Objective-C

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

    Swift

    optional func sChart(_ chart: ShinobiChart, radiusForDataPointAtIndex dataIndex: Int, forSeriesAtIndex seriesIndex: Int) -> CGFloat

    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.

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

    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.

    Declaration

    Objective-C

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

    Swift

    optional func sChart(_ chart: ShinobiChart, innerRadiusForDataPointAtIndex dataIndex: Int, forSeriesAtIndex seriesIndex: Int) -> CGFloat

    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.

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

    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.

    Declaration

    Objective-C

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

    Swift

    optional func sChart(_ chart: ShinobiChart, labelForSliceAt sliceIndex: Int, in series: SChartRadialSeries) -> UILabel

    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.

  • Returns the x axis for this series on the chart.

    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.

    Declaration

    Objective-C

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

    Swift

    optional func sChart(_ chart: ShinobiChart, xAxisForSeriesAt index: Int) -> SChartAxis?

    Parameters

    chart

    The chart containing the axis.

    index

    The index of the chart series within the chart.

  • The y-axis for this series on the chart

    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.

    Declaration

    Objective-C

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

    Swift

    optional func sChart(_ chart: ShinobiChart, yAxisForSeriesAt index: Int) -> SChartAxis?

    Parameters

    chart

    The chart containing the axis.

    index

    The index of the chart series within the chart.