DrawingSession

DrawingSession owns the host-facing connection to one canonical DiagramStore. Content commands work without a canvas; camera and visual-effect commands use the mounted DrawingCanvas.

Constructors

DrawingSession({
  required DiagramDocument document,
  DrawingConfiguration? configuration,
  ShapeRegistry? shapeRegistry,
  DiagramTextLayoutEngine? textLayout,
  DiagramToolRegistry? tools,
  DiagramShapeCreationPolicy? shapeCreationPolicy,
  DiagramConnectionPolicy? connectionPolicy,
  DiagramTool? activeTool,
})

DrawingSession.fromStore(
  DiagramStore store, {
  DrawingConfiguration? configuration,
})

Argument	Type	Default / behavior
document	DiagramDocument	Required for the primary constructor; initial canonical content.
configuration	DrawingConfiguration?	DrawingConfiguration() when omitted.
shapeRegistry	ShapeRegistry?	Resolver uses ShapeRegistry.standard() when omitted.
textLayout	DiagramTextLayoutEngine?	FlutterDiagramTextLayoutEngine() when omitted.
tools	DiagramToolRegistry?	Store uses DiagramToolRegistry.standard() when omitted.
shapeCreationPolicy	DiagramShapeCreationPolicy?	Optional creation policy forwarded to the store.
connectionPolicy	DiagramConnectionPolicy?	Optional connection policy forwarded to the store.
activeTool	DiagramTool?	Explicit value, otherwise supplied tools.defaultTool, otherwise DiagramToolIds.select.
store (fromStore only)	DiagramStore	Required positional argument; adopts the existing state, scene, and history.

fromStore borrows the store. Without explicit configuration it projects the store's settings into a default configuration. With configuration it applies those settings, but retains the owning store's admission hook.

Properties

Property	Type	Meaning
store	DiagramStore	Advanced access to the same canonical engine.
state	DiagramEditorState	Current document, selection, settings, and active tool.
scene	ResolvedScene	Current resolved geometry.
text	DiagramStoryCommands	Story replacement and checklist commands, shared with the canvas editor and headless store.
configuration	DrawingConfiguration	Current host configuration combined with live store settings and admission hook.
canUndo, canRedo	bool	Whether the respective history operation is available.
canAlign, canDistribute, canReorder, canRemoveFrames	bool	Availability for the current selection.
isDisposed	bool	Whether dispose() has completed.
isAttached	bool	Whether a canvas currently claims this session.
cameraState	DiagramCameraState?	Mounted camera state, or null when detached.
pathEffects	DiagramPathEffectRegistry	Current configuration's effect registry.
pathAnimations	Map<String, DiagramPathAnimation>	Active animations keyed by animation ID; empty when detached.

Except for isDisposed and isAttached, these getters require a live session.

Content and configuration methods

Signature	Returns	Behavior
addElement(DiagramElement element, {bool select = true})	DiagramPolicyDecision	Insert an authored record without factory defaults; see shapes.
createShape({required String type, required DiagramPoint worldCenter, ...})	String	Materialize registry defaults and return the new shape ID; full arguments.
createText({required DiagramPoint worldCenter, ...})	String	Create standalone text; full arguments.
dispatch(DiagramTransaction transaction)	DiagramPolicyDecision	Submits one atomic edit through the store's admission pipeline.
replaceDocument(DiagramDocument document, {required int expectedRevision})	DiagramPolicyDecision	Revision-checked replacement; see persistence.
importJson(String json, {required int expectedRevision})	DiagramPolicyDecision	Decodes with DiagramJsonCodec, then performs revision-checked replacement. Decode errors propagate.
undo()	DiagramPolicyDecision	Requests undo through the canonical store.
redo()	DiagramPolicyDecision	Requests redo through the canonical store.
selectElements(Iterable<String> elementIds)	void	Replaces object selection; missing and non-selectable elements are filtered by the admitted scene.
selectAll({String? ownerId})	void	Selects every selectable element, or only direct children of the supplied owner. Includes connectors.
clearSelection()	void	Clears selection. Selection commands are transient, preserve document/scene and create no undo entries; they work before mounting.
canGroup / canUngroup	bool	Checks selection ownership and registered group availability, or removal capability for selected groups. Host admission runs when executing.
groupSelection()	DiagramPolicyDecision	Groups at least two objects with the same owner, using admitted selection bounds. Works without a mounted canvas.
ungroupSelection()	DiagramPolicyDecision	Removes selected group containers while retaining children. Nested removals reparent to the first surviving owner, preserving geometry.
copySelection()	DiagramClipboardPayload	Captures selected objects, owned descendants, and connectors whose two bound targets are included, as an immutable payload. Crossing connectors are excluded unless explicitly selected or owned by a captured container. The host owns clipboard storage.
paste(DiagramClipboardPayload payload, {DiagramPoint offset = const DiagramPoint(24, 24)})	DiagramPolicyDecision	Allocates fresh identities and inserts through admission as one undo unit. Selects copied selection identities on success.
duplicateSelection({DiagramPoint offset = const DiagramPoint(24, 24)})	DiagramPolicyDecision	Copies and pastes selected objects without changing the host clipboard.
setElementsLocked(Iterable<String> ids, bool locked)	DiagramPolicyDecision	Locks or unlocks existing objects in one admitted history operation. Missing IDs deny the complete command. Locked owners protect descendants.
canDeleteSelection	bool	Checks deletion capabilities for selected objects and their dependants, or the selected connector label. Host admission runs when executing the edit.
deleteSelection()	DiagramPolicyDecision	Deletes selected objects or a selected connector label through the engine. Does not delete text-editing content.
removeElements(Iterable<String> elementIds)	DiagramPolicyDecision	Removes objects, descendants and attached connectors as one undo unit. A missing requested ID or protected descendant denies the entire operation. Works without a mounted canvas.
createConnectedShape(DiagramConnectedShapeCreation creation)	DiagramConnectedShapeResult	Creates a shape and its incoming connection together.
setActiveTool(DiagramTool tool)	void	Selects an active tool through the store.
setConfiguration(DrawingConfiguration value)	void	Applies behavior and presentation settings without replacing document history.
align(DiagramAlignment alignment)	DiagramPolicyDecision	Aligns the selection through store.arrangement.
distribute(DiagramDistribution distribution)	DiagramPolicyDecision	Distributes the selection through store.arrangement.
reorder(DiagramLayerOrder order)	DiagramPolicyDecision	Changes selection stacking through store.arrangement.
removeFrames()	DiagramPolicyDecision	Removes selected frame containers through store.arrangement.

The facade forwards engine command validation and policy results; it does not create a second mutation path. Use the corresponding can… getter to enable arrangement controls.

PNG export

Future<DiagramPngSnapshot> exportPng(
  DiagramPngOptions options, {
  ImageProvider<Object> Function(DiagramImageSource)? imageProvider,
})

Captures the current publication and exports it asynchronously. options is required; imageProvider optionally supplies Flutter image providers. A mounted canvas is not required. Once started, an export survives later edits or session disposal. See persistence and export for output options.

Listeners

Signature	Returns	Contract
addListener(DiagramStateListener listener)	void	Observes canonical state. Duplicate registration through the session is ignored.
removeListener(DiagramStateListener listener)	void	Removes a registration made through this session; safe after disposal.
addPresentationListener(VoidCallback listener)	void	Observes transient camera and path-animation changes separately from content.
removePresentationListener(VoidCallback listener)	void	Removes a presentation listener; no-op after disposal.

DiagramStateListener is void Function(DiagramEditorState state). For completed structured document changes, use configuration.hooks.onChange or advanced store.addDocumentChangeListener(...).

Mounted presentation methods

These methods come from DrawingSessionPresentation and require a mounted canvas.

Signature	Returns	Behavior
screenToWorld(DiagramPoint screenPoint)	DiagramPoint	Converts canvas-local screen coordinates to world coordinates.
globalToWorld(Offset globalPosition)	DiagramPoint	Converts a Flutter global position through the laid-out canvas.
setImageSource(String elementId, DiagramImageSource? source)	void	Sets an image shape's source; null removes it.
navigateToPoint(DiagramPoint point, {double? zoom})	void	Centers on a world point; omitted zoom preserves zoom, supplied zoom is clamped to camera limits.
navigateToRectangle(DiagramRect bounds, {double padding = 48})	void	Fits world bounds with viewport padding.
navigateToElement(String elementId, {double padding = 48})	bool	Fits the element; false if missing.
navigateToRegion(String elementId, String regionId, {double padding = 48})	bool	Fits the shape region's world bounds; false if unresolved.
navigateToSelection({double padding = 48})	bool	Fits selection bounds; false when no bounds are available.
stopViewportAnimation()	void	Cancels the current camera animation.
startPathAnimation(DiagramPathAnimation animation)	bool	Adds/replaces the animation by ID; false for invalid animation, unregistered kind, or missing connector.
stopPathAnimation(String animationId)	bool	Removes the animation; false if the ID is absent.
clearPathAnimations()	void	Removes all active path animations.

Animated navigation

Every method returns Future<bool>. Each has these additional named parameters:

Parameter	Type	Default
duration	Duration	const Duration(milliseconds: 450)
curve	Curve	Curves.easeInOutCubic

Method	Required positional arguments	Other named parameters
animateToPoint	DiagramPoint point	double? zoom
animateToRectangle	DiagramRect bounds	double padding = 48
animateToElement	String elementId	double padding = 48
animateToRegion	String elementId, String regionId	double padding = 48
animateToSelection	None	double padding = 48

The future resolves to true on completion and false for a missing target/selection or cancellation. Starting a new camera animation cancels the previous one. Immediate navigation also cancels the current camera animation. Reduced-motion behavior or a nonpositive duration applies the target immediately and returns true.

Lifetime and errors

Condition	Result
replaceDocument / importJson expected revision differs from the current document revision	DiagramRevisionConflict.
Shape creation is denied by creation, connection, or document-admission policy	StateError.
Requested creation size is non-finite or nonpositive	ArgumentError.
Connected creation specifies an invalid target port, omits a required port, or reuses a connector ID	StateError.
Call a live-session API after disposal	StateError. Listener removal and repeated dispose() remain safe.
Mount a second canvas on the same session	StateError; each simultaneous canvas needs a separate session.
Call a mounted presentation method while detached	StateError.
globalToWorld before the canvas is laid out	StateError.
setImageSource targets a missing shape or a shape without an image region	StateError.
Image source is neither an HTTP(S) URL nor an image data URI	ArgumentError.
Borrowed session supplies a non-null admission hook different from the store's hook	ArgumentError from construction or setConfiguration.
Call dispose() while the canvas is still mounted	StateError; unmount first.

void dispose() removes subscriptions made through the session and disposes its controller and configuration notifier. Borrowed-store listeners belonging to other owners are retained. Unmount/remount before disposal retains document and history; runtime settings and path animations are not document content.

Example

final session = DrawingSession(
  document: DiagramDocument.empty('my-drawing'),
  configuration: DrawingConfiguration(
    grid: DrawingGridConfiguration(visible: true),
  ),
);

void onState(DiagramEditorState state) {
  final document = state.document;
  // Persist with DiagramJsonCodec or update host UI from document.
}
session.addListener(onState);

// Return this widget inside a bounded layout:
final canvas = DrawingCanvas(session: session);

// After the canvas is mounted and laid out:
await session.animateToSelection();

// After removing the canvas from the widget tree:
session.removeListener(onState);
session.dispose();

Advanced operations currently use session.store: connections through store.connections, connector labels through store.connectorLabels, and explicit selection through store.setSelection(...). Serialize session.state.document with DiagramJsonCodec and restore with the matching shape registry. See embedding for Flutter lifecycle integration and capability status for remaining foundations.

Paragraph alignment applies only to ordinary paragraphs. Bulleted lists, numbered lists, and checklists remain left-aligned in their region, including nested items. Markers reserve their measured width plus a half-em gap before the item text.

Clipboard references

copySelection() captures resolved endpoint positions for bound targets outside the copied subgraph. paste() remaps internal parents and targets to fresh identities. External references are retained only when pasting into the same document ID and the referenced element still exists. In another document, or after the original target is deleted, external parents are cleared and external endpoints become free endpoints at their captured visible positions plus the paste offset. Matching element IDs in a different document do not establish a binding.

Document IDs identify document identity; independent documents must use distinct IDs. Direct engine callers of DiagramClipboardPayload.capture(document, ids, scene: scene) must supply the current resolved scene when the selection contains external bound endpoints. Missing or revision-mismatched geometry throws ArgumentError. materialize(nextId: ..., targetDocument: ...) uses the same reference rules; omitting targetDocument creates a detached, portable subgraph. The session supplies both automatically.

Arrangement commands return denial for insufficient selection or protected frame removal, and return the host admission decision for edits. An already-satisfied alignment or distribution succeeds without publishing a document change or adding history. Frame removal unwraps children and requires every selected frame to be deletable.

Disposal and store ownership

session.dispose() closes the store created by that session. Retained store and command references can no longer mutate it or register listeners. Dispose is idempotent; unmount the canvas first. Capture session.store.publication before disposal if you need its immutable document and resolved scene afterwards.

DrawingSession.fromStore(store) borrows the store. Disposing that session removes its subscriptions while leaving the store available to its external owner. A headless owner calls store.dispose() when finished. Store disposal clears subscriptions, host policy callbacks, history and pending gesture/group ownership without emitting another change. Disposal during candidate evaluation or publication notification is rejected before cleanup begins.