DrawingConfiguration

DrawingConfiguration is the immutable behavior, presentation, and host integration configuration for a DrawingSession.

Constructor

DrawingConfiguration({
  List<DiagramEditorExtension> extensions = const [],
  DiagramPathEffectRegistry? pathEffects,
  CanvasPolicy canvasPolicy = const InfiniteCanvasPolicy(),
  DrawingGridConfiguration? grid,
  double rotationSnapDegrees = 15,
  DiagramLodPolicy lodPolicy = const DiagramLodPolicy(),
  Color backgroundColor = const Color(0xFFFAFAFA),
  DrawingHooks hooks = const DrawingHooks(),
  DiagramImageSourcePicker imageSourcePicker = pickDiagramImageSource,
})

Properties

All stored properties are final. Nullable constructor inputs for grid and pathEffects become non-null properties.

Property	Type	Default	Contract
extensions	List<DiagramEditorExtension>	Empty list	Copied into an unmodifiable list; IDs must be nonempty and unique.
pathEffects	DiagramPathEffectRegistry	DiagramPathEffectRegistry.standard	Registry used for transient connector path effects.
canvasPolicy	CanvasPolicy	const InfiniteCanvasPolicy()	Selects infinite or finite world navigation.
grid	DrawingGridConfiguration	DrawingGridConfiguration()	Visibility, snapping, spacing, and pattern; see grids.
rotationSnapDegrees	double	15	Finite angle increment, greater than 0 and at most 360.
lodPolicy	DiagramLodPolicy	const DiagramLodPolicy()	Full visual detail by default; adaptive detail is opt-in.
backgroundColor	Color	Color(0xFFFAFAFA)	Flutter canvas background color.
hooks	DrawingHooks	const DrawingHooks()	Admission, completed-change, region, and connection callbacks; see hooks.
imageSourcePicker	DiagramImageSourcePicker	pickDiagramImageSource	Image picker callback supplied at construction.
finiteCanvas	bool getter	Derived	true when canvasPolicy is FiniteCanvasPolicy.

DiagramImageSourcePicker is Future<DiagramImageSource?> Function(); returning null cancels image selection.

copyWith

DrawingConfiguration copyWith({
  List<DiagramEditorExtension>? extensions,
  DiagramPathEffectRegistry? pathEffects,
  CanvasPolicy? canvasPolicy,
  DrawingGridConfiguration? grid,
  double? rotationSnapDegrees,
  DiagramLodPolicy? lodPolicy,
  Color? backgroundColor,
  DrawingHooks? hooks,
  DiagramImageSourcePicker? imageSourcePicker,
})

Returns a new configuration. Omitted or null arguments preserve their current values. Constructor validation runs again. Supply imageSourcePicker to replace the picker through the same configuration update path; omit it to preserve the current callback.

Failure	Result
Non-finite rotation increment, <= 0, or > 360	ArgumentError
Empty/whitespace-only extension ID or duplicate ID	ArgumentError

Canvas policies

const InfiniteCanvasPolicy()
const FiniteCanvasPolicy(DiagramRect worldBounds, {double viewportPadding = 0})

Class / property	Type	Default	Meaning
InfiniteCanvasPolicy	CanvasPolicy	Outer configuration default	No finite world boundary.
FiniteCanvasPolicy.worldBounds	DiagramRect	Required positional argument	Finite world boundary.
FiniteCanvasPolicy.viewportPadding	double	0	Screen-space breathing room around the boundary; constructor asserts >= 0.

DiagramLodPolicy

const DiagramLodPolicy({
  bool adaptive = false,
  double compactBelowPixels = 32,
  double thumbnailBelowPixels = 10,
})

DiagramVisualDetail detailFor({
  required double projectedMinimumDimension,
  required bool interactionCritical,
})

Property	Type	Default	Meaning
adaptive	bool	false	Enables projected-size-based visual detail.
compactBelowPixels	double	32	Compact threshold, in projected pixels.
thumbnailBelowPixels	double	10	Thumbnail threshold, in projected pixels.

detailFor returns DiagramVisualDetail.full when adaptation is disabled or the element is interaction-critical. Otherwise it returns thumbnail below the thumbnail threshold, compact below the compact threshold, and full at or above both thresholds. Threshold comparisons are strict <.

Applying configuration

final session = DrawingSession(
  document: DiagramDocument.empty('my-drawing'),
  shapeRegistry: ShapeRegistry.standard(),
  tools: DiagramToolRegistry.standard(),
  configuration: DrawingConfiguration(
    grid: DrawingGridConfiguration(visible: true, snap: true, size: 20),
    extensions: [const DiagramMinimapExtension()],
  ),
);

session.setConfiguration(session.configuration.copyWith(
  grid: session.configuration.grid.copyWith(size: 24),
));

// Mount inside a bounded Flutter layout.
DrawingCanvas(session: session);

setConfiguration preserves document history. The session projects toolbar and inspector setting changes back into session.configuration, so hosts can read the current settings from that property. Shape and tool registries are constructor inputs to the session, not configuration fields; there is no live registry replacement method. A session borrowed with DrawingSession.fromStore retains the store's admission hook; see session lifetime and errors.