Zoom and Scroll in 2D XY-Charts
- 11 minutes to read
This document explains how to navigate through a 2D chart. Users can scroll a chart along argument and value axes to pan a chart horizontally and vertically, and zoom a chart in/out.
Note
The Web
This help file explains how to:
- Allow Users to Zoom a Chart
- Zoom a Chart
- Use API to Zoom a Chart
- Allow Users to Scroll a Chart
- Scroll a Chart
- Use API to Scroll a Chart
- Customize Scroll Bar Appearance
- Specify Keyboard Shortcuts and Mouse Actions
#Allow Users to Zoom a Chart
The Chart control allows you to enable the capability to zoom a chart’s x-axis, y-axis or both axes.
XYDiagram xyDiagram = (XYDiagram)chartControl.Diagram;
xyDiagram.EnableAxisXZooming = true;
xyDiagram.EnableAxisYZooming = true;
The code listed above uses the following API members:
Member | Description |
---|---|
XYDiagram2D. |
Indicates whether a user can zoom a chart’s x-axis. |
XYDiagram2D. |
Indicates whether a user can zoom a chart’s y-axis. |
Use the XYDiagramPaneBase.EnableAxisXZooming and XYDiagramPaneBase.EnableAxisYZooming properties to define whether a user can zoom a diagram within a separate pane.
A chart cannot be zoomed more than the maximum zoom factor (100 times (10000%)). The mouse pointer changes to when a user achieves the maximum zoom. Use the ZoomingOptions2D.AxisXMaxZoomPercent and ZoomingOptions2D.AxisYMaxZoomPercent properties to specify a zoom factor’s limits.
#Zoom a Chart
Users can use a keyboard and/or mouse, and spread/pinch gestures on touchscreen devices to zoom a chart:
xyDiagram.ZoomingOptions.UseKeyboard = true;
xyDiagram.ZoomingOptions.UseKeyboardWithMouse = true;
xyDiagram.ZoomingOptions.UseMouseWheel = true;
xyDiagram.ZoomingOptions.UseTouchDevice = true;
The code above uses the following API members:
Member | Description |
---|---|
XYDiagram2D. |
Returns zooming options for the XY-Diagram. |
Zooming |
Specifies whether a user can use a keyboard to zoom a chart. |
Zooming |
Defines whether a user can use a keyboard and/or mouse to zoom a chart. |
Zooming |
Defines whether a user can use a mouse wheel to zoom a chart. |
Zooming |
Specifies whether a user can use touchscreen devices to zoom a chart. |
You can use the following actions to zoom a diagram:
Action | Effect |
---|---|
Press Shift and click the diagram. | The mouse pointer changes to |
Press Alt and click the diagram. | The mouse pointer changes to |
Press Shift and select a region on the diagram. | The mouse pointer changes to A chart is zoomed into the selected region bounds after a user releases the left mouse button. |
Use Ctrl with the + or - key. | A chart’s diagram is zoomed in by 20 percent from the current axis ranges if a user presses and holds the Ctrl key with the + key. A chart’s diagram is zoomed out by 20 percent from the current axis ranges if a user presses and holds the Ctrl key with the - key. |
Use the mouse wheel. | A user should hover a diagram with the mouse pointer and scroll the mouse wheel to zoom in/out by 20 percent from the current ranges of axes. To zoom in/out a chart by an individual axis, they should hover the axis with the mouse pointer and scroll the mouse wheel. |
Use the spread or pinch gestures on a touchscreen device. | Spread or pinch gestures allow a user to zoom in and out a diagram on any touchscreen devices.
|
Use Ctrl + Z. | Users should press the Ctrl + Z keys to return the previous zoom state of a diagram. Note that all subsequent operations of a similar kind (for example, multiple “zoom in” operations) are considered as a single transaction. A press of Ctrl + Z returns the zoom state existed before the first zoom operation in a zoom series. |
#Use API to Zoom a Chart
Use the following methods to zoom in/out a chart programmatically:
Use the XYDiagram2D.ResetZoom method to set visual range values to whole range values.
The ChartControl.Zoom event allows you to track how axis ranges change when a user zooms a chart. The ChartControl.BeforeZoom event allows you to use the ChartBeforeZoomEventArgs.Cancel property to cancel a zoom operation:
void chart_BeforeZoom(object sender, ChartBeforeZoomEventArgs e) {
if (!(e.Axis is AxisX))
return;
double rangeLengthInMeasureUnits = e.NewRange.Max - e.NewRange.Min;
if (rangeLengthInMeasureUnits > MaxZoomPointCount)
e.Cancel = true;
}
void chart_Zoom(object sender, ChartZoomEventArgs e) {
double rangeLengthInMeasureUnits = e.NewXRange.Max - e.NewXRange.Min;
if (rangeLengthInMeasureUnits > 1.2 * InitialPointCountOnScreen)
VolumeSeriesView.BarWidth = 1;
else
VolumeSeriesView.BarWidth = 0.6;
}
The code above uses the following API members:
Member | Description |
---|---|
Chart |
Occurs when a user zooms in/out of a chart. |
Chart |
Provides the Chart |
Chart |
Occurs before the chart is zoomed. |
Chart |
Provides the Chart |
You can also specify an axis’s visual or whole range to zoom a chart. See the following section for more information: Configure Visual and Whole Ranges.
The following code makes a chart display data for a specific range when a user clicks a button:
private void simpleButton1_OnClick(object sender, EventArgs e) {
Range range = ((XYDiagram)chartControl1.Diagram).AxisX.VisualRange;
range.MinValue = new DateTime(2019, 6, 1, 12, 0, 0);
range.MaxValue = new DateTime(2019, 6, 2, 3, 0, 0);
}
#Allow Users to Scroll a Chart
Users can scroll a diagram to navigate on a chart when they zoom in a diagram or when an axis’s visual range is less than its whole range. The Chart control allows you to enable scrolling for x and y-axis separately:
XYDiagram diagram = (XYDiagram)chartControl.Diagram;
diagram.EnableAxisXScrolling = true;
diagram.EnableAxisYScrolling = true;
The code above uses the following API members:
Member | Description |
---|---|
XYDiagram2D. |
Indicates whether a user can scroll a diagram by an x-axis. |
XYDiagram2D. |
Indicates whether a user can scroll a diagram by a y-axis. |
Use the XYDiagramPaneBase.EnableAxisXScrolling and XYDiagramPaneBase.EnableAxisYScrolling properties to define whether a user can scroll a diagram within a separate pane.
#Scroll a Chart
Users can utilize a mouse, keyboard, scroll bars and flick gestures on touchscreen devices to move through a diagram:
xyDiagram.ScrollingOptions.UseKeyboard = true;
xyDiagram.ScrollingOptions.UseMouse = true;
xyDiagram.ScrollingOptions.UseScrollBars = true;
xyDiagram.ScrollingOptions.UseTouchDevice = true;
The code above uses the following API members:
Member | Description |
---|---|
XYDiagram2D. |
Provides access to the options specifying the ways in which scrolling can be performed for a 2D XY-Diagram. |
Scrolling |
Specifies whether a user can use a keyboard to scroll a chart. |
Scrolling |
Defines whether a user can use a mouse to scroll a chart. |
Scrolling |
Specifies whether a user can use scroll bars to scroll a chart. |
Scrolling |
Defines whether a user can use touchscreen devices to scroll a chart. |
The following actions scroll a diagram:
Action | Effect |
---|---|
Press the left mouse button or wheel button, and drag the mouse pointer. | The mouse pointer changes from |
Use axes’ scroll bars. | A user can click a scrollbar arrow or the scrollbar near the thumb, or drag the thumb and move it. |
Use Ctrl + Arrow keys (Left, Up, Right or Down). | A diagram is moved to the left if a user presses Ctrl + Left. A diagram is moved up if a user presses Ctrl + Up. A diagram is moved to the right if a user presses Ctrl + Right. A diagram is moved down if a user presses Ctrl + Down. |
Use flick gestures on a touchscreen device. | Flick gestures allows a user to scroll a diagram on touchscreen devices. |
#Use API to Scroll a Chart
Use the XYDiagram2D.Scroll method to scroll a chart in code.
xyDiagram.Scroll(HorizontalScrollingDirection.Right, VerticalScrollingDirection.Up, xyDiagram.DefaultPane);
The code listed above uses the following API members:
Member | Description |
---|---|
XYDiagram2D. |
Scrolls a chart in a given direction. |
Horizontal |
Enumerates the possible horizontal scrolling directions. |
Vertical |
Enumerates the possible vertical scrolling directions. |
Handle the ChartControl.Scroll event to provide a custom functionality when a chart is being scrolled.
chartControl.Scroll += ChartControl_Scroll;
// ...
private void ChartControl_Scroll(object sender, ChartScrollEventArgs e) {
// Your custom logic here.
}
The previously mentioned code uses the following API members:
Member | Description |
---|---|
Chart |
Occurs when an end-user scrolls the Chart |
Chart |
Provides data for the Chart |
#Customize Scroll Bar Appearance
You can change a background color of scroll bars, their border’s color and thickness, and specify scroll bar position.
The following code configures scroll bar position, visibility and position:
xyDiagram.DefaultPane.ScrollBarOptions.XAxisScrollBarAlignment = ScrollBarAlignment.Near;
xyDiagram.DefaultPane.ScrollBarOptions.YAxisScrollBarAlignment = ScrollBarAlignment.Far;
xyDiagram.DefaultPane.ScrollBarOptions.XAxisScrollBarVisible = true;
xyDiagram.DefaultPane.ScrollBarOptions.YAxisScrollBarVisible = true;
xyDiagram.DefaultPane.ScrollBarOptions.BarThickness = 10;
xyDiagram.DefaultPane.ScrollBarOptions.BackColor = Color.DarkGray;
xyDiagram.DefaultPane.ScrollBarOptions.BarColor = Color.LightGray;
xyDiagram.DefaultPane.ScrollBarOptions.BorderColor = Color.Black;
The table below lists the API members you can use to customize scroll bars:
Member | Description |
---|---|
XYDiagram |
Gets the specific settings of scroll bars displayed within the pane while a user zooms or scrolls a chart. |
Scroll |
Specifies the x-axis scroll bar’s alignment. |
Scroll |
Specifies the y-axis scroll bar’s alignment. |
Scroll |
Lists scroll bars’ alignments. |
Scroll |
Gets or sets the x-axis scroll bar’s visibility. |
Scroll |
Gets or sets the y-axis scroll bar’s visibility. |
Scroll |
Specifies scroll boxes’ thickness. |
Scroll |
Specifies the background color of scroll bars. |
Scroll |
Gets or sets the scroll box color. |
Scroll |
Gets or sets the scroll bar border color. |
#Specify Keyboard Shortcuts and Mouse Actions
The Chart control allows you to assign keyboard shortcuts to the following actions:
Action | Shortcut key collection |
---|---|
Scroll down | Scrolling |
Scroll left | Scrolling |
Scroll right | Scrolling |
Scroll up | Scrolling |
Undo zoom | Zooming |
Zoom in | Zooming |
Zoom out | Zooming |
The following code assigns keyboard shortcut keys to the ScrollLeft, ScrollUp, ScrollRight, and ScrollDown operations:
// Use Shift + A or the Left arrow to move a diagram to the left.
xyDiagram.ScrollingOptions.ScrollLeftShortcuts.Add(Keys.Shift | Keys.A);
xyDiagram.ScrollingOptions.ScrollLeftShortcuts.Add(Keys.Left);
// Use Shift + W or the Up arrow to move a diagram up.
xyDiagram.ScrollingOptions.ScrollUpShortcuts.Add(Keys.Shift | Keys.W);
xyDiagram.ScrollingOptions.ScrollUpShortcuts.Add(Keys.Up);
// Use Shift + D or the Right arrow to move a diagram to the right.
xyDiagram.ScrollingOptions.ScrollRightShortcuts.Add(Keys.Shift | Keys.D);
xyDiagram.ScrollingOptions.ScrollRightShortcuts.Add(Keys.Right);
// Use Shift + S or the Down arrow to move a diagram down.
xyDiagram.ScrollingOptions.ScrollDownShortcuts.Add(Keys.Shift | Keys.S);
xyDiagram.ScrollingOptions.ScrollDownShortcuts.Add(Keys.Down);
You can change the predefined mouse button + keyboard key combination for the following actions:
Action | Property |
---|---|
Zoom in | Zooming |
Zoom out | Zooming |
Zoom to rectangle | Zooming |
Scroll | Scrolling |
The following code specifies the ZoomIn and ZoomOut actions:
XYDiagram xyDiagram = chartControl.Diagram as XYDiagram;
if(xyDiagram != null) {
xyDiagram.ZoomingOptions.ZoomInMouseAction.ModifierKeys = ChartModifierKeys.Control;
xyDiagram.ZoomingOptions.ZoomInMouseAction.MouseButton = MouseButtons.Right;
xyDiagram.ZoomingOptions.ZoomOutMouseAction.ModifierKeys = ChartModifierKeys.Shift;
xyDiagram.ZoomingOptions.ZoomOutMouseAction.MouseButton = MouseButtons.Right;
}
The code above uses the following API members:
Member | Description |
---|---|
Chart |
Gets or sets the mouse button the end user should use to interact with the chart. |
Chart |
Gets or sets the modifier keys. |