Design Grids

Wing/line updates and structural line edits on a grid — the entity-family home for grid-specific operations (like design.doors). Accessed via snaptrude.design.grids.

Lines are addressed positionally as { wing, line } index pairs into the wings arrays returned by design.query.grids.get. Adding, removing, or re-counting lines re-indexes the affected wing — re-query after every structural edit.

Related surfaces: creation on design.create.grid / gridFromCurve / gridsFromMasses / columnsFromGrids, group-level edits (styling, angle, storey visibility) on design.update.grid, reads on design.query.listGrids / grids.get. Whole grids also work with the generic families: transform.move/rotate, visibility.hide/show, lock/unlock, delete.entities, and selection (transform.align and transform.mirror are not supported for grids and throw OPERATION_FAILED).

Types

PluginGridLineTagPolicy

Tag policy for line removal (mirrors the engine values verbatim).

Value	Behavior
"rewrite"	Each affected wing renumbers its tag sequence after removal (default)
"preserve"	Surviving lines keep their tags unchanged

PluginGridLineAddress

Property	Type	Description
wing	number	Wing index (into grids.get's wings)
line	number	Line index within the wing

Functions

updateWings(grid, wings)

Update one or more wings with sparse per-wing entries — the exact setters the native panel uses; each changed field commits its own undoable command, identical to editing that field in the panel.

• Parameters:
  • grid: ComponentHandle — The grid group
  • wings: Array<{ wing: number; spacing?: number; count?: number; spanMin?: number; spanMax?: number }> — spacing re-spaces uniformly; count grows/truncates and renumbers tags (re-indexes lines — re-query afterwards); spanMin/spanMax move the family length handles (Snaptrude units)
• Returns: true once applied

await snaptrude.design.grids.updateWings(grid, [{ wing: 0, spacing: 8, count: 10 }]);

updateLines(grid, lines)

Update one or more lines with sparse per-line entries — the exact setters the native drilled-line panel uses; each changed field commits its own undoable command.

• Parameters:
  • grid: ComponentHandle — The grid group
  • lines: Array<{ wing: number; line: number; tag?: string; distanceToPrevious?: number; distanceToNext?: number; props?: PluginGridStyleOptions; visible?: false }> — the two distances set the typed distance to the neighbour on that side and are mutually exclusive per entry; props are per-line style overrides
• Returns: true once applied

visible is hide-only (false), mirroring the product — per-line show does not exist. Hiding lines that would leave no visible line hides the whole group instead (the native last-line rule; the line flags stay untouched). To bring hidden lines back, show the group (design.visibility.show([grid])) — it restores all of its lines, exactly like the native Show All.

await snaptrude.design.grids.updateLines(grid, [
  { wing: 0, line: 1, tag: "B", distanceToPrevious: 4 }
]);

addLine(grid, wing, position)

Insert a parallel grid line into a wing at an explicit position along the wing's spacing axis (Snaptrude units, wing-local). Sibling lines do not shift; the wing's tag sequence renumbers. Undoable.

• Parameters:
  • grid: ComponentHandle — The grid group
  • wing: number — Wing index
  • position: number — Position along the wing's spacing axis (Snaptrude units)
• Returns: true once inserted

await snaptrude.design.grids.addLine(grid, 0, 12.5);

removeLines(grid, lines, tagPolicy?)

Remove grid lines by positional address, as one undoable step. A wing emptied of lines is dropped from the group. Removing EVERY line of the group is rejected — delete the group instead (design.delete.entities).

• Parameters:
  • grid: ComponentHandle — The grid group
  • lines: PluginGridLineAddress[] — Addresses to remove
  • tagPolicy: PluginGridLineTagPolicy (optional, default "rewrite")
• Returns: true once removed

await snaptrude.design.grids.removeLines(grid, [{ wing: 0, line: 2 }], "preserve");

Errors

Failed calls reject with a typed PluginError — see Error Handling.

Code	Thrown by	When	details
VALIDATION	all methods	Bad args: empty entry arrays, non-finite values, out-of-range wing/line addresses, both distances on one updateLines entry, a distance with no neighbour on that side or exceeding available space, an invalid tag	—
HANDLE_INVALID	all methods	The id is unknown or does not belong to a grid group	—
PRECONDITION_FAILED	all methods	The grid is locked	handles — the grid id
OPERATION_FAILED	removeLines	The removal would delete the group's last line — delete the whole grid instead	handles — the grid id