Skip to main content

Module writeback

pdfluent_forms

Module writeback 

Source
Expand description

Single reliable AcroForm value writeback (D-chain).

apply_field_value is the one SDK-level operation for setting a form value on a lopdf::Document. It owns the complete chain the PDF spec and the reference implementations (pdfium, mupdf, pdf.js) require:

  1. /V — text values via the ASCII-literal-else-UTF-16BE+BOM policy (ISO 32000-1 §7.9.2.2); button values as byte-exact /Name objects (§12.7.4.2.3).
  2. /AS — kept consistent with /V on every widget of a button field: a widget’s /AS becomes the on-state iff that name is a key of the widget’s own /AP /N sub-dictionary, else /Off (the mupdf set_check_grp rule).
  3. /AP — text and choice widgets get a regenerated /AP /N Form XObject (/Tx BMC … EMC, WinAnsi-encoded show text, AFM-measured positioning, comb/multiline/quadding support) so the fill is visible in every viewer without /NeedAppearances processing.
  4. /NeedAppearances — set true only as a fallback when appearance generation is not trustworthy (value not WinAnsi-representable); the stale /AP /N is removed in that case so no viewer shows the old value. PDF 2.0 deprecates NeedAppearances, so the primary path never sets it.

Field lookup accepts fully-qualified names (parent.kid) and recurses through /Kids, unlike the historical top-level-only paths. Read-only fields (/Ff bit 1, inherited) are rejected — note this is stricter than pdfium/mupdf, which only enforce read-only in their UI layers; an SDK has no UI layer, so set-time enforcement is the only place the contract can live.

Structs§

WriteOutcome
What apply_field_value did, for callers that report or log.

Enums§

WriteValue
The value to write, by field family.
WritebackError
Errors surfaced by apply_field_value.

Functions§

apply_choice_multi
Set multiple selected values on a multi-select list box (/Ff bit 22).
apply_field_value
Set a form field value, updating /V, /AS, /AP and (only as an encoding fallback) /NeedAppearances. See the module docs for the chain.
regenerate_appearances
Regenerate /AP /N for every filled text/choice field in the document.