Xceed Chart for WinForms v4.4 Documentation
Axis Texts

Welcome to Xceed Chart for WinForms v4.4 > User Guide > Axes > Axis Texts

Axis Text Generation

The texts displayed by the axes are generated by the current active scale. The default texts represent the value of the major tick on which they are placed. For example, a Dimension scale will generate numbers representing the dimension index (0, 1, 2, 3, etc.), while a Numeric scale can generate values such as 1.3, 1.5, 1.7, etc. In some cases, it is useful to change the default axis text generation and display your own texts on major ticks. The chart on figure 1 demonstrates this. 

figure 1.

The code reproducing the axis texts of the PrimaryX axis is as follows:

VB.NET  
' there is one chart created by default
Dim chart As Chart =   chartControl1.Charts(0)
  
' disable automatic labels
chart.Axis(StandardAxis.PrimaryX).DimensionScale.AutoLabels = False
  
' add custom labels to be displayed on major tick values
chart.Axis(StandardAxis.PrimaryX).Labels.Clear()
chart.Axis(StandardAxis.PrimaryX).Labels.Add("Apples")
chart.Axis(StandardAxis.PrimaryX).Labels.Add("Oranges")
chart.Axis(StandardAxis.PrimaryX).Labels.Add("Bananas")
C#  
// there is one chart created by default
Chart chart = chartControl1.Charts[0];
 
// disable automatic labels
chart.Axis(StandardAxis.PrimaryX).DimensionScale.AutoLabels = false;
 
// add custom labels to be displayed on major tick values
chart.Axis(StandardAxis.PrimaryX).Labels.Clear();
chart.Axis(StandardAxis.PrimaryX).Labels.Add("Apples");
chart.Axis(StandardAxis.PrimaryX).Labels.Add("Oranges");
chart.Axis(StandardAxis.PrimaryX).Labels.Add("Bananas");

Axis Text Formatting

The formatting of automatically generated axis texts is controlled by the ValueFormatting object accessible from the ValueFormatting property of the axis. This property often needs to be modified to reflect the nature of the values displayed on the axis. For example, in a date-time chart you need to manually set the value format to Date:

VB.NET  
chart.Axis(StandardAxis.PrimaryX).ScaleMode = AxisScaleMode.DateTime
chart.Axis(StandardAxis.PrimaryX).ValueFormatting.Format = ValueFormat.Date
C#  
chart.Axis(StandardAxis.PrimaryX).ScaleMode = AxisScaleMode.DateTime;
chart.Axis(StandardAxis.PrimaryX).ValueFormatting.Format = ValueFormat.Date;

It is also often required to display the values of the numeric scale as currency:

VB.NET  
' display as currency
chart.Axis(StandardAxis.PrimaryY).ValueFormatting.Format = ValueFormat.Currency
C#  
// display as currency
chart.Axis(StandardAxis.PrimaryY).ValueFormatting.Format = ValueFormat.Currency;

or as a percentage:

VB.NET  
' display as percentage
chart.Axis(StandardAxis.PrimaryY).ValueFormatting.Format = ValueFormat.Percentage
C#  
// display as percentage
chart.Axis(StandardAxis.PrimaryY).ValueFormatting.Format = ValueFormat.Percentage;

 

Axis Value Formatting
DateTime XAxis Currency YAxis Percentage YAxis
 

Axis Text Layout

The user can control the layout of the displayed axis texts. This is particularly useful in the case of a custom labeled PrimaryX axis on which the labels are long strings and often overlap. You can resolve this with several approaches: 

1. Staggered texts: Staggered texts are displayed on several levels. The user can control the number of stagger levels as well as the distance between each level. The properties implementing staggered texts are: 

StaggerTexts: Enables or disables staggered text mode. 
StaggerLevels: Controls the number of stagger levels. 
StaggerOffset: Controls the offset of the staggered texts. 

The chart on figure 2 is a typical example of staggered labels. 

figure 2. 

The code replicating this behaviour follows:

VB.NET  
chart.Axis(StandardAxis.PrimaryX).StaggerTexts = True
chart.Axis(StandardAxis.PrimaryX).StaggerLevels = 3
chart.Axis(StandardAxis.PrimaryX).StaggerOffset = 5
C#  
chart.Axis(StandardAxis.PrimaryX).StaggerTexts = true;
chart.Axis(StandardAxis.PrimaryX).StaggerLevels = 3;
chart.Axis(StandardAxis.PrimaryX).StaggerOffset = 5;

2. Use a predefined text layout: This is a very useful feature for configuring the layout of axis text. The predefined text layout is a specific combination of text offset, alignment, orientation, and stagger. It is applied with the SetPredefinedTextLayout method of the Axis class. It also takes into account the PredefinedChartStyle setting. It is of type PredefinedTextLayout. For example, if you want to display the PrimaryX axis texts vertically, you can use the following code:

VB.NET  
chart.Axis(StandardAxis.PrimaryX).SetPredefinedTextLayout(PredefinedTextLay.Vertical)
C#  
chart.Axis(StandardAxis.PrimaryX).SetPredefinedTextLayout(PredefinedTextLayout.Vertical);

 

figure 3.

Axis Text Appearance

The user can control the appearance of axis texts with the ChartText object accessible from the Text property of the Axis class.

VB.NET  
' make PrimaryY axis
texts blue chart.Axis(StandardAxis.PrimaryY).Text.FillEffect.SetSolidColor(Color.Blue)
C#  
// make PrimaryY axis
texts blue chart.Axis(StandardAxis.PrimaryY).Text.FillEffect.SetSolidColor(Color.Blue);

Axis Title

The axis title is a string displayed parallel to the axis orientation. The string itself is controlled by the Title property. The appearance of the title string is controlled by the TitleText property.

VB.NET  
' set some title to the PrimaryY axis
chart.Axis(StandardAxis.PrimaryY).Title = "Sales in millions"
chart.Axis(StandardAxis.PrimaryY).TitleText.FillEffect.SetSolidColor(Color.Magenta)
C#  
// set some title to the PrimaryY axis
chart.Axis(StandardAxis.PrimaryY).Title = "Sales in millions";
chart.Axis(StandardAxis.PrimaryY).TitleText.FillEffect.SetSolidColor(Color.Magenta);

See Also

Axis

 

 

Copyright Xceed Software Inc

Send Feedback