Axis Labels

• Aug 03, 2020
• 5 minutes to read

The Chart control provides default and custom axis labels. Default labels are generated automatically based on series’ data.

This document consists of the following sections:

• How to Configure Custom Labels
• How to Apply an Axis Label Text Pattern
• How to Resolve Axis Label Overlapping

How to Configure Custom Labels

You can create custom axis labels and modify their position and content. The Chart Control can display custom and default labels simultaneously. The following image shows custom axis labels for a y-axis:

Use the markup below to configure custom axis labels:

XAML

<dxc:XYDiagram2D.AxisY>
      <dxc:AxisY2D LabelVisibilityMode="Default"
                   GridLinesMinorVisible="False" 
                   Interlaced="False" 
                   Brush="Transparent">
            <dxc:AxisY2D.CustomLabels>
                  <dxc:CustomAxisLabel Value="120" Content="2h"/>
                  <dxc:CustomAxisLabel Value="360" Content="6h"/>
                  <dxc:CustomAxisLabel Value="600" Content="10h"/>
                  <dxc:CustomAxisLabel Value="840" Content="14h"/>
            </dxc:AxisY2D.CustomLabels>
      </dxc:AxisY2D>
</dxc:XYDiagram2D.AxisY>

The following API members allow you to configure axis custom labels:

Class or Property	Description
Axis2D.CustomLabels	The custom axis labels’ collection. If this collection is empty, a Chart control displays default axis labels.
CustomAxisLabel	An individual custom axis label.
CustomAxisLabel.Value	An axis value that specifies a custom label’s position.
CustomAxisLabel.Content	A custom label’s content.
Axis2D.LabelVisibilityMode	Specifies whether to show custom with default axis labels or only display custom labels.

The MVVM Design Pattern’s Use

To generate custom axis labels from a ViewModel, bind the Axis2D.CustomLabelItemsSource property to a collection of objects that contain custom axis labels’ parameters. Use the Axis2D.CustomLabelItemTemplate or Axis2D.CustomLabelItemTemplateSelector property to specify how to convert a model object to a custom label.

The following example shows how to generate custom labels for a y-axis:

XAML

<Window.DataContext> 
    <local:MainViewModel/> 
</Window.DataContext> 

<dxc:XYDiagram2D.AxisY> 
    <dxc:AxisY2D x:Name="axisY" 
                 GridLinesMinorVisible="False" 
                 Interlaced="False" 
                 Brush="Transparent" 
                 CustomLabelItemsSource="{Binding CustomLabels}"> 
        <dxc:AxisY2D.CustomLabelItemTemplate> 
            <DataTemplate> 
                <dxc:CustomAxisLabel Value="{Binding Item1}" 
                                     Content="{Binding Item2}"/> 
            </DataTemplate> 
        </dxc:AxisY2D.CustomLabelItemTemplate> 
    </dxc:AxisY2D> 
</dxc:XYDiagram2D.AxisY> 

C#

public class MainViewModel {
    public IEnumerable<Tuple<double, string>> CustomLabels { get; private set; }
    public MainViewModel() {
        this.CustomLabels = new List<Tuple<double, string>> {
            new Tuple<double, string>(120, "2h"),
            new Tuple<double, string>(360, "6h"),
            new Tuple<double, string>(600, "10h"),
            new Tuple<double, string>(840, "14h")
        };
    }
}

VB.NET

Public Class MainViewModel    
    Public Property CustomLabels As IEnumerable(Of Tuple)
        Get 
        End Get 
        Set 
        End Set 
    End Property 
    Public Sub New()
        MyBase.New 
        Me.CustomLabels = New List(Of Tuple)() {
                         New Tuple(Of Double, String)(120, "2h"), 
                         New Tuple(Of Double, String)(360, "6h"), 
                         New Tuple(Of Double, String)(600, "10h"), 
                         New Tuple(Of Double, String)(840, "14h")}
    End Sub 
End Class 

You can use the API members in the following table to generate custom labels from a View Model:

Member	Description
Axis2D.CustomLabelItemsSource	Gets or sets the collection that is used to generate custom labels.
Axis2D.CustomLabelItemTemplate	Specifies the DataTemplate object that defines how to convert a model object to a custom label.
Axis2D.CustomLabelItemTemplateSelector	Gets or sets the DataTemplateSelector object that defines the custom logic to select a data template that converts a model to a custom label.

How to Apply an Axis Label Text Pattern

Use the predefined placeholders, format specifiers and plain text to set a pattern that defines a label’s text. In the image below, the {V} min pattern is applied to the y-axis labels.

The following markup shows how to configure the label’s text pattern:

XAML

<dxc:XYDiagram2D.AxisY>
      <dxc:AxisY2D GridLinesMinorVisible="False" 
                   Interlaced="False" 
                   Brush="Transparent">
            <dxc:AxisY2D.Label>
                  <dxc:AxisLabel TextPattern="{}{V} min"/>
            </dxc:AxisY2D.Label>
      </dxc:AxisY2D>
</dxc:XYDiagram2D.AxisY>

The code above uses the following classes and properties:

Class or Property	Description
AxisLabel.TextPattern	Specifies a text pattern.
AxisBase.Label	Specifies the label settings.
AxisLabel	The axis label settings’ storage.

The following table lists all the available placeholders:

Pattern	Description
{A}	Displays series point arguments (only for arguments axes).
{V}	Displays series point values (only for values axes).
{VP}	Displays series point values as a percentage (only for values axes).

How to Resolve Axis Label Overlapping

The Chart Control provides the Resolve Overlapping algorithm that rotates, staggers and hides axis labels when they are too long and do not have enough space to display all the information. You can use the Resolve Overlapping options to configure this algorithm. Axis labels overlap when the Resolve Overlapping options are disabled.

The following animation shows how the Resolve Overlapping algorithm works:

The following XAML demonstrates how to use AxisLabelResolveOverlappingOptions to configure the Resolve Overlapping algorithm’s options:

Tip

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=T316624.

XAML

<dxc:XYDiagram2D.AxisX>
    <dxc:AxisX2D>
        <dxc:AxisX2D.DateTimeScaleOptions>
            <dxc:ManualDateTimeScaleOptions MeasureUnit="Hour"
                        GridAlignment="Hour"
                        GridSpacing="6"
                        AutoGrid="False" />
        </dxc:AxisX2D.DateTimeScaleOptions>
        <dxc:AxisX2D.Label>
            <dxc:AxisLabel TextPattern="{}{A:dd/MM HH:mm}">
                <dxc:Axis2D.ResolveOverlappingOptions>
                    <dxc:AxisLabelResolveOverlappingOptions AllowHide="True"
                                AllowRotate="True"
                                AllowStagger="True"
                                MinIndent="5" />
                </dxc:Axis2D.ResolveOverlappingOptions>
            </dxc:AxisLabel>
        </dxc:AxisX2D.Label>
    </dxc:AxisX2D>
</dxc:XYDiagram2D.AxisX>

You can use the following properties to configure the Resolve Overlapping algorithm’s options:

Member	Description
AxisLabelResolveOverlappingOptions	Settings that allow you to modify axis labels’ position to prevent overlapping labels.
Axis2D.ResolveOverlappingOptions	Gets or sets the settings that allow you to avoid overlapping axis labels.
AxisLabelResolveOverlappingOptions.AllowHide	Gets or sets the value that indicates whether to hide axis labels to prevent overlapping labels.
AxisLabelResolveOverlappingOptions.AllowRotate	Specifies the value that indicates whether to rotate axis labels.
AxisLabelResolveOverlappingOptions.AllowStagger	Gets or sets the value that indicates whether to stagger axis labels to avoid overlapping labels.
AxisLabelResolveOverlappingOptions.MinIndent	Gets or sets the minimum indent between adjacent axis labels when an overlap resolution algorithm is applied to them.

Note

The AllowRotate and AllowStagger properties only affect labels of a horizontal 2D XY Diagram axis (an arguments x-axis or values y-axis when XYDiagram2D.Rotated is enabled).