Grids and snapping

DrawingGridConfiguration configures one grid interval shared by rendering and snapping. Visibility and snapping are independent. DiagramGridPattern controls appearance without changing that interval.

DrawingGridConfiguration

DrawingGridConfiguration({
  bool visible = false,
  bool snap = false,
  double size = 20,
  DiagramGridPattern pattern = DiagramGridPattern.layered,
})

DrawingGridConfiguration copyWith({
  bool? visible,
  bool? snap,
  double? size,
  DiagramGridPattern? pattern,
})

Property	Type	Default	Contract
visible	bool	false	Paint the grid. Does not enable snapping.
snap	bool	false	Enable grid snapping. Does not require a visible grid.
size	double	20	World-space interval, normalized on construction and copyWith.
pattern	DiagramGridPattern	DiagramGridPattern.layered	Immutable composition of paint layers.

copyWith returns a new configuration; omitted or null arguments preserve existing values. All four properties are final.

Size normalization

The implementation uses DiagramEditorSettings.normalizeGridSize(double value) and exposes these constants:

Constant	Type	Value
minimumGridSize	double	4
maximumGridSize	double	128
gridSizeStep	double	4

Finite inputs are divided by 4, rounded with Dart's round(), multiplied by 4, and clamped to [4, 128]. Non-finite inputs become 20; negative or zero finite inputs become 4. Normalization does not throw for those values.

DiagramGridPattern

factory DiagramGridPattern({
  required String id,
  required String label,
  required Iterable<DiagramGridLayer> layers,
})

Property	Type	Requirement
id	String	Nonempty after trimming and no leading/trailing whitespace.
label	String	Nonempty after trimming.
layers	List<DiagramGridLayer>	Unmodifiable copy containing 1–16 layers.

Patterns compare by id, label, and ordered layer values, with a matching hashCode.

Static value	ID / label	Layers
DiagramGridPattern.dots	dots / Dots	One default DiagramDotGridLayer.
DiagramGridPattern.lines	lines / Lines	One default DiagramLineGridLayer.
DiagramGridPattern.layered	layered / Layered	Lines at interval 1, color 0xB8E5E5E5; lines at interval 5, color 0x9ED4D4D4.
DiagramGridPattern.presets	—	Constant list [dots, lines, layered].

Grid layers

DiagramGridLayer is sealed. Its concrete productions are dots, lines, and crosses:

const DiagramDotGridLayer({
  int spacingMultiple = 1,
  DiagramColor color = const DiagramColor(0xFFCDD5E4),
  double size = 2,
})
const DiagramLineGridLayer({
  int spacingMultiple = 1,
  DiagramColor color = const DiagramColor(0xFFCDD5E4),
  double size = 1,
})
const DiagramCrossGridLayer({
  int spacingMultiple = 1,
  DiagramColor color = const DiagramColor(0xFFCDD5E4),
  double size = 3,
})

Property	Type	Default	Meaning / accepted range in a pattern
spacingMultiple	int	1	Multiplies the shared world interval; 1–1024.
color	DiagramColor	DiagramColor(0xFFCDD5E4)	ARGB integer from 0 through 0xFFFFFFFF.
size	double	Dot: 2; line: 1; cross: 3	Screen-space dot diameter, line stroke width, or cross arm length. Must be finite, > 0, and <= 32.

Layer values compare by concrete type and all three properties. Validation occurs when constructing DiagramGridPattern, which throws ArgumentError for invalid identity, label, layer count, spacing, size, or color. Layer constructors themselves do not perform this pattern validation.

Example

final pattern = DiagramGridPattern(
  id: 'cross-and-major-lines',
  label: 'Crosses and major lines',
  layers: const [
    DiagramCrossGridLayer(size: 3),
    DiagramLineGridLayer(
      spacingMultiple: 5,
      color: DiagramColor(0x99CDD5E4),
    ),
  ],
);

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

See custom grid patterns for a canvas example. Rotation snapping uses DrawingConfiguration.rotationSnapDegrees rather than the grid configuration.