DateTimeAxisX Class

The X-axis the chart uses to display series that represent data sources with date-time arguments.

Namespace: DevExpress.XamarinForms.Charts

Assembly: DevExpress.XamarinForms.Charts.dll

Declaration

public class DateTimeAxisX :
    AxisX

Remarks

ChartView chooses the X-axis type depending on data in the first series. If arguments are date-time values, the chart uses a DateTimeAxisX.

The automatically created axis is available via the ChartView.AxisX property. To create and customize axes for individual series, use the Series.AxisX property.

<dxc:ChartView>
    <!--Specify an X-axis at the chart level-->
    <dxc:ChartView.AxisX>
        <dxc:DateTimeAxisX />
    </dxc:ChartView.AxisX>

    <dxc:ChartView.Series>
        <dxc:LineSeries>
            <!--Specify an X-axis at the series level-->
            <dxc:LineSeries.AxisX>
                <dxc:DateTimeAxisX />
            </dxc:LineSeries.AxisX>
        </dxc:LineSeries>
    </dxc:ChartView.Series>
</dxc:ChartView>

The DateTimeAxisX class properties allow you to configure the following axis options: range, scale parameters, labels, title, constant lines, strip, gridlines, tickmarks and interlacing colors. You can also change the axis position.

X-Axis Elements

Value Range

The ChartView automatically calculates the value range based on data of all series measured by the axis. You can also specify a custom range for the axis. To do this, set the Range property to a DateTimeRange object with the following properties specified:

  • Min and Max - to specify the entire range of the axis scale. A chart does not visualize data that is out of this range. A user can scroll the chart through this range when scrolling is enabled for the X-axis (AxisXNavigationMode).

  • VisualMin and VisualMax - to configure the axis scale range currently visible on the screen.

  • SideMargin - to change the value of indents on both sides of the axis.

X-Axis Elements

<dxc:DateTimeAxisX>
    <dxc:DateTimeAxisX.Range>
        <dxc:DateTimeRange Min="1/1/1950" VisualMin="1/1/1970"
                           Max="1/1/2050" VisualMax="1/1/2030" 
                           SideMargin="1"/>
    </dxc:DateTimeAxisX.Range>
</dxc:DateTimeAxisX>

You can also set the EmptyRangesVisible property to False to hide the ranges of the DateTimeAxisX that contain no data.

Axis Scale Parameters

Use the following properties to configures the axis scale:

DateTime Axis X Scale Settings

<dxc:DateTimeAxisX MeasureUnit="Month" GridOffset="6"
                   GridAlignment="Year" GridSpacing="10"/>

Axis Labels

Axis labels display values at major tickmarks. They are automatically generated based on series data.

Axis Label Sample

To configure axis labels, set the axis's Label property to an AxisLabel object with the specified settings. For example, you can use the AxisLabel.TextFormat property to change the text pattern applied to axis labels.

<dxc:DateTimeAxisX>
    <dxc:DateTimeAxisX.Label>
        <dxc:AxisLabel TextFormat="yyyy yr"/>
    </dxc:DateTimeAxisX.Label>
</dxc:DateTimeAxisX>

Label Text Formatter

To generate text strings for axis labels based on a custom condition:

  1. Create a class that inherits the IAxisLabelTextFormatter interface and implement the Format method.
  2. Assign an instance of the newly created class to the LabelTextFormatter property (it has a higher priority than AxisLabel.TextFormat).

This example shows how to format labels of a date-time axis.

<dxc:DateTimeAxisX GridAlignment="Day" GridSpacing="7">
    <dxc:DateTimeAxisX.LabelTextFormatter>
        <local:AxisLabelTextFormatter/>
    </dxc:DateTimeAxisX.LabelTextFormatter>
</dxc:DateTimeAxisX>
using DevExpress.XamarinForms.Charts;
... 

public class AxisLabelFormatter : IAxisLabelTextFormatter {
    public string Format(object axisValue) {
        DateTime value = (DateTime)axisValue;
        return ((value.Day >= 1) && (value.Day <= 7)) ? $"{value.ToString("MMM, d")}" : $"{value.Day}";
    }
}

Label Format Auto Replace

The ChartView can detect if adjacent date-time argument values belong to different measurement units (for example, days of different months) and automatically display a transition label on a date-time axis (for example, the first-day label of the next month) with a different format.

To enable this functionality:

  1. Set the DateTimeAxisX.LabelFormatAutoReplaceOptions property to an AxisLabelFormatAutoReplaceOptions object.
  2. Add DateTimeLabelFormat objects that specify label formats (Format) for arguments of different measure units (MeasureUnit) to the AxisLabelFormatAutoReplaceOptions.LabelFormats collection.

    NOTE

    LabelFormats is a content property. You can skip property tags in the markup.

    If you don't populate the LabelFormats collection explicitly, the following default formats are used depending the axis's MeasureUnit and GridAlignment settings:

    Measurement Unit*

    Label Format

    Millisecond

    Millisecond - "SSS"
    Second - "HH:mm:ss SSS"
    Day - "dd MMMM HH:mm:ss SSS"
    Year - "dd/MM/yyyy HH:mm:ss SSS"

    Second
    Minute
    Hour

    Second - "HH:mm:ss"
    Day - "dd MMMM HH:mm:ss"
    Year - "dd/MM/yyyy HH:mm:ss"

    Day
    Week

    Day - "dd MMMM"
    Year - "dd MMMM yyyy"

    Month
    Quarter

    Month - "MMMM"
    Year - "MMMM yyyy"

    Year

    Year - "yyyy"

    Measurement Unit* - the larger of measurement units assigned to the MeasureUnit and GridAlignment properties.

The following example configures a date-time axis so that it automatically shows when each next month starts:

Axis Label Format Auto Replace

<dxc:DateTimeAxisX x:Name="xAxis" GridAlignment="Day" GridSpacing="5">
    <dxc:DateTimeAxisX.LabelFormatAutoReplaceOptions>
        <dxc:AxisLabelFormatAutoReplaceOptions>
            <dxc:DateTimeLabelFormat MeasureUnit="Day" Format="d"/>
            <dxc:DateTimeLabelFormat MeasureUnit="Month" Format="MMM, d"/>
        </dxc:AxisLabelFormatAutoReplaceOptions>
    </dxc:DateTimeAxisX.LabelFormatAutoReplaceOptions>
</dxc:DateTimeAxisX>

Avoid Axis Label Overlaps

Axis labels can be hidden to avoid overlapping labels. To enable this option, use ResolveOverlappingOptions property.

<dxc:DateTimeAxisX x:Name="myAxis" GridAlignment="Day" GridSpacing="6">
    <dxc:DateTimeAxisX.Label>
        <dxc:AxisLabel TextFormat="M/d/yy">
            <dxc:AxisLabel.ResolveOverlappingOptions>
                <dxc:AxisLabelResolveOverlappingOptions AllowHide="True"/>
            </dxc:AxisLabel.ResolveOverlappingOptions>
        </dxc:AxisLabel>
    </dxc:DateTimeAxisX.Label>
</dxc:DateTimeAxisX>

Axis Title

Use the Title property to access the X-axis's title settings.

This example demonstrates how to create, align, and customize the appearance of the X-axis's title.

Axis Title Sample

<dxc:DateTimeAxisX>
    <dxc:DateTimeAxisX.Title>
        <dxc:AxisTitle Text="Year" Alignment="Center"/>
            <dxc:AxisTitle.Style>
                <dxc:TitleStyle>
                    <dxc:TitleStyle.TextStyle>
                        <dxc:TextStyle Color="DarkRed" Size="24"/>
                    </dxc:TitleStyle.TextStyle>
                </dxc:TitleStyle>
            </dxc:AxisTitle.Style>
    </dxc:DateTimeAxisX.Title>
</dxc:DateTimeAxisX>

You can also use the AxisTitle's Visible property to change the title visibility.

Constant Lines

A Constant Line visually represents an axis value as a line perpendicular to the X-Axis.

Constant Line Sample

This example shows how to add a constant line to the X-axis, customize its appearance and display it in the chart legend. To do this, add a DateTimeConstantLine object with the specified properties to the DateTimeAxisX.ConstantLines collection.

<dxc:DateTimeAxisX>
    <dxc:DateTimeAxisX.ConstantLines>
        <dxc:DateTimeConstantLine AxisValue="2019" ShowBehind="False" 
                                  VisibleInLegend="True" LegendText="Nowadays">
            <!-- Customize the constant line title. -->
            <dxc:DateTimeConstantLine.Title>
                <dxc:ConstantLineTitle Text="Nowadays" ShowBelowLine="False" Alignment="Near">
                    <dxc:ConstantLineTitle.Style>
                        <dxc:TitleStyle>
                            <dxc:TitleStyle.TextStyle>
                                <dxc:TextStyle Color="DarkBlue" Size="24"/>
                            </dxc:TitleStyle.TextStyle>
                        </dxc:TitleStyle>
                    </dxc:ConstantLineTitle.Style>
                </dxc:ConstantLineTitle>
            </dxc:DateTimeConstantLine.Title>
            <!-- Customize the constant line appearance. -->
            <dxc:DateTimeConstantLine.Style>
                <dxc:ConstantLineStyle Thickness="5"/>
            </dxc:DateTimeConstantLine.Style>
        </dxc:DateTimeConstantLine>
    </dxc:DateTimeAxisX.ConstantLines>
</dxc:DateTimeAxisX>

Strip

A Strip highlights a specific range of axis values as a rectangular area with an axis label.

Constant Line Sample

<dxc:DateTimeAxisX>
    <dxc:DateTimeAxisX.Strips>
        <dxc:DateTimeStrip MinLimit="2019" MaxLimitEnabled="False">
            <dxc:DateTimeStrip.AxisLabel>
                <dxc:StripAxisLabel Text="Future"/>
            </dxc:DateTimeStrip.AxisLabel>
        </dxc:DateTimeStrip>
    </dxc:DateTimeAxisX.Strips>
</dxc:DateTimeAxisX>
NOTE

The axis hides its labels when any strip has a label.

Axis Appearance

The axis provides the Style property that stores the appearance of the following elements:

Element

Properties

Axis Line

LineColor, LineThickness, LineVisible

Major Tickmarks

LineColor, MajorTickmarksThickness, MajorTickmarksLength, MajorTickmarksVisible

Minor Tickmarks

LineColor, MinorTickmarksThickness, MinorTickmarksLength, MinorTickmarksVisible

Major Gridlines

MajorGridlinesThickness, MajorGridlinesColor, MajorGridlinesVisible

Minor Gridlines

MinorGridlinesThickness, MinorGridlinesColor, MinorGridLinesVisible

Interlacing

InterlacedVisible, InterlacedColor

Axis Appearance Settings

NOTE

Labels, Titles, Constant Lines and Strips have Style properties that manage the appearance of these elements.

Axis Position

Use the DisplayPosition property to specify where an X-axis should be positioned within the chart diagram.

This example anchors an X-axis to the top portion of the chart's plot area:

Axis Position Sample

<dxc:DateTimeAxisX>
    <dxc:DateTimeAxisX.DisplayPosition>
        <dxc:AxisDisplayPositionFar/>
    </dxc:DateTimeAxisX.DisplayPosition>
</dxc:DateTimeAxisX>

Inheritance

Object
Xamarin.Forms.BindableObject
See Also