API reference / Common / Engine types / Form

Interface: Form

A self-contained, editable graphics-object body shared by every GraphicsObject whose content is a FormObject pointing at this definition.

Form is the model's analogue of a PDF Form XObject — but with one critical difference: a single PDF Form XObject can produce one or more Forms in the model, depending on how its per-invocation expansion fares under each invocation context. State inheritance can structurally change a form's expansion (PDF text-rendering mode 7 makes Tj produce a clip instead of paint), so the loader deduplicates expansions structurally: invocations that produce the same body share a Form; invocations whose expansion diverges structurally each get their own.

Once built, a Form.body is self-contained: it has no parametric dependence on use site, and its graphics objects' fields are directly editable. Edits propagate to every invocation referencing this definition.

Form is also the canonical content of Pattern and SoftMask resources — both reference a FormId.

Properties

Property	Description
id string	-
bbox Rect	Bounding box in the form's own coordinate space (top-left origin, y-down — the udoc convention).
matrix Affine	The form's own matrix, applied when the form is invoked. The invocation's transform composes on top of this.
body GraphicsObject[]	The form's content. Graphics objects here have stable GraphicsObjectIds and are addressable for editing.
transparencyGroup TransparencyGroup | null	PDF /Group attribute on the Form XObject. Some(_) means the form is a transparency group — its body is rendered into an isolated buffer and composited as a unit when invoked. None means the body composites directly onto the invocation backdrop.
optionalContent OptionalContent | null	PDF /OC on the Form XObject (Table 93) — the optional content deciding whether the form shows. Hidden, every invocation is skipped as if there were no Do.