Zoom and Scroll in 2D XY-Charts

  • 8 minutes to read

The chart control supports scroll and zoom operations. This topic describes end-user capabilities and the API you can use to perform these operations in code.

Allow End-Users to Zoom and Scroll a Chart

Use the XYDiagram2D.EnableAxisXNavigation and XYDiagram2D.EnableAxisYNavigation properties to allow users to zoom and scroll a chart:

 <dxc:ChartControl>
    <dxc:XYDiagram2D 
        EnableAxisXNavigation="True"
        EnableAxisYNavigation="True">
    </dxc:XYDiagram2D>
 </dxc:ChartControl>

You can use the Pane.EnableAxisXNavigation and Pane.EnableAxisYNavigation properties to enable/disable scroll and zoom operations within specific panes.

<dxc:XYDiagram2D.Panes>
    <dxc:Pane  
        EnableAxisXNavigation="True"
        EnableAxisYNavigation="True">
    </dxc:Pane> 
</dxc:XYDiagram2D.Panes>   

The NavigationOptions.AxisXMaxZoomPercent and NavigationOptions.AxisYMaxZoomPercent properties specify zoom limits. The default maximum is x100 (10,000%). When a user reaches the limit, the mouse pointer changes to ZoomingAndScrolling_Zooming04.png.

<dxc:XYDiagram2D>
    <dxc:XYDiagram2D.NavigationOptions>
        <dxc:NavigationOptions 
            AxisXMaxZoomPercent="500" 
            AxisYMaxZoomPercent="500"/>
    </dxc:XYDiagram2D.NavigationOptions>
</dxc:XYDiagram2D>

End-User Capabilities

Users can utilize keyboard shortcuts, mouse operations, and touch gestures to zoom and scroll a chart:

<dxc:XYDiagram2D>
    <dxc:XYDiagram2D.NavigationOptions>
        <dxc:NavigationOptions 
            UseKeyboard="True"
            UseScrollBars="True"
            UseMouse="True"
            UseTouchDevice="True"/>
    </dxc:XYDiagram2D.NavigationOptions>
</dxc:XYDiagram2D>

Related API members:

Member Description
XYDiagram2D.NavigationOptions Specifies zoom and scroll options for XYDiagram2D.
NavigationOptionsBase.UseKeyboard Specifies whether a user can use a keyboard to zoom and scroll a chart.
NavigationOptionsBase.UseScrollBars Specifies whether a user can use scrollbars to scroll a chart.
NavigationOptionsBase.UseMouse Specifies whether a user can use a mouse to zoom and scroll a chart.
NavigationOptionsBase.UseTouchDevice Specifies whether a user can use touchscreen devices to zoom and scroll a chart.
NOTE

Set ChartControl.IsManipulationEnabled to true to allow users to use gestures to zoom and scroll.

End-User Capabilities: Zoom a Chart

Action

Effect

SHIFT + Click

After you press SHIFT, the mouse pointer changes to ZoomingAndScrolling_Zooming01.png. Click any chart region to zoom in by a factor of three.

ALT + Click

After you press ALT, the mouse pointer changes to ZoomingAndScrolling_Zooming02.png. Click any chart region to zoom out by a factor of three.

SHIFT + Selection

After you press SHIFT, the mouse pointer changes to ZoomingAndScrolling_Zooming01.png. Use the left mouse button to select a region on the chart and then release the button.

ZoomingAndScrolling

A chart is zoomed into the selected region bounds.

CTRL + "+"

The diagram is zoomed in by 20 percent.

CTRL + "-"

The diagram is zoomed out by 20 percent.

Mouse Wheel

Move the mouse pointer over a diagram and spin the mouse scroll wheel to zoom in/out by 20 percent. Move the mouse pointer over an axis and spin the mouse scroll wheel to zoom into (or zoom out of) a diagram by an individual axis.

Spread / Pinch Gestures

The spread and pinch gestures zoom into and out of a diagram on touchscreen devices.

Gesture_ZoomInGesture_ZoomOut

CTRL + Z

A diagram returns to the previous zoom state. All subsequent operations of a similar kind (e.g., multiple "zoom in" operations) are considered to be a single transaction.

Actions to Scroll a Chart

Action

Effect

Pan the chart

When you press and hold a mouse button, the pointer changes from ZoomingAndScrolling_Scrolling01.png to ZoomingAndScrolling_Scrolling02.png. Move the mouse pointer with the mouse button pressed to scroll the diagram.

Use scroll bars

Press CTRL + "Arrow" keys ("Left", "Up", "Right" or "Down").

Press CTRL + "Left" to move the diagram to the left.

Press CTRL + "Up" to move the diagram up.

Press CTRL + "Right" to move the diagram to the right.

Press CTRL + "Down" to move the diagram down.

Use flick gestures

Flick gestures scroll the diagram on touchscreen devices.

Gesture_Scroll

Use API

Zoom a Chart

Use the following API members to process zoom operations:

The XYDiagram2D.ZoomIn method zooms in to a diagram.

XYDiagram2D diagram = (XYDiagram2D)chart.Diagram;
diagram.ZoomIn(new Point(200, 200));

The XYDiagram2D.ZoomOut method zooms out of a diagram.

XYDiagram2D diagram = (XYDiagram2D)chart.Diagram;
diagram.ZoomOut(new Point(200, 200));

The XYDiagram2D.ZoomIntoRectangle method zooms a diagram into a specified rectangle.

XYDiagram2D diagram = (XYDiagram2D)chart.Diagram;
Rect rectangle = new Rect(new Point(200, 200), new Size(350, 350));
diagram.ZoomIntoRectangle(rectangle);

The XYDiagram2D.SetAxisXZoomRatio(Double) and XYDiagram2D.SetAxisYZoomRatio(Double) methods allow you to change the zoom level of the X and Y axes to the zoom ratio passed as a parameter. You can set the ratio parameter to any double value between 0 (no zoom) and 1 (the maximum zoom value).

XYDiagram2D diagram = (XYDiagram2D)chart.Diagram;
diagram.SetAxisXZoomRatio(0.25);
diagram.SetAxisYZoomRatio(0.25);

Use the XYDiagram2D.CanZoomIn, XYDiagram2D.CanZoomOut, or XYDiagram2D.CanZoomIntoRectangle method to check whether zoom operations are possible. The following code changes the cursor's appearance when the chart is displayed at the maximum zoom level:

private void chartControl1_QueryChartCursor(object sender, QueryChartCursorEventArgs e) {
    ChartControl chart = (ChartControl)sender;
        XYDiagram2D diagram = (XYDiagram2D)chart.Diagram;
            if (!diagram.CanZoomIn()) {
                e.Cursor = Cursors.None;
                e.CursorImage = new BitmapImage(new Uri(@"/CustomCursor;component/mycursor.png", UriKind.Relative));
    }
}

Use the XYDiagram2D.Zoom event to track range changes when a user zooms the chart.

private void XYDiagram2D_Zoom(object sender, DevExpress.Xpf.Charts.XYDiagram2DZoomEventArgs e) {
    // Get new range limits.
    object newXRangeMin = e.NewXRange.MinValue;
    object newXRangeMax = e.NewXRange.MaxValue;
    object newYRangeMin = e.NewYRange.MinValue;
    object newYRangeMax = e.NewYRange.MaxValue;
    //Add your custom logic here.
}

To cancel a zoom operation, handle the XYDiagram2D.BeforeZoom event and use the e.Cancel property.

private void XYDiagram2D_BeforeZoom(object sender, XYDiagram2DBeforeZoomEventArgs e) {
    if (e.Axis is AxisX2D) {
        e.Cancel = true;
    }
}

Scroll a Chart

Use the following API members to process scroll operations:

The XYDiagram2D.ScrollAxisXTo(Double) and XYDiagram2D.ScrollAxisYTo(Double) methods scroll axes to the specified position.

XYDiagram2D diagram = (XYDiagram2D)chart.Diagram;
diagram.ScrollAxisXTo(150);
diagram.ScrollAxisYTo(100);

The XYDiagram2D.ScrollHorizontally(Int32) and XYDiagram2D.ScrollVertically(Int32) methods scroll a diagram by a specified distance (in pixels) in the horizontal or vertical direction.

XYDiagram2D diagram = (XYDiagram2D)chart.Diagram;
diagram.ScrollHorizontally(50);
diagram.ScrollVertically(50);

Use the XYDiagram2D.CanScrollAxisXTo, XYDiagram2D.CanScrollAxisYTo, XYDiagram2D.CanScrollHorizontally, or XYDiagram2D.CanScrollVertically method to determine whether scroll operations are possible. The following code changes the cursor's appearance when a user cannot scroll a chart vertically:

private void chartControl1_QueryChartCursor(object sender, QueryChartCursorEventArgs e) {
    ChartControl chart = (ChartControl)sender;
    XYDiagram2D diagram = (XYDiagram2D)chart.Diagram;
    if (!diagram.CanScrollVertically(1)) {
        e.Cursor = Cursors.None;
        e.CursorImage = new BitmapImage(new Uri(@"/CustomCursor;component/mycursor.png", UriKind.Relative));
    }
}

Use the XYDiagram2D.Scroll event to track range changes when a user scrolls the chart.

private void XYDiagram2D_Scroll(object sender, XYDiagram2DScrollEventArgs e) {
    // Get new range limits.
    object newXRangeMin = e.NewXRange.MinValue;
    object newXRangeMax = e.NewXRange.MaxValue;
    object newYRangeMin = e.NewYRange.MinValue;
    object newYRangeMax = e.NewYRange.MaxValue;
    // Add your custom logic here.
}

To cancel a scroll operation, handle the XYDiagram2D.BeforeScroll event and set the e.Cancel property to true.

private void XYDiagram2D_BeforeScroll(object sender, XYDiagram2DBeforeScrollEventArgs e) {
    if (e.Axis is AxisY2D) {
        e.Cancel = true;
    }
}

Customize Scroll Bars and Cursor

Use the Pane.AxisXScrollBarOptions and Pane.AxisYScrollBarOptions properties to define scroll bar visibility, alignment, and thickness.

<dxc:XYDiagram2D>
    <dxc:XYDiagram2D.DefaultPane>
        <dxc:Pane>
            <dxc:Pane.AxisXScrollBarOptions>
                <dxc:ScrollBarOptions Visible="False"/>
            </dxc:Pane.AxisXScrollBarOptions>
            <dxc:Pane.AxisYScrollBarOptions>
                <dxc:ScrollBarOptions  Alignment="Far" BarThickness="12" Visible="True">
                </dxc:ScrollBarOptions>
            </dxc:Pane.AxisYScrollBarOptions>
        </dxc:Pane>
    </dxc:XYDiagram2D.DefaultPane>
</dxc:XYDiagram2D>

The table below lists the API members used to customize scroll bars:

Member Description
ScrollBarOptions.Alignment Specifies the scroll bar alignment.
ScrollBarOptions.BarThickness Specifies the scroll bar thickness.
ScrollBarOptions.Visible Specifies the scroll bar visibility.

The Chart Control allows you to indicate chart element positions on scroll bars. Use the ScrollBarOptions.AnnotatedElements property to list the elements to be displayed.

<dxc:XYDiagram2D>
    <dxc:XYDiagram2D.DefaultPane>
        <dxc:Pane>
            <dxc:Pane.AxisXScrollBarOptions>
                <dxc:ScrollBarOptions  AnnotatedElements="ConstantLine, PaneAnnotation"/>
            </dxc:Pane.AxisXScrollBarOptions>
            <dxc:Pane.AxisYScrollBarOptions>
                <dxc:ScrollBarOptions  AnnotatedElements="ConstantLine, PaneAnnotation"/>
            </dxc:Pane.AxisYScrollBarOptions>
        </dxc:Pane>
    </dxc:XYDiagram2D.DefaultPane>
</dxc:XYDiagram2D>

The scroll bar color scheme depends on the chart theme. For more information on how to change the theme, see the following help topic: Chart Themes and Palettes.

You can provide custom cursors for scroll and zoom operations in the ChartControl.QueryChartCursor event handler. To see an example, refer to the following help topic: Custom Cursor in the Chart Control.

See Also