Nevron Open Vision Documentation
Formatting

Scale labels appear next to major ticks by default and denote values on the scale depending on a number of settings. This topic will discuss the provided options for label customization by the NStandardScale derived classes only, as other scales expose different label properties.

Automatic Label Texts

The scale Labels object has a property called TextProvider that controls how the label value will be formatted and presented as text to the user. There are two types of label text providers:

NFormattedScaleLabelTextProvider

The formatted scale label text provider takes the value associated with the label and formats it as a user readable string. It has an associated value formatter object (check out the Numeric Value Formatting and DateTime Value Formatting sections below). The following code snippet shows how to alter the default formatting on a linear scale:

C#
Copy Code

scale.Labels.TextProvider = new NFormattedScaleLabelTextProvider(new NNumericValueFormatter("0.000"));

Different scales by default have an associated formatted scale label text provider with different value formatter as shown on the following table:

Scale Label Value Formatter
NDateTimeScale NDateTimeValueFormatter with a format string showing the data according to the system date presentation settings.
NOrdinalScale NNumericValueFormatter formatting numbers with variable decimal places.
NLogarithmicScale NNumericValueFormatter formatting numbers with variable decimal places.
NLinearScale NNumericValueFormatter formatting numbers with variable decimal places.
You can derive from the base NValueFormatter class and create your own label formatter.

NOrdinalScaleLabelTextProvider

The ordinal scale label text provider takes the value of label and maps it to a set to a set of predefined constant strings. It is commonly used in ordinal (categorical) scales where each value on the scale represents a different category. The following code snippet for example create a simple categorical bar chart with custom category labels:

C#
Copy Code

NBarSeries bar = new NBarSeries();
bar.DataPoints.Add(
new NBarDataPoint(10));
bar.DataPoints.Add(
new NBarDataPoint(18));
bar.DataPoints.Add(
new NBarDataPoint(25));
chart.Series.Add(bar);

NOrdinalScale scaleX = (NOrdinalScale)chart.Axes[ENCartesianAxis.PrimaryX].Scale;
scaleX.Labels.TextProvider =
new NOrdinalScaleLabelTextProvider(new string[] { "Cars", "Busses", "Airplanes" });

NDateTimeUnitSensitiveLabelTextProvider

The date time unit sensitive label text provider takes the unit and value of the label and applies formatting to the value which is dependent on the date time unit that generated itl. This allows you to specify unit sensitive 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).

Creating a Date Time Unit Sensitive Label Text Provider

The following code snippet shows how to create a date time unit sensitive text provider:

C#
Copy Code

scale.Labels.TextProvider = new NDateTimeUnitSensitiveLabelTextProvider();

Configuring the allowed date time units for decoration

Date time units are implemented as singleton objects, which are accessible from the NDateaTimeUnit base abstract class. The following table lists the date time units supported by the date time, value timeline and range timeline scales:

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

 dateTimeScale.AutoDateTimeUnits = new NDomArray<NDateTimeUnit>(new NDateTimeUnit[] { NDateTimeUnit.Day, NDateTimeUnit.Month });

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

You can also change the format string associated with a particular date time unit:

C#
Copy Code

NDateTimeUnitSensitiveLabelTextProvider textProvider = new NDateTimeUnitSensitiveLabelTextProvider();

textProvider.DayFormatter = new NDateTimeValueFormatter(ENDateTimeValueFormat.ShortDateShortTime24Hour);

textProvider.MonthFormatter = new NDateTimeValueFormatter(ENDateTimeValueFormat.Date);

dateTimeScale.Labels.TextProvider = textProvider;

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.

Numeric Value Formatting

The numeric value formatter supports all standard .NET format strings and also features support for a number of predefined format strings. The following table shows the predefined numeric format strings:

ENNumericValueFormat Description
General The value is formatted with the default locale settings
Currency The value is formatted with the default locale currency format
Scientific The value is formatted with the default locale scientific format
Percentage The value is formatted as a percentage
Arabic The value is formatted as arabic number
ArabicDash The value is formatted as arabic number with dash
AlphaLower The value is formatted with lower alpha numbers
AlphaUpper The value is formatted with upper alpha numbers
RomanLower The value is formatted with lower roman numbers
RomanUpper The value is formatted with upper roman numbers
Ordinal The value is formatted as ordinal
CardinalText The value is formatted as cardinal text
OrdText value is formatted as ordinal text
DollarText The value is formatted as dollar text

The following code snippets show how to apply different predefined numeric formats:

Display Value as Currency

C#
Copy Code

scale.Labels.TextProvider = new NFormattedScaleLabelTextProvider(new NNumericValueFormatter(ENNumericValueFormat.Currency));

Display Value as Percentage

C#
Copy Code

scale.Labels.TextProvider = new NFormattedScaleLabelTextProvider(new NNumericValueFormatter(ENNumericValueFormat.Percentage));

DateTime Value Formatting

The date time value formatter supports all standard .NET date time format strings and extends it further to add support for week and quarter formatting. The predefined format strings in the control are contained in the ENDateTimeValueFormat enumeration. The following table list the available options:

ENNumericValueFormat Description
Date The value is formatted with the default locale short date format
LongDate The value is formatted with the default locale long date format
Time The value is formatted with the default locale time format
DateTime The value is formatted with the default locale date time format
WeekDayFullName The value is formatted with the day of the week full name e.g. Monday, Tuesday etc.
WeekDayShortName The value is formatted with the day of the week short name e.g. Mon, Tue etc.
LongDateLongTime24Hour The value is formatted with long date and long time in 24 hour format
LongDateLongTimeAMPM The value is formatted with long date and time in AM/PM format
LongDateShortTime24Hour The value if formatted with long date and short time (HH:mm)
LongDateShortTimeAMPM The value if formatted with long date and short time in AM/PN format
LongTime24Hour Long time 24 hour format
MonthFullName The value is formatted by its month full name e.g. January, February etc.
MonthNameAndDay The value is formatted by its month full name and day
MonthNameYear2Digit The value is formatted by its month full name and year with 2 digits
MonthShortName The value is formatted by its month short name and day e.g Jan 15
ShortDateLongTime24Hour The value is formatted by its short date and long time in 24 hour format
ShortDateLongTimeAMPM The value is formatted by its short date and long time in AM/PM hour format
ShortDateShortTime24Hour The value is formatted by its short date and short time in 24 hour format
ShortDateShortTimeAMPM The date is formatted by tis short date and short time in AM/PM hour format
ShortTime24Hour The value is formatted by its short time 24 hour format.
ShortTimeAMPM The value is formatted by its short time in AM/PM hour format
Year4Digit The value is formatted by its year expressed in four digits
Year2Digit The value is formatted by its year expressed by two digits
QuarterYear2Digit The value is formatted by its quarter and year expressed by two digits
QuarterYear4Digit The value is formatted by its quarter and year expressed by four digits
YearAndMonthName The value is formatted by its year and month name
WeekYear2Digit The value is formatted by its week number in ISO and year by two digits
WeekYear4Digit The value is formatted by its week number in ISO and year by four digits
MinuteSecond The value is formatted by its minute and second (mm:ss)
SecondMillisecond The value is formatted by its second an millisecond

 The following code shows how to apply one of the predefined date time value formats:

C#
Copy Code

dateTimeScale.Labels.TextProvider = new NFormattedScaleLabelTextProvider(new NDateTimeValueFormatter(ENDateTimeValueFormat.ShortTime24Hour));

Send Feedback