Whole and Visual Axis Ranges

  • 8 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

This article consists of the following sections:

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:

XYDiagram diagram = chartControl1.Diagram as 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:

How to Limit the Numeric Axis Range

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);

How to Limit the Date-Time Axis Range

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));

How to Limit the Time-Span Axis Range

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));

How to Limit the Qualitative Axis Range

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");

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.

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
XYDiagram diagram = chartControl1.Diagram as 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:

XYDiagram diagram = chart.Diagram as 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_false
AlwaysShowZeroLevel = true AlwaysShowZeroLevel_true
XYDiagram diagram = chartControl1.Diagram as 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 AxisY.DependentRange_false
DependentAxesYRange = true AxisY.DependentRange_true
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);

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.

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();
    }
}
See Also