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 labelProvider property, which allows a class to be attached to an axis for complete control over axis label output.
Use a LabelProviderBase<T> 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 textFormatting as you zoom in or out.
- Dynamically change the textFormatting depending on Data-value.
By default each axis has a ILabelProvider 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 Android.
Label Provider Type | Provide labels For |
---|---|
NumericLabelProvider | NumericAxis |
LogarithmicNumericLabelProvider | LogarithmicNumericAxis |
DateLabelProvider | DateAxis |
TradeChartAxisLabelProvider | CategoryDateAxis |
The above label providers are inherited from FormatterLabelProviderBase<T> which format labels using ILabelFormatter<T> provided by inheritors. So if you want to customize the default formatting of the above - provide custom ILabelFormatter<T> into the appropriate constructors.
Creating custom ILabelFormatter
To create custom ILabelFormatter<T>, you will need to implement the following methods:
- update(T axis) - is called from associated FormatterLabelProviderBase<T> to update this label formatter with values provided by axis.
- formatLabel(double dataValue) - is called internally for every axis tick value to get a text to show for corresponding axis label.
- formatCursorLabel(double dataValue) - is called to format data values for axis overlays, such as CursorModifier axis labels.
Let's create custom ILabelFormatter<T> for NumericAxis
class NumericLabelFormatter extends LabelFormatterBase<INumericAxis> {
@Override
public void update(INumericAxis iAxisCore) {}
@Override
public CharSequence formatLabel(double dataValue) {
// return a formatting string for tick labels
return String.format("%.3f", dataValue);
}
@Override
public CharSequence formatCursorLabel(double dataValue) {
// return a formatting string for modifiers' axis labels
return formatLabel(dataValue);
}
}
NumericAxis axis = new NumericAxis(getContext());
// create a NumericLabelProvider with custom ILabelFormatter and assign it to the axis
axis.setLabelProvider(new NumericLabelProvider(new NumericLabelFormatter()));
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 LabelProviderBase<T> and provide the proper IAxis interface, 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 CursorModifier axis labels.
As mentioned above - the LabelProvider can be assigned to an axis via the labelProvider property.
Let's create custom LabelProvider for DateAxis
class DateLabelProvider extends LabelProviderBase<IDateAxis> {
final SimpleDateFormat dateFormatter = new SimpleDateFormat("yyyy MMM dd");
DateLabelProvider() {
super(IDateAxis.class);
}
@Override
public CharSequence formatLabel(Comparable dataValue) {
final double doubleValue = ComparableUtil.toDouble(dataValue);
return formatLabel(doubleValue);
}
@Override
public CharSequence formatCursorLabel(Comparable dataValue) {
final double doubleValue = ComparableUtil.toDouble(dataValue);
return formatCursorLabel(doubleValue);
}
@Override
public CharSequence formatLabel(double dataValue) {
return dateFormatter.format(dataValue);
}
@Override
public CharSequence formatCursorLabel(double dataValue) {
return formatLabel(dataValue);
}
}
NumericAxis axis = new NumericAxis(getContext());
// create a custom DateLabelProvider and assign it to the axis
axis.setLabelProvider(new DateLabelProvider());
Note
dataValue parameter in - - formatLabel(Comparable dataValue) and - formatCursorLabel(Comparable dataValue) is always a double. It is different for different axis types:
- For a NumericAxis - the double-representation of the data.
- For a DateAxis - the getTime()
- For a CategoryDateAxis - dataValue is the index to the data-series.
More examples of LabelProvider usage
Several of the SciChart Android Chart Examples use the LabelProvider, including the following: