Canvas, camera, and grids

Give an idea room to grow, or frame a focused workspace. The document stores the content; the camera and drawing configuration control how you explore it.

Move the viewpoint

Pan and zoom without rewriting shape coordinates. Fit the document or selection, or animate toward an element after the canvas has mounted:

await session.animateToElement(
  elementId,
  duration: const Duration(milliseconds: 500),
  padding: 48,
);

The session also supports animated navigation to points, rectangles, regions, and selections. User navigation interrupts camera animation. Configure an infinite or finite canvas through session.configuration.canvasPolicy. Apply changes with session.setConfiguration(session.configuration.copyWith(canvasPolicy: policy)).

Choose a grid

Grid visibility and snapping are independent configuration options. Showing a grid does not turn snapping on, and snapping can stay enabled while the grid is hidden.

session.setConfiguration(
  session.configuration.copyWith(
    grid: DrawingGridConfiguration(
      visible: true,
      snap: true,
      size: 20,
      pattern: DiagramGridPattern.dots,
    ),
  ),
);

Choose dots, lines, or layered. Layered grids combine fine and major lines. Every pattern uses the same grid spacing as snapping. At distant zoom levels, the painter thins visible grid marks while preserving the snapping interval.

Compose your own pattern

Custom patterns use the same dot, line, and cross productions as the defaults. Colors, screen-space mark sizes, and spacing multiples belong to each layer:

final engineeringGrid = DiagramGridPattern(
  id: 'engineering',
  label: 'Engineering',
  layers: [
    DiagramDotGridLayer(
      color: DiagramColor(0xFFBBC9E8),
      size: 2,
    ),
    DiagramLineGridLayer(
      spacingMultiple: 5,
      color: DiagramColor(0xFF8296C7),
    ),
  ],
);

session.setConfiguration(
  session.configuration.copyWith(
    grid: session.configuration.grid.copyWith(pattern: engineeringGrid),
  ),
);

Patterns are validated, immutable compositions. A custom pattern changes the painted grid, not the document geometry or snapping rules. Arbitrary custom renderer callbacks are not part of this grid contract.

Set the minimap detail policy

The minimap defaults to shape outlines and fills, without connections. It uses resolved shape geometry and clipping; text, handles and detailed editing chrome are omitted.

DiagramMinimapExtension(
  initiallyExpanded: true,
  policy: DiagramMinimapPolicy(
    shapeAppearance: DiagramMinimapShapeAppearance.outlines,
    showConnections: false,
  ),
)

Use outlinesAndFills for colored silhouettes, or opt into showConnections. A policy can provide shapePainterForType for custom registered types. Thumbnail painters receive resolved geometry and must remain deterministic; replacing the policy refreshes external thumbnail inputs. They affect presentation only.

Camera movement reuses a recorded scene picture. Document or policy changes rebuild that picture, so a changed scene still costs work proportional to its shapes. Thousands of shapes are not automatically a constant-cost or 120 fps minimap; measure the representative document and chosen thumbnail policy.

Particle count and size

Count controls the number of particles evenly distributed along a path. It does not shrink their dimensions. Size is the radius for circles and polygons; character particles use a font scale of twice that value. Dash length is eight times size, capped only by total path length, while width sets dash thickness. The configured screen/world scaling policy controls zoom behavior. Dense particles can overlap.