Axis Ranges

Oct 09, 2023
9 minutes to read

Whole and Visual axis ranges define the data that an axis displays. The whole range specifies the data source values the chart displays at the minimum zoom level. If whole range limits are not set, the whole range is calculated based on the data of all series associated with the axis. The visual range depends on the zoom level and is initially equal to the whole range. You can modify ranges of both x- and y-axes.

An x-axis’s visual range is equal to a whole range (default)	An x-axis’s visual range is less than a whole range

How End Users Can Change a Visual Range
Configure Visual and Whole Ranges
Specify Diagram Side Margins
Hide Zero Level on a Chart Value Axis
Configure Y-Axis’s Range Based on X-Axis’s Visual Range

How End Users Can Change a Visual Range

Users can pan and zoom a chart to change the visual range. To allow users to scroll and zoom a chart, enable the following properties:

XYDiagram2D.EnableAxisXZooming (use XYDiagramPaneBase.EnableAxisXZooming for a particular pane)
XYDiagram2D.EnableAxisXScrolling (use XYDiagramPaneBase.EnableAxisXScrolling for a particular pane)
XYDiagram2D.EnableAxisYZooming (use XYDiagramPaneBase.EnableAxisYZooming for a particular pane)
XYDiagram2D.EnableAxisYScrolling (use XYDiagramPaneBase.EnableAxisYScrolling for a particular pane)
C#
VB.NET

csharp

XYDiagram diagram = chartControl1.Diagram as XYDiagram;

diagram.EnableAxisXScrolling = true;
diagram.EnableAxisXZooming = true;

diagram.EnableAxisYScrolling = true;
diagram.EnableAxisYZooming = true;

Dim diagram As XYDiagram = TryCast(chartControl1.Diagram, XYDiagram)

diagram.EnableAxisXScrolling = True
diagram.EnableAxisXZooming = True

diagram.EnableAxisYScrolling = True
diagram.EnableAxisYZooming = True

Refer to Zoom and Scroll in 2D XY-Charts and Zooming and Scrolling (3D Charts) for more information.

Configure Visual and Whole Ranges

The Range class provides base functionality for WholeRange and VisualRange. To access whole and visual range parameters, use the AxisBase.WholeRange and AxisBase.VisualRange properties.

Range limits are automatically calculated when the Range.Auto property is enabled. To specify range limits, use the Range.MinValue and Range.MaxValue properties. Alternatively, you can call the Range.SetMinMaxValues method to pass minimum and maximum range values. The following examples show how to configure a whole range for different axis types:

csharp

XYDiagram diagram = chartControl1.Diagram as XYDiagram;

// Set limits for an x-axis's whole range
diagram.AxisX.WholeRange.MinValue = 500;
diagram.AxisX.WholeRange.MaxValue = 2000;
// or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.WholeRange.SetMinMaxValues(500, 2000);

// Set limits for an x-axis's visual range
diagram.AxisX.VisualRange.MinValue = 1000;
diagram.AxisX.VisualRange.MaxValue = 1500;
// or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.VisualRange.SetMinMaxValues(1000, 1500);

Dim diagram As XYDiagram = TryCast(chartControl1.Diagram, XYDiagram)

' Set the lower limit for an x-axis's whole range.
diagram.AxisX.WholeRange.MinValue = 500
' Set the upper limit for an x-axis's whole range.
diagram.AxisX.WholeRange.MaxValue = 2000
' or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.WholeRange.SetMinMaxValues(500, 2000)

' Set the lower limit for an x-axis's visual range.
diagram.AxisX.VisualRange.MinValue = 1000
' Set the upper limit for an x-axis's visual range.
diagram.AxisX.VisualRange.MaxValue = 1500
' or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.VisualRange.SetMinMaxValues(1000, 1500)

How to Limit the Date-Time Axis Range

C#
VB.NET

csharp

XYDiagram diagram = chartControl1.Diagram as XYDiagram;

// Set limits for an x-axis's whole range
diagram.AxisX.WholeRange.MinValue = new DateTime(2017, 01, 01);     
diagram.AxisX.WholeRange.MaxValue = new DateTime(2019, 12, 31);
// or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.WholeRange.SetMinMaxValues(new DateTime(2017, 01, 01), new DateTime(2019, 12, 31));

// Set limits for an x-axis's visual range
diagram.AxisX.VisualRange.MinValue = new DateTime(2018, 01, 01);
diagram.AxisX.VisualRange.MaxValue = new DateTime(2019, 01, 01);
// or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.VisualRange.SetMinMaxValues(new DateTime(2018, 01, 01), new DateTime(2019, 01, 01));

Dim diagram As XYDiagram = TryCast(chartControl1.Diagram, XYDiagram)

' Set limits for an x-axis's whole range
diagram.AxisX.WholeRange.MinValue = New DateTime(2017, 01, 01)
diagram.AxisX.WholeRange.MaxValue = New DateTime(2019, 12, 31)
' or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.WholeRange.SetMinMaxValues(New DateTime(2017, 01, 01), New DateTime(2019, 12, 31))

' Set limits for an x-axis's visual range
diagram.AxisX.VisualRange.MinValue = New DateTime(2018, 01, 01)
diagram.AxisX.VisualRange.MaxValue = New DateTime(2019, 01, 01)
' or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.VisualRange.SetMinMaxValues(New DateTime(2018, 01, 01), New DateTime(2019, 01, 01))

How to Limit the Time-Span Axis Range

C#
VB.NET

csharp

XYDiagram diagram = chartControl1.Diagram as XYDiagram;

// Set limits for an x-axis's whole range
diagram.AxisX.WholeRange.MinValue = new TimeSpan(0,0,0);
diagram.AxisX.WholeRange.MaxValue = new TimeSpan(1, 0, 0, 0);
// or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.WholeRange.SetMinMaxValues(new TimeSpan(0, 0, 0), new TimeSpan(1, 0, 0, 0));

// Set limits for an x-axis's visual range
diagram.AxisX.VisualRange.MinValue = new TimeSpan(6, 0, 0);
diagram.AxisX.VisualRange.MaxValue = new TimeSpan(12, 0, 0);
// or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.VisualRange.SetMinMaxValues(new TimeSpan(6, 0, 0), new TimeSpan(12, 0, 0));

Dim diagram As XYDiagram = TryCast(chartControl1.Diagram, XYDiagram)

' Set limits for an x-axis's whole range
diagram.AxisX.WholeRange.MinValue = New TimeSpan(0, 0, 0)
diagram.AxisX.WholeRange.MaxValue = New TimeSpan(1, 0, 0, 0)
' or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.WholeRange.SetMinMaxValues(New TimeSpan(0, 0, 0), New TimeSpan(1, 0, 0, 0))

' Set limits for an x-axis's visual range
diagram.AxisX.VisualRange.MinValue = New TimeSpan(6, 0, 0)
diagram.AxisX.VisualRange.MaxValue = New TimeSpan(12, 0, 0)
' or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.VisualRange.SetMinMaxValues(New TimeSpan(6, 0, 0), New TimeSpan(12, 0, 0))

How to Limit the Qualitative Axis Range

C#
VB.NET

csharp

XYDiagram diagram = chartControl1.Diagram as XYDiagram;

// Use the actual string categories from the data source.
// Set limits for an x-axis's whole range
diagram.AxisX.WholeRange.MinValue = "Camera";
diagram.AxisX.WholeRange.MaxValue = "Flash";
// or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.WholeRange.SetMinMaxValues("Camera", "Flash");

// Set limits for an x-axis's visual range
diagram.AxisX.VisualRange.MinValue = "Camcorder";
diagram.AxisX.VisualRange.MaxValue = "Binoculars";
// or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.VisualRange.SetMinMaxValues("Camcorder", "Binoculars");

Dim diagram As XYDiagram = TryCast(chartControl1.Diagram, XYDiagram)

' Use the actual string categories from the data source.
' Set limits for an x-axis's whole range
diagram.AxisX.WholeRange.MinValue = "Camera"
diagram.AxisX.WholeRange.MaxValue = "Flash"
' or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.WholeRange.SetMinMaxValues("Camera", "Flash")

' Set limits for an x-axis's visual range
diagram.AxisX.VisualRange.MinValue = "Camcorder"
diagram.AxisX.VisualRange.MaxValue = "Binoculars"
' or use the SetMinMaxValues method to specify range limits.
diagram.AxisX.VisualRange.SetMinMaxValues("Camcorder", "Binoculars")

The Chart Control recalculates the maximum and minimum range values as float numbers for Qualitative , DateTime , and TimeSpan axes (see Axis Scale Types for more information). These float equivalents are available via the Range.MinValueInternal and Range.MaxValueInternal properties.

Use the AxisBase.GetScaleValueFromInternal(System.Double) method to convert an internal numerical value to its equivalent for a DateTime, TimeSpan or Qualitative axis.

The following example displays the first five series points when you use a qualitative axis and the fifth argument value is unknown:

C#
VB.NET

csharp

XYDiagram diagram = (XYDiagram)chartControl1.Diagram;
diagram.AxisX.VisualRange.MinValue = diagram.AxisX.GetScaleValueFromInternal(0);
diagram.AxisX.VisualRange.MaxValue = diagram.AxisX.GetScaleValueFromInternal(4);

Dim diagram As XYDiagram = CType(chartControl1.Diagram, XYDiagram)
diagram.AxisX.VisualRange.MinValue = diagram.AxisX.GetScaleValueFromInternal(0)
diagram.AxisX.VisualRange.MaxValue = diagram.AxisX.GetScaleValueFromInternal(4)

When you change an axis’s MeasureUnit (DateTimeScaleOptions.MeasureUnit, TimeSpanScaleOptions.MeasureUnit or NumericScaleOptions.MeasureUnit) property, the range limits are reset to default values. For this reason, specify the MeasureUnit value first to configure the MeasureUnit and the range’s limits.

Specify Diagram Side Margins

The Chart Control adds additional margins between the outermost series point and the diagram’s edge. To configure margins, use the Range.StartSideMargin, Range.EndSideMargin or Range.SideMarginsValue properties.

The SideMarginSizeUnit property defines margin measurement units. When SideMarginSizeUnit is set to SideMarginSizeUnit.AxisUnit (the default value), margins are specified in axis measurement units.

Property Value	Example
WholeRange.SideMarginsValue = 200
WholeRange.SideMarginsValue = 0

C#
VB.NET

csharp

XYDiagram diagram = chartControl1.Diagram as XYDiagram;
diagram.AxisX.WholeRange.SideMarginsValue = 0;

Dim diagram As XYDiagram = TryCast(chartControl1.Diagram, XYDiagram)
diagram.AxisX.WholeRange.SideMarginsValue = 0

Set Range.SideMarginSizeUnit to SideMarginSizeUnit.AxisRangePercentage to define margins as a percentage of the axis range.

The following example shows how to set the left margin as a percentage:

C#
VB.NET

csharp

XYDiagram diagram = chart.Diagram as XYDiagram;
diagram.AxisX.WholeRange.SideMarginSizeUnit = SideMarginSizeUnit.AxisRangePercentage;
diagram.AxisX.WholeRange.StartSideMargin = 20;

Dim diagram As XYDiagram = TryCast(chart.Diagram, XYDiagram)
diagram.AxisX.WholeRange.SideMarginSizeUnit = SideMarginSizeUnit.AxisRangePercentage
diagram.AxisX.WholeRange.StartSideMargin = 20

If you specify the SideMarginsValue , StartSideMargin or EndSideMargin properties, the control ignores the Range.AutoSideMargins property.

Hide Zero Level on a Chart Value Axis

If you want your y-axis to start at the first value, disable the WholeRange.AlwaysShowZeroLevel property. In this case, a new minimum value is calculated for the y-axis based on the underlying data.

Property Value	Example
AlwaysShowZeroLevel = false
AlwaysShowZeroLevel = true

C#
VB.NET

csharp

XYDiagram diagram = chartControl1.Diagram as XYDiagram;
diagram.AxisY.WholeRange.AlwaysShowZeroLevel = false;

Dim diagram As XYDiagram = TryCast(chartControl1.Diagram, XYDiagram)
diagram.AxisY.WholeRange.AlwaysShowZeroLevel = false

Configure Y-Axis’s Range Based on X-Axis’s Visual Range

The y-axis visual range is determined based on the x-axis whole range. To make a y-axis calculate its range based on the x-axis visual range only, set the XYDiagram2D.DependentAxesYRange property to true. Use the AxisXBase.StickToEdge property to specify whether the visual range sticks to the whole range’s start or end.

Property Value	Example
DependentAxesYRange = false
DependentAxesYRange = true

C#
VB.NET

csharp

XYDiagram diagram = chartControl1.Diagram as XYDiagram;
diagram.DependentAxesYRange = DevExpress.Utils.DefaultBoolean.True;
diagram.AxisX.StickToEdge = true;
diagram.AxisX.WholeRange.SideMarginsValue = 2;
diagram.AxisX.VisualRange.SetMinMaxValues((double)diagram.AxisX.WholeRange.MaxValue - 20, diagram.AxisX.WholeRange.MaxValue);

Dim diagram As XYDiagram = TryCast(chartControl1.Diagram, XYDiagram)
diagram.DependentAxesYRange = DevExpress.Utils.DefaultBoolean.True
diagram.AxisX.StickToEdge = True
diagram.AxisX.WholeRange.SideMarginsValue = 2
diagram.AxisX.VisualRange.SetMinMaxValues(CDbl(diagram.AxisX.WholeRange.MaxValue) - 20, diagram.AxisX.WholeRange.MaxValue)

Track Range Changes

The Chart Control’s ChartControl.AxisWholeRangeChanged and ChartControl.AxisVisualRangeChanged events track range changes. To obtain previous and new limits for a changed range, use the AxisRangeChangedEventArgs.MinChange and AxisRangeChangedEventArgs.MaxChange properties.

C#
VB.NET

csharp

chartControl1.AxisVisualRangeChanged += OnChartControlAxisVisualRangeChanged;
//...
private void OnChartControlAxisVisualRangeChanged(object sender, AxisRangeChangedEventArgs e) {
    if (e.Axis is AxisX) {
        StringBuilder str = new StringBuilder();
        str.Append($"Measure Unit: <b>{e.Axis.DateTimeScaleOptions.MeasureUnit}</b>{Environment.NewLine}");
        str.Append($"Min Value changed from <b>{e.MinChange.OldValue}</b> to <b>{e.MinChange.NewValue}</b>{Environment.NewLine}");
        str.Append($"Max Value changed from <b>{e.MaxChange.OldValue}</b> to <b>{e.MaxChange.NewValue}</b>");
        ((AxisX)e.Axis).Title.Visibility = DefaultBoolean.True;
        ((AxisX)e.Axis).Title.Text = str.ToString();
    }
}

chartControl1.AxisVisualRangeChanged += OnChartControlAxisVisualRangeChanged
'...
Private Sub OnChartControlAxisVisualRangeChanged(ByVal sender As Object, ByVal e As AxisRangeChangedEventArgs)
    If TypeOf e.Axis Is AxisX Then
        Dim str = New StringBuilder
        str.Append($"Measure Unit: <b>{e.Axis.DateTimeScaleOptions.MeasureUnit}</b>{Environment.NewLine}")
        str.Append($"Min Value changed from <b>{e.MinChange.OldValue}</b> to <b>{e.MinChange.NewValue}</b>{Environment.NewLine}")
        str.Append($"Max Value changed from <b>{e.MaxChange.OldValue}</b> to <b>{e.MaxChange.NewValue}</b>")
        CType(e.Axis, AxisX).Title.Visibility = DefaultBoolean.True
        CType(e.Axis, AxisX).Title.Text = str.ToString
    End If
End Sub