SChartDelegate Protocol Reference

Conforms to NSObject
Declared in SChartDelegate.h
Availability Standard
Premium
Related samples

Overview

The delegate of a ShinobiChart object must adopt the SChartDelegate protocol. Optional methods of the protocol allow the delegate to respond to the following types of events:

  • Axis range changes.
  • Selection on the chart.
  • Chart rendering.
  • Data loading.
  • Chart series animations.
  • Crosshair tracking.

As well as methods to respond to events on the chart, the protocol also provides methods to allow the delegate to manage the chart axes, by altering tick marks on the axes, or by setting tick frequencies.

More information about how to use the SChartDelegate can be found in the user guide.

Instance Methods

sChart:alterDataPointLabel:forDataPoint:inSeries:NS_SWIFT_NAME:

Alter a data point label before it is added to the chart.

- (void)sChart:(ShinobiChart *)chart alterDataPointLabel:(SChartDataPointLabel *)label forDataPoint:(SChartDataPoint *)dataPoint inSeries:(SChartSeries *)series NS_SWIFT_NAME

Parameters

chart

The chart containing the label.

label

The label being added to the chart.

series

The series containing the data point.

datapoint

The data point on the chart to which the label applies.

Discussion

This method gives you each data point label for each series before it is added to the chart. Use this to set colors, borders, or reposition the label.

Declared In

SChartDelegate.h

sChart:alterLabel:forDatapoint:atSliceIndex:inRadialSeries:NS_SWIFT_NAME:

Alter a pie/donut label before it is added to the chart.

- (void)sChart:(ShinobiChart *)chart alterLabel:(UILabel *)label forDatapoint:(SChartRadialDataPoint *)datapoint atSliceIndex:(NSInteger)index inRadialSeries:(SChartRadialSeries *)series NS_SWIFT_NAME

Parameters

chart

The chart containing the pie/donut label.

label

The pie/donut label being added to the chart.

datapoint

The data point on the chart to which the label applies.

index

The index of the data point in its pie/donut series.

series

The pie/donut series containing the data point.

Discussion

This method gives you each label for each pie/donut series before it is added to the chart. Use this to set colors, borders, or reposition the label.

More information about using this method can be found in our tutorial ‘Pie chart labels that are out of this… slice’.

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

Declared In

SChartDelegate.h

sChart:alterTickMark:beforeAddingToAxis:

Alter a tick mark before it is added to an axis on the chart.

- (void)sChart:(ShinobiChart *)chart alterTickMark:(SChartTickMark *)tickMark beforeAddingToAxis:(SChartAxis *)axis

Parameters

chart

The chart containing the tick marks.

tickMark

The tick mark which will be added to its axis.

axis

The axis on the chart to which the tick mark will be added.

Discussion

This method gives you each tick mark just before it is added to its axis. Use this to set colors, borders, or even move the tickmark’s label elsewhere.

Warning: This method is called after the labels are positioned and tick label collision has been accounted for. Use the axis' labelFormatter property to format tick labels before these calculations.

Declared In

SChartDelegate.h

sChart:crosshairMovedToXValue:andYValue:NS_SWIFT_NAME:

Notifies the user when the crosshair moves.

- (void)sChart:(ShinobiChart *)chart crosshairMovedToXValue:(id)x andYValue:(id)y NS_SWIFT_NAME

Parameters

chart

The chart containing the crosshair.

x

The x value of the current crosshair position.

y

The y value of the current crosshair position.

Discussion

When the crosshair is panned, the new values at the crosshair point are passed into this method. For a line series, the values will be interpolated if they lie between actual data points. On a category axis - or bar/column series - the crosshair will snap to the discrete values.

Declared In

SChartDelegate.h

sChart:didAlterRangeOnAxis:

A notfication that the range has been changed on the specified axis.

- (void)sChart:(ShinobiChart *)chart didAlterRangeOnAxis:(SChartAxis *)axis

Discussion

This delegate method will be invoked in all cases where an axis range changes, including: - setting the axis' range - a user is performing a zooming/panning gesture - the chart is momentum zooming/panning - the chart is bouncing back after being zoomed/panned outside its max range

Declared In

SChartDelegate.h

sChart:didFinishAnimatingAxis:

A notfication that the specified axis has finished animating.

- (void)sChart:(ShinobiChart *)chart didFinishAnimatingAxis:(SChartAxis *)axis

Discussion

This delegate method will be invoked in all cases where an axis animation completes, including: - setting the axis' range passing withAnimation:YES - a user finishes a zooming/panning gesture and the enableMomentumPanning/enableMomentumZooming properties are YES, causing the axis to animate to a stop - the chart finishes bouncing back after being zoomed/panned outside its max range

Declared In

SChartDelegate.h

sChart:longestLabelStringOnAxis:

Assist the chart in calculating tick label lengths. This is useful when you provide an implementation for sChart:alterTickMark:beforeAddingToAxis:

- (NSString *_Nullable)sChart:(ShinobiChart *)chart longestLabelStringOnAxis:(SChartAxis *)axis

Parameters

chart

The chart containing the axis.

axis

The axis for which we are returning the longest tick label string.

Return Value

A string of the right size, from which the axis can deduce the maximum amount of space that tick mark labels will require.

Discussion

For example, if you lengthen the tick label strings in alterTickMark, you should hint to the axis that extra room will be required by implementing this method.

The actual contents of this string are ignored, only its size with the current tick-label font is used. For example, if you are using a currency format, a string like @“$#.##” will ensure sufficient room is calculated. Return nil for the chart to use automatically calculated values for the tick label lengths.

Declared In

SChartDelegate.h

sChart:radialSeriesDidEndDecelerating:

A notification that a pie/donut series has come to a halt after being panned and released.

- (void)sChart:(ShinobiChart *)chart radialSeriesDidEndDecelerating:(SChartRadialSeries *)radialSeries

Parameters

chart

The chart containing the pie/donut series.

radialSeries

The pie/donut series which has finished panning.

Discussion

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

Declared In

SChartDelegate.h

sChart:radialSeriesDidStartPanning:

A notification that we have started panning on a pie/donut series.

- (void)sChart:(ShinobiChart *)radial radialSeriesDidStartPanning:(SChartRadialSeries *)radialSeries

Parameters

radial

The chart containing the pie/donut series which has started panning.

radialSeries

The pie/donut series being panned.

Discussion

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

Declared In

SChartDelegate.h

sChart:radialSeriesIsPanning:

A notification that a pie/donut series is being panned.

- (void)sChart:(ShinobiChart *)radial radialSeriesIsPanning:(SChartRadialSeries *)radialSeries

Parameters

radial

The chart containing the pie/donut series.

radialSeries

The pie/donut series being panned.

Discussion

The rotation of the series is updated as the user pans the chart. You can query the current rotation of the series using the [SChartDonutSeries rotation] property.

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

Declared In

SChartDelegate.h

sChart:radialSeriesWillBeginDecelerating:

A notification that a panning gesture on a pie/donut series has ended, and the series will begin to decelerate.

- (void)sChart:(ShinobiChart *)chart radialSeriesWillBeginDecelerating:(SChartRadialSeries *)radialSeries

Parameters

chart

The chart containing the pie/donut series.

radialSeries

The pie/donut series which has started to decelerate.

Discussion

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

Declared In

SChartDelegate.h

sChart:setMajorTickFrequency:andMinorTickFrequency:onGeneratingTickMarksforAxis:NS_SWIFT_NAME:

Set the major and minor tick frequencies for an axis.

- (void)sChart:(ShinobiChart *)chart setMajorTickFrequency:(id _Nullable *const _Nonnull)majorTickFrequency andMinorTickFrequency:(id _Nullable *const _Nonnull)minorTickFrequency onGeneratingTickMarksforAxis:(SChartAxis *)axis NS_SWIFT_NAME

Parameters

chart

The chart containing the axis.

majorTickFrequency

A pointer to the major tick frequency on the axis. If you set this value, the axis will update to use the new value.

minorTickFrequency

A pointer to the minor tick frequency on the axis. If you set this value, the axis will update to use the new value.

axis

The axis for which we are setting the tick frequencies.

Discussion

Implement this method to customize your major and minor tick frequencies depending on the state of the axis.

Set the majorTickFrequency and minorTickFrequency pointers to objects of your choosing.

Not setting the minorTickFrequency, or setting it to nil, will result in minor ticks not being displayed. You should set frequencies of the correct type to match the axis - for example, SChartDateFrequency for SChartDateTimeAxis, or NSNumber for SChartNumberAxis.

Declared In

SChartDelegate.h

sChart:toggledSelectionForPoint:inSeries:atPixelCoordinate:NS_SWIFT_NAME:

A notification that a data point has been selected or de-selected.

- (void)sChart:(ShinobiChart *)chart toggledSelectionForPoint:(id<SChartData>)dataPoint inSeries:(SChartSeries *)series atPixelCoordinate:(CGPoint)pixelPoint NS_SWIFT_NAME

Parameters

chart

The chart on which the selection has occurred.

dataPoint

The data point which was selected or de-selected.

series

The chart series which contains that data point.

pixelPoint

The pixel coordinates of that data point.

Discussion

A touch gesture has resulted in the closest data point to be added to our selectedDataPoints set. This data point is passed into the method along with the current pixel coordinates of that point and the series that it belongs to.

Declared In

SChartDelegate.h

sChart:toggledSelectionForRadialPoint:inSeries:atPixelCoordinate:NS_SWIFT_NAME:

A notification that a data point on a pie/donut chart has changed state to ‘selected’ from ‘deselected’ or vice versa.

- (void)sChart:(ShinobiChart *)chart toggledSelectionForRadialPoint:(SChartRadialDataPoint *)dataPoint inSeries:(SChartRadialSeries *)series atPixelCoordinate:(CGPoint)pixelPoint NS_SWIFT_NAME

Parameters

chart

The chart on which the selection occurred.

dataPoint

The data point which was selected or de-selected.

series

The pie/donut series which contains the data point.

pixelPoint

The pixel coordinate of the data point.

Discussion

Theselected property of the data point has changed. This could be as a result of a tap gesture on the chart, or of programmatically selecting the point (setSlice:asSelected). The data point is returned along with the series that it belongs to and the pixel coordinates of the tap, if any.

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

Declared In

SChartDelegate.h

sChart:toggledSelectionForSeries:nearPoint:atPixelCoordinate:NS_SWIFT_NAME:

A notification that a series has been selected or de-selected.

- (void)sChart:(ShinobiChart *)chart toggledSelectionForSeries:(SChartSeries *)series nearPoint:(SChartDataPoint *)dataPoint atPixelCoordinate:(CGPoint)pixelPoint NS_SWIFT_NAME

Parameters

chart

The chart on which the selection has occurred.

series

The series which has been selected or de-selected.

dataPoint

The nearest data point on that series to the point on the screen which was touched.

pixelPoint

The pixel coordinates of that data point.

Discussion

A touch gesture has resulted in the selected property of the series changing. The nearest data point is passed into the method along with the current pixel coordinates of that point.

Declared In

SChartDelegate.h

sChartDidFinishLoadingData:

A notification that the chart has finished loading its data.

- (void)sChartDidFinishLoadingData:(ShinobiChart *)chart

Parameters

chart

The chart which finished loading its data.

Discussion

This is called once the chart has finished loading its data, and before it starts rendering its plot area and axes. A common use of this method would be to close the activity indicator if you popped one up during loading. At this point, the chart axes will have been refreshed from the new data, so you could update the chart axes here before they are rendered. It is important to note that this method is only called when we load data, rather than each time the chart is rendered.

Declared In

SChartDelegate.h

sChartRenderFinished:

A notification that the chart object has finished rendering.

- (void)sChartRenderFinished:(ShinobiChart *)chart

Parameters

chart

The chart which has finished rendering.

Discussion

This is called once the chart has finished rendering its data. A common use case for this method would be to display the crosshair on the chart after it has rendered, or to add annotations onto the chart. You could also update other UI elements in your application so that they reflect the new state of the chart. You shouldn’t modify the chart plot area or its axes here, as any changes won’t be visualized until the next time that the chart is rendered.

Declared In

SChartDelegate.h

sChartRenderStarted:withFullRedraw:

A notification that the chart object has started rendering.

- (void)sChartRenderStarted:(ShinobiChart *)chart withFullRedraw:(BOOL)fullRedraw

Parameters

chart

The chart which has started rendering.

fullRedraw

If the chart is carrying out a full redraw, this argument is set to YES.

Discussion

This is called before the chart starts rendering its data. At this point, the chart axes will be up to date with your data, so a common use case of this method would be to update the chart axes before they are rendered, for example to modify the axis title or range.

Declared In

SChartDelegate.h

sChartWillStartLoadingData:

A notification that the chart will start loading its data.

- (void)sChartWillStartLoadingData:(ShinobiChart *)chart

Parameters

chart

The chart which started loading its data.

Discussion

At this point, the chart has been created, but it either doesn’t contain any data, or it is about to reload its data. You shouldn’t do anything with chart axes at this point, as they will be out of date with the new data. A common use case for this method would be to pop up an activity indicator if you think the data will take a long time to load.

Declared In

SChartDelegate.h