Skip to content
D
Documentation

Viewport

reference
3 min readUpdated

Import these from @grafloria/renderer.

Classes

ViewportController

ts
class ViewportController

Methods

  • constructor(options: ViewportControllerOptions = {})
  • getViewport(): Rectangle
  • getZoom(): number
  • getState(): ViewportState
  • setViewport(viewport: Rectangle): void — Replace the camera rectangle wholesale.
  • setCanvasSize(width: number, height: number, options: CanvasSizeOptions = {}): void — Track the canvas element's pixel size. Call on mount and on resize: the width/height of the camera rect must stay equal to the canvas's CSS-pixel size for {@link clientToWorld} to be the true inverse of the rendered viewBox (see the coordinate contract).
  • syncCanvasSize(rect: CanvasRect, options: CanvasSizeOptions = {}): void — Convenience form of {@link setCanvasSize} taking a getBoundingClientRect().
  • clampZoom(zoom: number): number — Clamp to [minZoom, maxZoom]. Non-finite input falls back to the current zoom.
  • setZoom(zoom: number): number — Set zoom (centre-preserving), clamped. Returns the zoom actually applied.
  • zoomBy(delta: number): number — Additive zoom step, clamped — the convention the Angular canvas's wheel handler uses (zoom + delta, not zoom * factor). Returns the applied zoom.
  • zoomByWheel(deltaY: number): number — Apply one wheel notch. Mirrors DiagramCanvasComponent.onWheel: scrolling DOWN (deltaY > 0) zooms OUT by zoomSensitivity, scrolling up zooms in.
  • zoomAtPoint(zoom: number, clientX: number, clientY: number, rect: CanvasRect): number — Cursor-anchored zoom: change zoom while keeping the world point currently under (clientX, clientY) pinned to that same screen pixel. This is the standard "zoom towards the pointer" behaviour; the plain {@link setZoom} / {@link zoomByWheel} pair is centre-anchored instead.
  • pan(dx: number, dy: number): void — Translate the camera by a WORLD-space delta.
  • panByScreenDelta(dxPx: number, dyPx: number): void — Translate the camera by a SCREEN-space (pixel) drag delta, converting to world units by dividing by zoom.
  • getViewBox(): Rectangle — The world-space rectangle actually visible — centre-preserving zoom applied to the camera rect. Identical to the viewBox SVGRenderer emits, and the basis of {@link clientToWorld}.
  • getViewBoxString(): string — The viewBox attribute string: "x y width height".
  • getRenderViewport(): Rectangle — The rectangle to hand to IRenderer.render(viewport, zoom) alongside {@link getZoom}. The renderer applies the zoom itself, so this is the raw camera rect — do NOT pre-divide it by zoom (see the class docs).
  • getHtmlLayerTransform(): string — CSS transform that keeps an HTML overlay layer registered with the SVG layer in the hybrid renderer: translate(...) scale(zoom).
  • clientToWorld(clientX: number, clientY: number, rect: CanvasRect): ViewportPoint — Convert a client/screen point (e.g. event.clientX/Y) into world space. Exact inverse of {@link worldToClient} at any zoom.
  • worldToClient(worldX: number, worldY: number, rect: CanvasRect): ViewportPoint — Convert a world point into client/screen coordinates — for positioning overlays, toolbars and tooltips over the canvas. Exact inverse of {@link clientToWorld}.
  • fitToBounds(bounds: Rectangle, padding = 40, options?: { maxZoom?: number }): number — Frame bounds (a world-space content rectangle): pick the largest clamped zoom at which it fits inside the canvas with padding CSS pixels of margin on every side, and centre it. A zero-area canvas or bounds is a no-op.
  • onChange(listener: ViewportChangeListener): Unsubscribe — Subscribe to camera changes. Returns an unsubscribe function.
  • dispose(): void — Drop all subscribers.

Interfaces

CanvasRect

The subset of DOMRect the camera actually needs. Any getBoundingClientRect() result satisfies it; tests can pass a plain object. Keeping it structural is what lets this class run in Node with no DOM.

ts
interface CanvasRect

Properties

NameTypeDefaultDescription
leftnumber
topnumber
widthnumber
heightnumber

CanvasSizeOptions

How {@link ViewportController.setCanvasSize} places the camera on a size change.

ts
interface CanvasSizeOptions

Properties

NameTypeDefaultDescription
anchor?'origin' | 'center''origin' (default) keeps the camera's x/y. 'center' keeps the world point at the canvas centre — what a picture drawn with preserveAspectRatio="xMidYMid meet" (an adopted server svg before the first resize) showed.

ViewportControllerOptions

ts
interface ViewportControllerOptions

Properties

NameTypeDefaultDescription
viewport?RectangleCamera rectangle. x/y are WORLD coordinates; width/height are the canvas's CSS-PIXEL dimensions (see the coordinate contract below).
zoom?number
minZoom?numberDefault 0.1 — matches DiagramCanvasComponent.minZoom.
maxZoom?numberDefault 3.0 — matches DiagramCanvasComponent.maxZoom.
zoomSensitivity?numberAdditive step applied per wheel notch. Default 0.1.

ViewportPoint

A point in world space. Declared structurally (rather than imported from @grafloria/engine) so the viewport module stays dependency-free: camera math needs no diagram model. Structurally identical to Point from @grafloria/engine, so the two interoperate without conversion.

ts
interface ViewportPoint

Properties

NameTypeDefaultDescription
xnumber
ynumber

ViewportState

Immutable snapshot of the camera.

ts
interface ViewportState

Properties

NameTypeDefaultDescription
viewportRectangle
zoomnumber

Types

Unsubscribe

Remove a previously registered listener.

ts
type Unsubscribe = () => void;

ViewportChangeListener

ts
type ViewportChangeListener = (state: ViewportState) => void;

Was this page helpful?

Viewport — Grafloria