Detect and fill existing AcroForm fields

[McanKul]

Goal

Allow offline filling of existing interactive PDF forms.

Scope

• Detect and list AcroForm text fields, checkboxes, radio buttons, combo boxes and list boxes.
• Overlay interactive controls at field positions in the preview.
• Write field values and regenerate/update appearance streams.
• Provide Save interactive and Save flattened output modes.
• Explain unsupported XFA forms clearly instead of silently failing.

Out of scope

• Creating new form fields.
• JavaScript actions and complex validation/calculation scripts.
• Digital certificate signatures.

Acceptance criteria

• Field values display correctly after reopening in at least two common PDF viewers.
• Unicode/Turkish text is handled or rejected with a specific actionable error.
• Checkbox/radio export values are respected.
• Hidden/read-only fields are not accidentally changed.
• Existing unrelated annotations and document structure are preserved.
• Tests include direct/indirect fields, inherited attributes, missing appearances and malformed form trees.

Technical note

qpdf appearance generation is intentionally limited for simple forms, so the implementation must validate output rather than assuming that changing the field value is sufficient.