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.

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.

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.