Nevron .NET Vision
Chart for .NET / User's Guide / Axes / Scale / Scale Configurators / Scale Label Style
In This Topic
    Scale Label Style
    In This Topic

    All labels visualized on a scale have controllable style which allows you to modify various aspects of the label appearance and behavior. Since there are two types of labels - value labels and range labels, the first one denoting a value and the second a range on the scale respectively there are two label styles - NValueScaleLabelStyle and NRangeScaleLabelStyle. Both share a common base class called NScaleLabelStyle.

    For labels that are automatically generated (for example labels that denote the values of the major ticks on a numeric scale) this style is exposed by the LabelStyle property of the configurator, which is shared by all labels that are automatically generated. Custom labels have a per label style, which is again exposed through a property called LabelStyle, but contained in the NCustomValueLabel or NCustomRangeLabel classes.

    This topic will describes the different properties of the label style classes and how you can use them to achieve the desired looks of your charts and gauges.

     Label Angle

    You control the label angle through the Angle property of the label style. The following code will tell the primary X axis to rotate labels at 90 degrees.

    C#
    Copy Code

    NChart chart = nChartControl1.Charts[0];
    NAxis primaryX = chart.Axis(StandardAxis.PrimaryX);
    NStandardScaleConfigurator scale = (NStandardScaleConfigurator)primaryX.ScaleConfigurator;

    scale.LabelStyle.Angle = new NScaleLabelAngle(ScaleLabelAngleMode.View, 90);
    Visual Basic
    Copy Code

    Dim chart As NChart = NChartControl1.Charts(0)
    Dim xAxis As NAxis = chart.Axis(StandardAxis.PrimaryX)
    Dim scale As NStandardScaleConfigurator = CType(xAxis.ScaleConfigurator, NStandardScaleConfigurator)

    scale.LabelStyle.Angle = New NScaleLabelAngle(ScaleLabelAngleMode.View, 90)

    Notice that when you specify a scale label angle you also need to set its angle mode. The following table shows the possible angle modes:

    ScaleLabelAngleMode Description
    View The angle is specified in chart view space. This means that the angle will have the specified angle (in degrees) regardless of the axis 2D or 3D position.
    Scale The angle is specified in scale space. This means that the angle will be relative to the axis orientation at the value or range denoted by the label. For example when you set scale label angle of 90 degrees with ScaleLabelAngleMode.Scale to a horizontal scale the labels will be rotated. If you apply this setting to a vertical axis the labels will not be rotated.

    The following pictures shows several charts and gauges with different settings for this property:

    Chart with Y axis labels using ScaleLabelAngleMode.View, 0 degrees Chart with Y axis labels using ScaleLabelAngleMode.Scale, 0 degrees
    Gauge with axis labels using ScaleLabelAngleMode.View, 0 degrees Gauge with axis labels using ScaleLabelAngleMode.Scale, 0 degrees

    You may also tell the axis angle whether it will allow texts to flip (that is have right to left reading direction). The following code disables flipping:

    C#
    Copy Code

    NChart chart = nChartControl1.Charts[0];
    NAxis primaryX = chart.Axis(StandardAxis.PrimaryX);
    NStandardScaleConfigurator scale = (NStandardScaleConfigurator)primaryX.ScaleConfigurator;

    scale.LabelStyle.Angle.AllowTextFlip = false;
    Visual Basic
    Copy Code

    Dim chart As NChart = NChartControl1.Charts(0)
    Dim xAxis As NAxis = chart.Axis(StandardAxis.PrimaryX)
    Dim scale As NStandardScaleConfigurator = CType(xAxis.ScaleConfigurator, NStandardScaleConfigurator)

    scale.LabelStyle.Angle.AllowTextFlip = False
     Keeping Labels Inside Ruler

    When a label is placed on the scale its bounds may fall outside the ruler range. You can force both value and range labels to be completely inside the ruler range if possible by setting the KeepInsideRuler property to true. By default this property is enabled for range labels and disabled for value labels.

    C#
    Copy Code

    NChart chart = nChartControl1.Charts[0];
    NAxis primaryX = chart.Axis(StandardAxis.PrimaryX);
    NStandardScaleConfigurator scale = (NStandardScaleConfigurator)primaryX.ScaleConfigurator;

    scale.LabelStyle.KeepInsideRuler = true;
    Visual Basic
    Copy Code

    Dim chart As NChart = NChartControl1.Charts(0)
    Dim xAxis As NAxis = chart.Axis(StandardAxis.PrimaryX)
    Dim scale As NStandardScaleConfigurator = CType(xAxis.ScaleConfigurator, NStandardScaleConfigurator)

    scale.LabelStyle.KeepInsideRuler = True
     Label Visibility

    Label visibility is controlled by setting the label style VisibilityMode property. This property allows you to control the visibility of a label based on its position on the scale. The following table shows the possible options:

    ScaleLabelVisibilityMode Description
    Always The label is always visible and no check is performed for its relative position against the ruler. This is the default setting for value labels.
    CenterInRuler The label is visible when its center lies inside the ruler range.
    TextInRuler The label is visible when its text is completely inside ruler.
    TextIntersectsRuler The label is visible when its text bounds intersect the ruler range. This is the default setting for range labels.

    The following code will change the label visibility mode of automatic labels in order to display them only when they are completely inside the ruler bounds:

    C#
    Copy Code

    NChart chart = nChartControl1.Charts[0];
    NAxis yAxis = chart.Axis(StandardAxis.PrimaryY);
    NStandardScaleConfigurator scale = (NStandardScaleConfigurator)yAxis.ScaleConfigurator;

    scale.LabelStyle.VisibilityMode = ScaleLabelVisibilityMode.TextInRuler;
    Visual Basic
    Copy Code

    Dim chart As NChart = NChartControl1.Charts(0)
    Dim yAxis As NAxis = chart.Axis(StandardAxis.PrimaryY)
    Dim scale As NStandardScaleConfigurator = CType(yAxis.ScaleConfigurator, NStandardScaleConfigurator)

    scale.LabelStyle.VisibilityMode = ScaleLabelVisibilityMode.TextInRuler

    The following pictures show how the VisibilityMode and KeepInsideRuler properties work together:

    Scale with labels using ScaleLabelVisibilityMode.Always Scale with labels using ScaleLabelVisibilityMode.TextInRuler Scale with labels where KeepInsideRuler is set to true

     Range Label Style
    The NRangeLabelStyle associated with range labels builds on top of the functionality provided by the NScaleLabelStyle base class by adding features specific to range labels. Therefore the following sections apply to range labels only.
     Wrapping Text

    Since range labels denote a range on the scale it is possible to determine the maximum space they should occupy. By default all range labels will wrap the text they display to the range they denote. To disable text wrapping you must set the WrapText property to false. The following code will create a range label without text wrapping on the X axis:

    C#
    Copy Code

    NChart chart = nChartControl1.Charts[0];

    NCustomRangeLabel customLabel = new NCustomRangeLabel();
    customLabel.Range =     new NRange1DD(20, 40);
    customLabel.Text =     "Some Long Text";
    customLabel.Style.WrapText =     false;

    chart.Axis(StandardAxis.PrimaryX).ScaleConfigurator.CustomLabels.Add(customLabel);
    Visual Basic
    Copy Code

    Dim chart As NChart = NChartControl1.Charts(0)

    Dim customLabel As New NCustomRangeLabel()
    customLabel.Range =     New NRange1DD(20, 40)
    customLabel.Text =     "Some Long Text"
    customLabel.Style.WrapText = False

    chart.Axis(StandardAxis.PrimaryX).ScaleConfigurator.CustomLabels.Add(customLabel)

    The following pictures show the effect of text wrapping:

    Chart with custom range label that does not use wrapping Chart with custom range label that uses wrapping

     Range Label Tick Mode

    Each range label will also generate a range tick on the scale that pinpoints the range denoted by the range. You can control the tick mode by changing the TickMode property of the NRangeScaleLabelStyle class. The following table shows the available options:

    RangeLabelTickMode Description
    None The range label does not render ticks
    Separators The range label tick is visualized as two separators at the left and right of the range annotated by the label
    Top The range label tick is attached to the top of the label (this is the default)
    Center The range label tick is attached to the center of the label
    Hierarchical and range timeline configurators use RangeLabelTickMode.Separators by default.

    The following code shows hot to change the range label tick mode of a custom range label:

    C#
    Copy Code

    NChart chart = nChartControl1.Charts[0];

    NCustomRangeLabel customLabel = new NCustomRangeLabel();
    customLabel.Range =     new NRange1DD(20, 40);
    customLabel.Text =     "Some Long Text";
    customLabel.Style.WrapText =     true;
    customLabel.Style.TickMode =     RangeLabelTickMode.Separators;

    chart.Axis(StandardAxis.PrimaryX).ScaleConfigurator.CustomLabels.Add(customLabel);
    Visual Basic
    Copy Code

    Dim chart As NChart = NChartControl1.Charts(0)

    Dim customLabel As New NCustomRangeLabel()
    customLabel.Range =     New NRange1DD(20, 40)
    customLabel.Text =     "Some Long Text"
    customLabel.Style.WrapText = False
    customLabel.Style.TickMode = RangeLabelTickMode.Separators

    chart.Axis(StandardAxis.PrimaryX).ScaleConfigurator.CustomLabels.Add(customLabel)
     Padding and Offset

    The TickPadding, TickOffset, TextPadding and Offset properties work together to determine the offset of the range tick lines from the text as well as the vertical position of the range tick lines and text on the scale. They have different meaning depending on the tick mode. The following pictures show how these properties work together depending on the TickMode of the label:

    RangeLabelTickMode.None - in this mode only TextPadding and Offset properties have any effect (as the label will not show a range tick). The picture below shows how text padding has limited the available space for the label. If the label uses wrapping if will fit in the range denoted by the blue lines:
    RangeLabelTickMode.Top - in this mode TickPadding, TickOffset, TextOffset and Offset properties work together to determine the label appearance as shown on the picture below:
    RangeLabelTickMode.Separators - this mode is similar to RangeLabelTickMode.None as only the TextPadding and Offset properties are regarded. The blue lines on the picture below show the available space for the label text. If the label does not use wrapping and is longer than the range then the separators will be hidden.
    RangeLabelTickMode.Center – in this mode TickOffset, Offset and TextPadding have the same meaning as when the label ticks operate in RangeLabelTickMode.Top. The TickPadding property in this case is used to control the distance of the center lines from the label text as shown on the picture below:

    The following code creates the label on the last picture (showing RangeLabelTickMode.Center):

    C#
    Copy Code

    NChart chart = nChartControl1.Charts[0];

    NCustomRangeLabel customLabel = new NCustomRangeLabel();
    customLabel.Range =     new NRange1DD(20, 60);
    customLabel.Text =     "Some Text";
    customLabel.Style.WrapText =     true;

    customLabel.Style.TickMode = RangeLabelTickMode.Center;
    customLabel.Style.Offset =     new NLength(10);
    customLabel.Style.TextPadding =     new NLength(10);
    customLabel.Style.TickOffset =     new NLength(0);
    customLabel.Style.TickPadding =     new NLength(5);

    chart.Axis(StandardAxis.PrimaryX).ScaleConfigurator.CustomLabels.Add(customLabel);
    Visual Basic
    Copy Code

    Dim chart As NChart = NChartControl1.Charts(0)

    Dim customLabel As New NCustomRangeLabel()
    customLabel.Range =     New NRange1DD(20, 40)
    customLabel.Text =     "Some Long Text"
    customLabel.Style.WrapText = False

    customLabel.Style.Offset = New NLength(10)
    customLabel.Style.TextPadding =     New NLength(10)
    customLabel.Style.TickOffset =     New NLength(0)
    customLabel.Style.TickPadding =     New NLength(5)

    chart.Axis(StandardAxis.PrimaryX).ScaleConfigurator.CustomLabels.Add(customLabel)

     Related Examples

    Windows Forms : Axes \ General \ Custom Range Labels

    Windows Forms : Gauge Gallery \ Gauges \ Axes \ Custom Range Labels

    Web Forms: Axes \ General \ Custom Range Labels

    Web Forms: Gauge Gallery \ Gauges \ Scales \ Custom Range Labels

     

     

    See Also
    Scale Labels
    Custom Labels