API reference / Common / Engine types / FormObject

Interface: FormObject

A reference to a Form — a PDF Do invocation site.

The owning [GraphicsObject] carries the invocation-site transform, clips, and visibility. The body lives in the shared Form definition: the importer expands each Do, then register_form dedups the result, so every Do of the same XObject that expands to the same (bbox, matrix, /Group, body) collapses onto one Form reused across pages. Editing that body affects every invocation.

This is a compositing scope over a (shared) flattened body, not a paint leaf — so it does not carry nonstroking_style / render_style like [PathObject] / [ShadingObject] do. Instead soft_mask, alpha, and blend_mode are the per-invocation compositing triple — the model mirror of render-side LayerOptions{ alpha, blend_mode, mask }. They live on the invocation, not the body, because the body is shared: a value that differs between Do sites can't be baked into a body other invocations reuse. Every other Do-site gs parameter (color, line, text, OPM, RI) is baked into the body's leaves during expansion — self-contained, directly editable, at the cost of forking the body per distinct gs.

Whether the group compositing is meaningful depends on the form's transparency_group:

• Plain form (None) — inlined per PDF §8.10, so ca/CA/BM are baked into the leaves too and alpha / blend_mode here stay at their defaults (1.0 / [BlendMode::Normal]).
• Transparency group (Some) — composited as a unit (§11.6.6): the group's ca / BM ride on alpha / blend_mode and apply once to the composited group, and the body is expanded with ca/CA/BM/SMask reset (§11.4.7.2) instead of folded per leaf. That both stops overlaps double-darkening and lets two Do sites differing only in ca/BM share one body — folding them in would fork the Form and double-darken.

To diverge one invocation from its definition, the editor runs a detach operation that clones the body into a new Form and re-points the invocation — both kept consistent without re-running any PDF interpreter.

Properties

Property	Description
form string	-
softMask string | null	-
alpha number	Group constant alpha — the non-stroking ca in effect at the Do, applied once to a transparency group's composited result. 1.0 for plain forms (whose ca is baked into the body leaves instead).
blendMode BlendMode	Group blend mode — the BM in effect at the Do, applied to a transparency group's composited result. [BlendMode::Normal] for plain forms (whose BM is baked into the body leaves instead).