Axis Labels - LabelProvider API

LabelProvider API - Full Control over Axis Labels

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

Use the LabelProvider 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” not “1”, “2”, “3”
Dynamically change the Axis TextFormatting as you zoom in or out
Dynamically change the Axis TextFormatting depending on Data-value

Creating your own LabelProviders

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

DateTimeLabelProvider– used to provide labels on the DateTimeAxis.
NumericLabelProvider– used to provide labels on the NumericAxis and LogarithmicNumericAxis.
TimeSpanLabelProvider– used to provide labels on the TimeSpanAxis.
TradeChartAxisLabelProvider– used to provide labels on the CategoryDateTimeAxis.

If you create a LabelProvider, inherit from the correct class above, and override FormatLabel and FormatCursorLabel methods.

Creating a Custom NumericAxis LabelProvider

To create a custom label provider for the NumericAxis, we simply create a class that inherits NumericLabelProvider, and override FormatLabel() and optionally, FormatCursorLabel().

Other axis types require different base types. Please read the comments below for additional information.

Creating a Custom NumericAxis LabelProvider	Copy Code
// To create a LabelProvider for a NumericAxis or Log Axis, inherit NumericLabelProvider // .. for a DateTimeAxis, inherit DateTimeLabelProvider // .. for a TimeSpanAxis, inherit TimeSpanLabelProvider // .. for a CategoryDateTimeAxis, inherit TradeChartAxisLabelProvider public class CustomNumericLabelProvider : NumericLabelProvider { // Optional: called when the label provider is attached to the axis public override void Init(IAxis parentAxis) { // here you can keep a reference to the axis. We assume there is a 1:1 relation // between Axis and LabelProviders base.Init(parentAxis); } // Optional: called when the Axis Begins each drawing pass public override void OnBeginAxisDraw() { // e.g. here you can reset any counters or any other custom logic at the start // of an axis render pass } /// <summary> /// Formats a label for the axis from the specified data-value passed in /// </summary> /// <param name="dataValue">The data-value to format</param> /// <returns> /// The formatted label string /// </returns> public override string FormatLabel(IComparable dataValue) { // Note: Implement as you wish, converting Data-Value to string return dataValue.ToString(); // NOTES: // dataValue is always a double. // For a NumericAxis this is the double-representation of the data // For a DateTimeAxis, the conversion to DateTime is new DateTime((long)dataValue) // For a TimeSpanAxis the conversion to TimeSpan is new TimeSpan((long)dataValue) // For a CategoryDateTimeAxis, dataValue is the index to the data-series } /// <summary> /// Formats a label for the cursor, from the specified data-value passed in /// </summary> /// <param name="dataValue">The data-value to format</param> /// <returns> /// The formatted cursor label string /// </returns> public override string FormatCursorLabel(IComparable dataValue) { // Note: Implement as you wish, converting Data-Value to string return dataValue.ToString(); // NOTES: // dataValue is always a double. // For a NumericAxis this is the double-representation of the data // For a DateTimeAxis, the conversion to DateTime is new DateTime((long)dataValue) // For a TimeSpanAxis the conversion to TimeSpan is new TimeSpan((long)dataValue) // For a CategoryDateTimeAxis, dataValue is the index to the data-series } }

Creating a Custom NumericAxis LabelProvider

Copy Code

// To create a LabelProvider for a NumericAxis or Log Axis, inherit NumericLabelProvider
// ..  for a DateTimeAxis, inherit DateTimeLabelProvider
// ..  for a TimeSpanAxis, inherit TimeSpanLabelProvider
// ..  for a CategoryDateTimeAxis, inherit TradeChartAxisLabelProvider
public class CustomNumericLabelProvider : NumericLabelProvider
{
    // Optional: called when the label provider is attached to the axis
    public override void Init(IAxis parentAxis)
    {
        // here you can keep a reference to the axis. We assume there is a 1:1 relation
        // between Axis and LabelProviders
        base.Init(parentAxis);
    }

    // Optional: called when the Axis Begins each drawing pass
    public override void OnBeginAxisDraw()
    {
        // e.g. here you can reset any counters or any other custom logic at the start
        // of an axis render pass
    }

    /// <summary>
    /// Formats a label for the axis from the specified data-value passed in
    /// </summary>
    /// <param name="dataValue">The data-value to format</param>
    /// <returns>
    /// The formatted label string
    /// </returns>
    public override string FormatLabel(IComparable dataValue)
    {
        // Note: Implement as you wish, converting Data-Value to string
        return dataValue.ToString();

        // NOTES:
        // dataValue is always a double.
         // For a NumericAxis this is the double-representation of the data
         // For a DateTimeAxis, the conversion to DateTime is new DateTime((long)dataValue)
         // For a TimeSpanAxis the conversion to TimeSpan is new TimeSpan((long)dataValue)
          // For a CategoryDateTimeAxis, dataValue is the index to the data-series
    }

    /// <summary>
    /// Formats a label for the cursor, from the specified data-value passed in
    /// </summary>
    /// <param name="dataValue">The data-value to format</param>
    /// <returns>
    /// The formatted cursor label string
    /// </returns>
    public override string FormatCursorLabel(IComparable dataValue)
    {
        // Note: Implement as you wish, converting Data-Value to string
        return dataValue.ToString();

        // NOTES:
        // dataValue is always a double.
        // For a NumericAxis this is the double-representation of the data
        // For a DateTimeAxis, the conversion to DateTime is new DateTime((long)dataValue)
        // For a TimeSpanAxis the conversion to TimeSpan is new TimeSpan((long)dataValue)
        // For a CategoryDateTimeAxis, dataValue is the index to the data-series
    }
}

Declaring a custom LabelProvider

Assuming you have created a CustomNumericLabelProvider as above, you can apply it to an axis as follows:

XAML

Declaring a custom LabelProvider	Copy Code
<Grid> <Grid.Resources> <s:CustomNumericLabelProvider x:Key="LP"/> </Grid.Resources> <!-- Create the chart surface --> <!-- where xmlns:s="http://schemas.abtsoftware.co.uk/scichart" --> <s:SciChartSurface> <!-- Create XAxis --> <s:SciChartSurface.XAxis> <s:NumericAxis LabelProvider="{StaticResource LP}"/> </s:SciChartSurface.XAxis> <!-- Create YAxis --> <s:SciChartSurface.YAxis> <s:NumericAxis /> </s:SciChartSurface.YAxis> </s:SciChartSurface> </Grid>

Declaring a custom LabelProvider

Copy Code

<Grid>
    <Grid.Resources>
        <s:CustomNumericLabelProvider x:Key="LP"/>
    </Grid.Resources>
       
    <!--  Create the chart surface  -->
    <!-- where xmlns:s="http://schemas.abtsoftware.co.uk/scichart" -->
    <s:SciChartSurface>

        <!--  Create XAxis  -->
        <s:SciChartSurface.XAxis>
            <s:NumericAxis LabelProvider="{StaticResource LP}"/>
        </s:SciChartSurface.XAxis>

        <!--  Create YAxis  -->
        <s:SciChartSurface.YAxis>
            <s:NumericAxis />
        </s:SciChartSurface.YAxis>

    </s:SciChartSurface>
</Grid>

Code

Declaring a custom LabelProvider	Copy Code
var axis = new NumericAxis(); axis.LabelProvider = new CustomNumericLabelProvider();

Examples of the LabelProvider Use

Several of the SciChart WPF Chart Examples use the LabelProvider, including the WPF Stacked Column Chart Side by Side Example and the WPF Heatmap Chart with Text Example