Nevron .NET Vision Documentation
Scale Labels

Scale labels appear along the scale of the axis and denote values on the scale depending on a number of settings. This topic will discuss the options provided for automatic label customization by the NStandardScaleConfigurator derived classes only, as more specific configurators expose label styles / properties under different names.

Automatic Labels Formatting

Labels that are automatically generated by the scale are formatted using the LabelValueFormatter property of the NStandardScaleConfigurator class. This property accepts objects of type NNumericValueFormatter or NDateTimeValueFormatter. The following table shows the default label value formatter depending on the type of the scale configurator:

Configurator Label Value Formatter
NDateTimeScaleConfigurator NDateTimeValueFormatter with a format string showing the data according to the system date presentation settings.
NOrdinalScaleConfigurator NNumericValueFormatter formatting numbers with variable decimal places.
NLogarithmicScaleConfigurator NNumericValueFormatter formatting numbers with variable decimal places.
NLinearScaleConfigurator NNumericValueFormatter formatting numbers with variable decimal places.
Using Numeric Value Formatting

On numeric scales it is often useful to display the values in currency or percentage format. The following code snippets show how to do that:

  1. Display as currency
    C#
    Copy Code
    NCartesianChart chart = (NCartesianChart)nChartControl1.Charts[0];
    NAxis primaryY = chart.Axis(StandardAxis.PrimaryY);
    NStandardScaleConfigurator scaleConfigurator = (NStandardScaleConfigurator)primaryY.ScaleConfigurator;
    
    scaleConfigurator.LabelValueFormatter = new NNumericValueFormatter(NumericValueFormat.Currency);
    
    Visual Basic
    Copy Code
    Dim chart As NCartesianChart = NChartControl1.Charts(0)
    Dim primaryY As NAxis = chart.Axis(StandardAxis.PrimaryY)
    Dim scaleConfigurator As NStandardScaleConfigurator = CType(primaryY.ScaleConfigurator, NStandardScaleConfigurator)
    
    scaleConfigurator.LabelValueFormatter = New NNumericValueFormatter(NumericValueFormat.Currency)
    
  2. Display as percentage.
    C#
    Copy Code
    scaleConfigurator.ValueFormatter = new NNumericValueFormatter(NumericValueFormat.Percentage);
    
    Visual Basic
    Copy Code
    scaleConfigurator.ValueFormatter = New NNumericValueFormatter(NumericValueFormat.Percentage)
    
Using Date Time Value Formatting

To apply date time value formatting to the scale labels you need to create an instance of the NDateTimeValueFormatter. The following code will apply short 24 hour time formatting to the automatically generated labels:

C#
Copy Code
NChart chart = nChartControl1.Charts[0];
NAxis primaryX = chart.Axis(StandardAxis.PrimaryX);
NDateTimeScaleConfigurator dateTimeScale = (NDateTimeScaleConfigurator)primaryX.ScaleConfigurator;
dateTimeScale.LabelValueFormatter = new NDateTimeValueFormatter(DateTimeValueFormat.ShortTime24Hour);
dateTimeScale.EnableUnitSensitiveFormatting = false;
Visual Basic
Copy Code
Dim chart As NCartesianChart = NChartControl1.Charts(0)
Dim primaryX As NAxis = chart.Axis(StandardAxis.PrimaryX)
Dim dateTimeScale As NDateTimeScaleConfigurator = CType(primaryX.ScaleConfigurator, NDateTimeScaleConfigurator)
dateTimeScale.LabelValueFormatter = New NDateTimeValueFormatter(DateTimeValueFormat.ShortTime24Hour)
dateTimeScale.EnableUnitSensitiveFormatting = False
Unit Sensitive Formatting

Note that in the above code we turned off the unit sensitive formatting. Unit sensitive formatting allows you to specify a date time formatting, which is dependent on the date/time unit selected by the scale for the major ticks.

For example consider that you display date/time data which is gathered from a real time device at 5 second intervals. In this case the scale will choose a smaller date time unit depending on the number of data points - for example second or minute. Most likely you'll not need date or year information when you display data for one or two hours span. On the other hand if you display data for monthly or yearly sales the scale will choose a bigger date time unit (week, month, quarter, half year or year) and chances are you'll not need time information.

Unit sensitive formatting allows you to specify a date time formatting string depending on the date time unit selected by the scale for the major ticks.

Unit sensitive formatting is also very useful when you use DateTime scales with zooming and scrolling. In this case when you zoom in the scale will select smaller units (that show time information), respectively when you zoom out, the scale will select bigger units (with date information).

Date time units are implemented as singleton objects, which are accessible from the NDateTimeUnit base abstract class. The following table lists the date time units supported by the scale:

Unit Instance Description
Tick NDateTimeUnit.Tick Represents the tick date time unit. Ticks are the smallest measurable period of time for the scale. There are 10 million ticks in one second.
Millisecond NDateTimeUnit.Millisecond Represents the millisecond date time unit. There are one thousand milliseconds in on second
Second NDateTimeUnit.Second Represents the second date time unit (1000 milliseconds).
Minute NDateTimeUnit.Minute Represents the minute date time unit (60 seconds)
Hour NDateTimeUnit.Hour Represents the hour date time unit (60 minutes).
Half Day NDateTimeUnit.HalfDay Represents the half day date time unit (12 hours)
Day NDateTimeUnit.Day Represents the half day date time unit (24 hours)
Week NDateTimeUnit.Week Represents the half week date time unit (7 days)
Month NDateTimeUnit.Month Represents the month date time unit (28 to 31 days depending on the month and year)
Quarter NDateTimeUnit.Quarter Represents the quarter date time unit (3 months)
Half Year NDateTimeUnit.HalfYear Represents the half year date time unit (6 months)
Year NDateTimeUnit.Year Represents the year date time unit (12 months)
Decade NDateTimeUnit.Decade Represents the decade date time unit (10 years)
Century NDateTimeUnit.Century Represents a century date time unit (100 years)

At any point you may enable / disable the date time units that the scale can use for the major ticks. This is achieved by modifying the AutoDateTimeUnits array:

C#
Copy Code
NChart chart = nChartControl1.Charts[0];
NAxis primaryX = chart.Axis(StandardAxis.PrimaryX);
NDateTimeScaleConfigurator dateTimeScale = (NDateTimeScaleConfigurator)primaryX.ScaleConfigurator;

dateTimeScale.AutoDateTimeUnits = new NDateTimeUnit[] { NDateTimeUnit.Day, NDateTimeUnit.Month };
Visual Basic
Copy Code
Dim chart As NCartesianChart = NChartControl1.Charts(0)
Dim primaryX As NAxis = chart.Axis(StandardAxis.PrimaryX)
Dim dateTimeScale As NDateTimeScaleConfigurator = CType(primaryX.ScaleConfigurator, NDateTimeScaleConfigurator)

dateTimeScale.AutoDateTimeUnits = New NDateTimeUnit() {NDateTimeUnit.Day, NDateTimeUnit.Month}

This code will limit the scale to choose only from a day and month date time units.

Furthermore you can change the format string associated with a particular date time unit:

C#
Copy Code
NChart chart = nChartControl1.Charts[0];
NAxis primaryX = chart.Axis(StandardAxis.PrimaryX);
NDateTimeScaleConfigurator dateTimeScale = (NDateTimeScaleConfigurator)primaryX.ScaleConfigurator;
dateTimeScale.AutoDateTimeUnits = new NDateTimeUnit[] { NDateTimeUnit.Day, NDateTimeUnit.Month };
dateTimeScale.DateTimeUnitFormatterPairs.DayFormatter = new NDateTimeValueFormatter(DateTimeValueFormat.ShortDateShortTime24Hour);
dateTimeScale.DateTimeUnitFormatterPairs.MonthFormatter = new NDateTimeValueFormatter(DateTimeValueFormat.Date);
Visual Basic
Copy Code
Dim chart As NCartesianChart = NChartControl1.Charts(0)
Dim primaryX As NAxis = chart.Axis(StandardAxis.PrimaryX)
Dim dateTimeScale As NDateTimeScaleConfigurator = CType(primaryX.ScaleConfigurator, NDateTimeScaleConfigurator)
dateTimeScale.AutoDateTimeUnits = New NDateTimeUnit() {NDateTimeUnit.Day, NDateTimeUnit.Month}
dateTimeScale.DateTimeUnitFormatterPairs.DayFormatter = New NDateTimeValueFormatter(DateTimeValueFormat.ShortDateShortTime24Hour)
dateTimeScale.DateTimeUnitFormatterPairs.MonthFormatter = New NDateTimeValueFormatter(DateTimeValueFormat.Date)

Now when the scale decides to generate major ticks for days (at say each day, each fifth day etc.) it will use a formatting string with short date and short time information. Otherwise if it chooses to generate ticks on a per month basis it will display just date information.

Label Generation and Layout

You can modify various aspects of the label generation and layout. The following sections describe how to fine tune automatically generated labels.

Ticks per Label

By default the scale will create a label for each major tick on the scale. In some cases however you may want labels to be less dense than ticks - in such cases you can change NumberOfTicksPerLabel property allowing you to create scales where labels skip major ticks. The following code snippet will configure the axis to display one label for each two ticks:

C#
Copy Code
NChart chart = nChartControl1.Charts[0];
NAxis primaryY = chart.Axis(StandardAxis.PrimaryY);
NStandardScaleConfigurator scale = (NStandardScaleConfigurator)primaryY.ScaleConfigurator;
scale.NumberOfTicksPerLabel = 2;
Visual Basic
Copy Code
Dim chart As NCartesianChart = NChartControl1.Charts(0)
Dim primaryY As NAxis = chart.Axis(StandardAxis.PrimaryY)
Dim scale As NStandardScaleConfigurator = CType(primaryY.ScaleConfigurator, NStandardScaleConfigurator)
scale.NumberOfTicksPerLabel = 2
Label Generation Mode

Often when you have densely populated scales the labels overlap. By default the scale is configured to resolve label overlapping by staggering and auto scaling texts. However this can often be unpractical because the chart will bounce when you have overlapping and when not. To avoid this you may consider to force the axis to always generate staggered labels regardless of whether the labels overlap or not. This is done with the help of the LabelGenerationMode property:

C#
Copy Code
NChart chart = nChartControl1.Charts[0];
NAxis primaryY = chart.Axis(StandardAxis.PrimaryY);
NStandardScaleConfigurator scale = (NStandardScaleConfigurator)primaryY.ScaleConfigurator;
scale.LabelGenerationMode = LabelGenerationMode.Stagger2;
Visual Basic
Copy Code
Dim chart As NCartesianChart = NChartControl1.Charts(0)
Dim primaryY As NAxis = chart.Axis(StandardAxis.PrimaryY)
Dim scale As NStandardScaleConfigurator = CType(primaryY.ScaleConfigurator, NStandardScaleConfigurator)
scale.LabelGenerationMode = LabelGenerationMode.Stagger2

Note that when you use staggered label generation you should disable the staggering layout mode because this can lead to having a scale with four levels if the labels overlap:

C#
Copy Code
NChart chart = nChartControl1.Charts[0];
NAxis primaryY = chart.Axis(StandardAxis.PrimaryY);
NStandardScaleConfigurator scale = (NStandardScaleConfigurator)primaryY.ScaleConfigurator;
scale.LabelFitModes = new LabelFitMode[] { LabelFitMode.AutoScale };
Visual Basic
Copy Code
Dim chart As NCartesianChart = NChartControl1.Charts(0)
Dim primaryY As NAxis = chart.Axis(StandardAxis.PrimaryY)
Dim scale As NStandardScaleConfigurator = CType(primaryY.ScaleConfigurator, NStandardScaleConfigurator)
scale.LabelFitModes = New LabelFitMode() {LabelFitMode.AutoScale}
Label Layout Fit Modes

When you have labels that overlap you can instruct the scale to try to resolve the overlapping by using one or more label overlapping resolve strategies.

You assign the allowed layout fit strategies to the scale by changing the values of the LabelFitModes property of the NStandardScaleConfigurator. The order in which you specify the strategies is important as layout fit modes that appear first in the collection will be tested before the rest. If a layout strategy succeeds the rest of the layout fit modes in the collection are ignored. By default the labels are configured to use staggering and then auto scaling.

The following code snippet allows 90 degrees rotation to the PrimaryX axis:

C#
Copy Code
NChart chart = nChartControl1.Charts[0];
NAxis primaryY = chart.Axis(StandardAxis.PrimaryY);
NStandardScaleConfigurator scale = (NStandardScaleConfigurator)primaryY.ScaleConfigurator;
scale.LabelFitModes = new LabelFitMode[] { LabelFitMode.Rotate90, LabelFitMode.AutoScale };
Visual Basic
Copy Code
Dim chart As NCartesianChart = NChartControl1.Charts(0)
Dim primaryY As NAxis = chart.Axis(StandardAxis.PrimaryY)
Dim scale As NStandardScaleConfigurator = CType(primaryY.ScaleConfigurator, NStandardScaleConfigurator)
scale.LabelFitModes = New LabelFitMode() {LabelFitMode.Rotate90, LabelFitMode.AutoScale}

Note: It is a good idea to always leave the auto scale layout, because it will always resolve label overlapping.

Related Examples
Windows Forms: Axes \ General \ Axis Labels

See Also

NStandardScaleConfigurator | NNumericValueFormatter | NDateTimeValueFormatter | NDateTimeUnit

See Also

 

 


©2017. Nevron Software LLC.

Send Feedback