Axis Ranging - Restricting VisibleRange

Clipping the Axis VisibleRange on Zoom and Pan using the VisibleRangeLimit

Given a chart with data in the range of [0, 10], when you zoom to extents, the axis will have a VisibleRange of [0, 10]. Sometimes this is not desirable, and you want to clip the setVisibleRange(IRange visibleRange) inside the data-range. To do this, you can use the visibleRangeLimit property.

For example. Given an axis without any limits (visibleRangeLimit = nil). When we perform ZoomExtents on the chart, the XAxis gets the visible range [0, 10]:

No VisibleRange Limit

Actual XAxis.dataRange = [0, 10]; XAxis.visibleRangeLimit = nil; XAxis.visibleRange after ZoomExtents = [0, 10]

So let's set visibleRangeLimit = [4.5, 5.5]

final NumericAxis axis = new NumericAxis(getContext());
axis.setVisibleRangeLimit(new DoubleRange(4.5, 5.5));

After setting such VisibleRangeLimit and using ZoomExtents we now get an XAxis.visibleRange = [4.5, 5.5]. In other words, zooming has clipped or limited the visibleRange to [4.5, 5.5]

Note

VisibleRangeLimit expects a minimum and maximum value according to the setVisibleRange(IRange visibleRange) type.

VisibleRange Limit

Actual XAxis.dataRange = [0, 10]; XAxis.visibleRangeLimit = [4.5, 5.5]; XAxis.visibleRange after ZoomExtents = [4.5, 5.5]

VisibleRangeLimit Modes

Sometimes it is required to have one end of VisibleRange fixed or restrict VisibleRange either by min or max value. For that purposes, Axis API exposes RangeClipMode. It allows to specify visibleRangeLimitMode property to choose a behavior which is best suitable for a particular scenario.

  • MinMax – (Default) allows clipping at Min and Max.
  • Max - allows clipping only at Max.
  • Min - allows clipping only at Min.

Use this property if you wish to ensure that one side of the chart is always clipped, while the other side is not. For instance:

final NumericAxis axis = new NumericAxis(getContext());
axis.setVisibleRangeLimit(new DoubleRange(0.0, 0.0));
axis.setVisibleRangeLimitMode(RangeClipMode.Min);

Results in a chart that always sets axis.visibleRange.min = 0 when you zoom to extents.

Note

VisibleRangeLimit does not clip data range when VisibleRangeLimit is greater than data range. In this case after ZoomExtents you’ll get the actual data range.

Advanced VisibleRange Clipping

visibleRangeLimit is a useful API to ensure the axis clips the visibleRange when zooming to extents. However, it will not stop a user from scrolling outside of that range. To achieve that, you will need to clip the visibleRange in code.

To clip the setVisibleRange(IRange visibleRange) and force a certain maximum or minimum, just use the following code:

final NumericAxis axis = new NumericAxis(getContext());
axis.setVisibleRangeChangeListener(new VisibleRangeChangeListener() {
    @Override
    public void onVisibleRangeChanged(IAxisCore axis, IRange oldRange, IRange newRange, boolean isAnimating) {
        // Set the old range back on the axis if the new Min is less than 0
        if (newRange.getMinAsDouble() < 0.0) {
            axis.setVisibleRange(oldRange);
        }
    }
});

Minimum or Maximum Zoom Level

If you want to constrain zoom depth in your application, the minimalZoomConstrain allows you to specify the minimal difference between Min and Max values of axis VisibleRange. If the difference becomes less than MinimalZoomConstrain value - then VisibleRange will not change.

It is also possible to specify the maximumZoomConstrain which defines the maximal difference between Min and Max values of axis VisibleRange. If the difference becomes more than MaximumZoomConstrain value - then VisibleRange will not change.

Read on to learn how to apply Minimum or Maximum Zoom Level for different Axis Types.

Specifying ZoomConstrains for NumericAxis

In the following code we are going to specify the visibleRange for NumericAxis. It should never become less than 10 and greater than 100. In other words - always be in range of [10, 100].

final NumericAxis axis = new NumericAxis(getContext());
axis.setMinimalZoomConstrain(10);
axis.setMaximumZoomConstrain(100);

Specifying ZoomConstrains for CategoryDateAxis

ZoomConstrains works differently if set on CategoryDateAxis. It determines the min/max zoom level on an axis which is possible to show by the specifying the amount of data points.

final CategoryDateAxis axis = new CategoryDateAxis(getContext());
axis.setMinimalZoomConstrain(10);
axis.setMaximumZoomConstrain(100);

In the code above, VisibleRange should show no less than 10 data points as well as no more that 100 data points.

Specifying ZoomConstrains for DateAxis

DateAxis has its specifics as well. It's VisibleRange is of DateRange type, so the Zoom Constraints is designed to specify the difference between two dates in seconds. Setting Zoom Constraints on a DateRange, you ensure that your axis.visibleRange.diff will never become less than the minimalZoomConstrain value and more than maximumZoomConstrain.

Note

For convenience, SciChart provides a bunch of helper methods in the DateIntervalUtil class:

DateAxis axis = new DateAxis(getActivity());
long min = DateIntervalUtil.fromMonths(2);
long max = DateIntervalUtil.fromMonths(10);
axis.setMinimalZoomConstrain(min);
axis.setMaximumZoomConstrain(max);

In the code above, the VisibleRange will satisfy the following equation: 2 months < VisibleRange < 10 month

See Also