Nevron Open Vision Documentation
Scales / Labels / Formatting
In This Topic
    Formatting
    In This Topic

    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));