Navigation

Navigate through DrawingSession. These methods move the mounted canvas camera immediately; they do not move elements, change the document, or add undo entries. For timed movement, use the separate Animation API.

session.navigateToPoint(const DiagramPoint(240, 160), zoom: 1.25);
final found = session.navigateToElement('review', padding: 48);

Mounting and coordinates

Mount DrawingCanvas(session: session) before calling navigation or coordinate-conversion methods. Calls on a detached or disposed session throw StateError. For initial navigation, wait until the canvas has completed its first layout, for example in a post-frame callback.

Quantity	Coordinate space
DiagramPoint passed to navigation	World coordinates in the document.
DiagramRect passed to navigation	World bounds to fit in the viewport.
padding	Logical screen pixels on each side of the viewport.
zoom	Scale factor: 1 means 100%; clamped to the current camera limits.

Finite-canvas policy may constrain the requested camera center. Fitting preserves aspect ratio and chooses the smaller of the horizontal and vertical scales, within zoom limits. A rectangle or viewport with nonpositive width or height leaves the camera unchanged.

Immediate navigation methods

void navigateToPoint(DiagramPoint point, {double? zoom})
void navigateToRectangle(DiagramRect bounds, {double padding = 48})
bool navigateToElement(String elementId, {double padding = 48})
bool navigateToRegion(String elementId, String regionId, {double padding = 48})
bool navigateToSelection({double padding = 48})

Method	Required arguments	Optional arguments	Result
navigateToPoint	point: requested world center.	zoom: preserve current zoom when omitted.	void; centers the view without fitting content.
navigateToRectangle	bounds: rectangle to frame.	padding = 48.	void; centers and fits the bounds.
navigateToElement	elementId: existing resolved element ID.	padding = 48.	true when found; false if absent. Fits its resolved bounds.
navigateToRegion	elementId, regionId: owner and declared layer ID.	padding = 48.	true when found; false if either is absent. Fits the world bounds of the transformed layer.
navigateToSelection	None.	padding = 48.	true when selection bounds exist; false for no resolved selection.

regionId is a shape-layer definition ID, not a text story ID or text slot ID. Region navigation resolves layers on shapes and text elements; a frame has no region target through this method. Rotated regions are fitted using their axis-aligned world bounds.

Every immediate navigation command cancels an active viewport animation, including an element or region lookup that returns false. A true result means the target was resolved; it does not guarantee that zoom limits permit a perfect fit.

Coordinate conversion

DiagramPoint screenToWorld(DiagramPoint screenPoint)
DiagramPoint globalToWorld(Offset globalPosition)

Method	Argument	Return
screenToWorld	Point relative to the canvas's top-left, in logical pixels.	World point under that canvas position.
globalToWorld	Flutter global pointer position, such as details.globalPosition.	World point after converting through the canvas render box and camera.

globalToWorld also throws StateError if the mounted canvas has not been laid out. Do not pass a global pointer coordinate to screenToWorld when the canvas is embedded below a header or beside a panel.

cameraState

DiagramCameraState? get cameraState

Returns the mounted camera snapshot, or null while detached. Reading it after disposing the session throws StateError. The immutable snapshot exposes:

Property	Type	Meaning
center	DiagramPoint	World point at the viewport center.
zoom	double	Current projection scale.
viewportSize	DiagramSize	Laid-out canvas size in logical pixels.
minZoom	double	Lower zoom limit; camera-state constructor default 0.25.
maxZoom	double	Upper zoom limit; camera-state constructor default 4.

DiagramCameraState.copyWith(...) creates a snapshot; it does not update a session. Use navigation methods to change the mounted camera.

Presentation listeners

void addPresentationListener(VoidCallback listener)
void removePresentationListener(VoidCallback listener)

Member	Contract
addPresentationListener	Registers a no-argument callback for transient camera and animation changes. It can be registered before mounting. Throws after disposal.
removePresentationListener	Removes the same callback instance; safely does nothing after disposal.

Read session.cameraState or session.pathAnimations inside the callback. Camera listeners run after the new camera state is published to the store, including layout, user navigation, and animation. Identical camera geometry does not notify. These listeners are separate from document events and undo/redo.

void onPresentationChanged() {
  final camera = session.cameraState;
  if (camera != null) {
    final percentage = (camera.zoom * 100).round();
    // Update the host's zoom indicator with percentage.
  }
}

session.addPresentationListener(onPresentationChanged);
// During host cleanup:
session.removePresentationListener(onPresentationChanged);

For gesture behavior, including touch pan and pinch, see DrawingCanvas. For canvas bounds and grid configuration, see Configuration and Grids.