PdfFormField
One terminal interactive-form field (ISO 32000-1 §12.7.3), flattened from the AcroForm field tree with inheritable attributes (/FT, /DA, /Ff, /V, /Q) resolved down from ancestors.
A field and its single widget annotation are frequently merged into one dictionary; when they are separate (e.g. one logical field with widgets on several pages) fieldReference and widgetReference differ. The writer's form-fill uses these references plus rect (the widget's /Rect) to set the value and regenerate the appearance.
Types
Properties
The scripts of the field's first widget, or of the field itself when the two are merged. Each button of a radio group has scripts of its own: read those from widgets.
The original /Opt indices, exports and labels (ISO 32000-1, 12.7.4.4).
Height of one displayed choice row in PDF points, using /DA (ISO 32000-1, 12.7.3.3).
The complete source /V, with /I resolving duplicate exports when consistent.
/Ff bit 27 commits a selection change immediately (ISO 32000-1, Table 230).
Variable-text default appearance string (/DA), inherited if absent.
The complete reset value /DV, or an empty selection (ISO 32000-1, 12.7.3.1).
The value the field goes back to when the form is reset (/DV), or null when it has none.
Indirect reference to the field dictionary, for editing.
Fully-qualified name: ancestor partial names joined by '.'.
/Ff bit 19 is meaningful only for a combo (ISO 32000-1, Table 230).
/Ff bit 13 (text fields): multi-line.
/Ff bit 22 allows several selected list options (ISO 32000-1, Table 230).
/Ff bit 1: the field is read-only.
/Ff bit 26 (text fields): the value is rich text, XHTML kept in /RV next to the plain value in value (ISO 32000-1, 12.7.3.4).
The choices of a list box or a combo box, in the order the file lists them (/Opt, ISO 32000-1 §12.7.4.4). This legacy label view omits malformed entries; use choiceOptions to retain original option indices and export values.
This field's own /T, or null for an anonymous node.
The first widget's /Rect, or null when this terminal field has no widget.
/V as text; for choices, the first selected export value. Use choiceSelection for all values.
Indirect reference to the widget annotation (== fieldReference when merged).
Every widget annotation this field owns, in the order the field declares them. One field may be shown in several places: a radio group has one widget per button, and a field may repeat on several pages (ISO 32000-1 §12.7.3.1). The first entry is the one rect, widgetReference and widgetDict describe.
Functions
Content inset of a choice widget in PDF points, accounting for its own border.
Adapts a scalar export value to one option, choosing the first duplicate export. Empty text clears a noneditable field only when it has no empty export option. Other unmatched values are valid only for an editable combo (ISO 32000-1, 12.7.4.4).
Original option index at the top of the displayed list. Starts at /TI and moves to the first selected row if no selected row is visible, so drawing and pointer hit tests use the same viewport. Returns zero when no usable options remain.
Export values in option order, followed by unresolved source strings; text stays scalar.
Validates a new selection and sorts its indices in original option order. Duplicate, unavailable or disallowed indices, mixed text/indices and unresolved source values are refused with null. An empty selection is valid (ISO 32000-1, 12.7.4.4).