Zooming, Panning, and Scrolling

Canvas navigation can be divided into two main categories: zooming and scrollbar handling, which are managed by the CanvasComponent itself, and panning, which is managed by the MoveViewportInputMode.

Note	The scrollable area and the zoom level can be efficiently limited using a ViewportLimiter, as discussed in the section Restricting the Viewport.

Mouse Wheel and Scroll Bars

The GraphComponent provides properties to specify mouse wheel behavior, scroll bar policy, and zoom limits.

mouseWheelBehavior: Determines whether the mouse wheel is used to zoom, scroll, or both.
mouseWheelZoomFactor: Determines how quickly the zoom level changes when the mouse wheel is turned.
mouseWheelScrollFactor: Determines how quickly the viewport scrolls when the mouse wheel is turned.
centerZoomEventRecognizer: An event recognizer that determines whether zooming occurs towards the center of the view or towards the mouse location.
mouseWheelZoomEventRecognizer: An event recognizer that determines whether mouse wheel turns should scroll or zoom. This recognizer is used only if mouseWheelBehavior has both the SCROLL and ZOOM flags.
verticalScrollBarPolicy
horizontalScrollBarPolicy: Determines whether and when to display vertical and horizontal scroll bars.
minimumZoom
maximumZoom: Minimum and maximum allowed values for the zoom factor.

Related events
Event	Occurs when …
viewport-changed	… the viewport has changed. This also happens when the zoom factor or the scrollbars' visibility changes.
zoom-changed	… the zoom factor has changed.

Panning

Panning, i.e., dragging the visible area with the pointer, is handled by MoveViewportInputMode. This input mode is a child input mode of both GraphEditorInputMode and GraphViewerInputMode.

MoveViewportInputMode allows customization by changing the recognizers for some gestures. This is important to avoid conflicts with input modes which share the same gesture (dragging on an empty canvas), e.g., MarqueeSelectionInputMode or LassoSelectionInputMode.

The following event recognizers are used to handle moving the viewport via mouse or stylus input:

validBeginRecognizer: An event recognizer that returns true if it is valid to begin moving the viewport at this location. The default event recognizer always returns true. Only if it returns true, are any of the following event recognizers queried.
beginRecognizer: An event recognizer that returns true if an event is recognized as a gesture that starts moving the viewport.
moveRecognizer: An event recognizer that returns true if an event is recognized as a gesture during viewport movement.
finishRecognizer: An event recognizer that returns true if an event is recognized as a valid gesture to finish panning.

MoveViewportInputMode also supports touch gestures for panning and pinch zooming. Panning and zooming work together. As a result, some event recognizers have different effects depending on whether the MoveViewportInputMode is currently in the panning or zooming state.

The following event recognizers are used to handle panning or zooming the viewport via touch gestures:

validBeginRecognizer: An event recognizer that returns true if it is valid to begin panning or pinch zooming the viewport at this location. The default event recognizer always returns true. Only if it returns true, are any of the following event recognizers queried.
beginRecognizerTouch: An event recognizer that returns true if an event is recognized as a gesture that initiates panning the viewport and sets the MoveViewportInputMode to its panning mode. It usually recognizes the primary touch (i.e., "primary finger down").
moveRecognizerTouch: An event recognizer that returns true if an event is recognized as a drag gesture. In panning mode, it pans the viewport, while in pinch zoom mode, it zooms the viewport. It usually recognizes movement of the primary touching finger.
finishRecognizerTouch: An event recognizer that returns true if an event is recognized as a valid gesture to finish dragging. In panning mode, it finishes the panning gesture, while in pinch zoom mode, the mode changes to panning with the pinchZoomRecognizer instead. It usually recognizes when the primary touching finger is lifted.
beginPinchZoomRecognizer: An event recognizer that returns true if an event is recognized as the start of a pinch gesture, causing the MoveViewportInputMode to switch from panning to pinch zoom mode. It usually recognizes the secondary touch (i.e., "secondary finger down").
pinchZoomRecognizer: An event recognizer that returns true if an event is recognized as a pinch gesture. In pinch mode, it performs pinch zooming the viewport, while in panning mode, the viewport is panned. It usually recognizes movement of the secondary touching finger.
finishPinchZoomRecognizer: An event recognizer that returns true if an event is recognized as a valid gesture to finish pinch zooming. In pinch zoom mode, the mode changes to panning mode, while in panning mode, the panning gesture is finished. It usually recognizes when the secondary touching finger is lifted.

In short, the default behavior is that moving a single touching finger pans the viewport, while pinch zooming occurs when two fingers are touching.

Related events
Event	Occurs when …
drag-starting	… a drag gesture is recognized, but before the input mode is initialized for dragging.
drag-started	… a drag gesture is recognized, after the input mode has been initialized for dragging.
dragging	… the mouse is moved during drag operations and before the viewport is moved in response to that drag.
dragged	… the mouse is moved during drag operations and after the viewport has been moved in response to that drag.
drag-canceling	… a drag gesture is canceled, but before the input mode has been cleaned up.
drag-canceled	… a drag gesture is canceled, after the input mode has been cleaned up.
drag-finishing	… a drag gesture has ended successfully, but before any final cleanup happens.
drag-finished	… a drag gesture has ended successfully, after final cleanup has happened.

Customizing Cursors Creating Nodes