iOS Charting Documentation - SciChart iOS Charts SDK v3.x

Axis Labels - LabelProvider API

In SciChart Axis Label is a representation of Values on the axes. Axis labels make it easier to read teh chart data. Our API allows to edit and customize them data in many ways to meet your needs, please read on to learn how!

All Axis Types include the ISCIAxisCore.labelProvider property, which allows a class to be attached to an axis for complete control over axis label output.

Use a SCILabelProviderBase inheritors when you want to:

  • Have fine grained control over Axis Text or Cursor Labels, depending on numeric (or date) values.
  • Display strings on the XAxis, e.g. “Bananas”, “Oranges”, “Apples” and not “1”, “2”, “3”.
  • Dynamically change the ISCIAxisCore.textFormatting as you zoom in or out.
  • Dynamically change the ISCIAxisCore.textFormatting depending on Data-value.

By default each axis has a ISCILabelProvider created and assigned to it. The type of LabelProvider depends on the type of Axis. Below is a table of the LabelProviders already defined in SciChart iOS.

Label Provider Type Provide labels For
SCINumericLabelProvider SCINumericAxis
SCILogarithmicNumericLabelProvider SCILogarithmicNumericAxis
SCIDateLabelProvider SCIDateAxis
SCITradeChartAxisLabelProvider SCICategoryDateAxis

The above label providers are inherited from SCIFormatterLabelProviderBase which format labels using ISCILabelFormatter provided by inheritors. So if you want to customize the default formatting of the above - provide custom ISCILabelFormatter into the appropriate constructors.

Creating custom ISCILabelFormatter

To create custom ISCILabelFormatter, you will need to implement the following methods:

Let’s create custom ISCILabelFormatter for SCINumericAxis

@interface NumericLabelFormatter : NSObject<ISCILabelFormatter> @end @implementation NumericLabelFormatter - (void)updateWithAxis:(id<ISCIAxisCore>)axis { } - (id<ISCIString>)formatLabel:(double)dataValue { // return a formatting string for tick labels return [NSString stringWithFormat:@“%.3f”, dataValue]; } - (id<ISCIString>)formatCursorLabel:(double)dataValue { // return a formatting string for modifiers’ axis labels return [self formatLabel:dataValue]; } @end … // create a SCINumericLabelProvider with custom ISCILabelFormatter and assign it to the axis axis.labelProvider = [[SCINumericLabelProvider alloc] initWithLabelFormatter:[NumericLabelFormatter new]];
class NumericLabelFormatter: ISCILabelFormatter { func update(_ axis: ISCIAxisCore!) { } func formatLabel(_ dataValue: Double) -> ISCIString! { // return a formatting string for tick labels return NSString(format: “%.3f”, dataValue) } func formatCursorLabel(_ dataValue: Double) -> ISCIString! { // return a formatting string for modifiers’ axis labels return formatLabel(dataValue) } } … // create a SCINumericLabelProvider with custom ISCILabelFormatter and assign it to the axis axis.labelProvider = SCINumericLabelProvider(labelFormatter: NumericLabelFormatter())
class NumericLabelFormatter: ISCILabelFormatter { public override void UpdateWithAxis(IISCIAxisCore axis) { } public override IISCIString FormatLabel(double dataValue) { // return a formatting string for tick labels return string.Format(“{0:0.00}”, dataValue).ToSciString(); } public override IISCIString FormatCursorLabel(double dataValue) { // return a formatting string for modifiers’ axis labels return FormatLabel(dataValue); } } … // create a SCINumericLabelProvider with custom ISCILabelFormatter and assign it to the axis axis.LabelProvider = new SCINumericLabelProvider(new NumericLabelFormatter());

Numeric LabelFormatter

NOTE: The other axis types require different LabelProvider types

Creating your own LabelProvider

You might want to create a your own, fully custom, LabelProvider. To do so, - we simply create a class that inherits SCILabelProviderBase and provide the proper ISCIAxis @protocol(), which should correspond to the axis which will use your label provider. From there, wou can override the following, similarly to the Label Formatter:

The first one is called internally for every axis tick value to get a text to show for corresponding axis label. The latter one is called to format data values for axis overlays, such as SCICursorModifier axis labels.

As mentioned above - the LabelProvider can be assigned to an axis via the ISCIAxisCore.labelProvider property.

Let’s create custom LabelProvider for SCIDateAxis

#import <SciChart/SCILabelProviderBase+Protected.h> @interface DateLabelProvider : SCILabelProviderBase @end @implementation DateLabelProvider { NSDateFormatter *_dateFormatter; } - (instancetype)init { self = [super initWithAxisType:@protocol(ISCIDateAxis)]; if (self) { _dateFormatter = [NSDateFormatter createWithFormat:@“hh:mm dd/mm/yyyy”]; } return self; } - (id<ISCIString>)formatLabel:(id<ISCIComparable>)dataValue { return [_dateFormatter stringFromDate:dataValue.toDate]; } - (id<ISCIString>)formatCursorLabel:(id<ISCIComparable>)dataValue { return [self formatLabel:dataValue]; } @end … axis.labelProvider = [DateLabelProvider new];
import SciChart.Protected.SCILabelProviderBase class DateLabelProvider : SCILabelProviderBase { let dateFormatter = DateFormatter.create(withFormat: “hh:mm dd/mm/yyyy”)! init() { super.init(axisType: ISCIDateAxis.self) } override func formatLabel(_ dataValue: ISCIComparable!) -> ISCIString! { return NSString(string: dateFormatter.string(from: dataValue.toDate())) } override func formatCursorLabel(_ dataValue: ISCIComparable!) -> ISCIString! { return formatLabel(dataValue) } } … axis.labelProvider = DateLabelProvider()
class DateLabelProvider: SCILabelProviderBase { public override IISCIString FormatLabel(IISCIComparable dataValue) { var date = dataValue.ToDate(); var dateTime = date.FromDate(); return dateTime.ToString(“hh:mm dd/mm/yyyy”).ToSciString(); } public override IISCIString FormatCursorLabel(IISCIComparable dataValue) { return FormatLabel(dataValue); } } … axis.LabelProvider = new DateLabelProvider();

Date LabelProvider

NOTE: dataValue parameter in - -[ISCILabelProvider formatLabel:] and -[ISCILabelProvider formatCursorLabel:] is always a double. It is different for different axis types:

More examples of LabelProvider usage

Several of the SciChart iOS Chart Examples use the LabelProvider, including the following:

See Also