Module forms 

AcroForm interactive-form support (PDF 32000-1 §12.7).

Two responsibilities:

1. Field model (AcroForm) — walks /Root /AcroForm /Fields, resolving the field tree into terminal FormFields with fully-qualified names and inherited attributes (/FT /V /DA /Ff /Q). Each terminal field records its widget-annotation object ids, so a consumer can map a page widget back to the field that owns it.

2. Appearance generation (generate_widget_appearance) — for text and choice fields whose producer left no appearance stream (or set /NeedAppearances), synthesizes a form XObject that draws the field value, honoring the /DA font/size/color, /Q justification, and the multiline / comb flags. The result feeds the interpreter’s annotation painter exactly like a real /AP /N stream.

Buttons (checkbox/radio) keep their producer-supplied /AP states; only the /AS selection is hardened (see the annotation module). Signatures are modelled but never generate an appearance.

Structs

AcroForm

The document’s interactive form.

FormField

A terminal interactive-form field.

GeneratedAppearance

A synthesized appearance stream for a widget the producer left without one (or that /NeedAppearances asks the viewer to regenerate). Mirrors a form XObject: a /BBox, /Matrix, /Resources and a content byte stream.

Enums

FieldKind

The four AcroForm field types (/FT), plus an Unknown catch-all.

FieldValue

A resolved field value (/V).

Constants

FF_COMB

Tx (bit 25): comb formatting — /MaxLen equally-spaced cells.

FF_COMBO

Ch (bit 18): combo box (vs. list box).

FF_MULTILINE

Tx (bit 13): the text field holds multiple lines.

FF_PASSWORD

Tx (bit 14): the value is a password — never rendered.

FF_PUSHBUTTON

Btn (bit 17): push button (no persistent value).

FF_RADIO

Btn (bit 16): radio button (mutually-exclusive set).

FF_READONLY

Common: field is read-only.

Functions

generate_widget_appearance

Build a generated appearance for a widget, or None when nothing should be drawn (button/signature fields, empty/absent values, password fields, or a degenerate rectangle). dr_fonts is the AcroForm /DR /Font dictionary, used to resolve the /DA font name to a concrete font object.