PdfFormState
The live values of a document's form fields, while the reader has it open.
A file's own values are what PdfFormField.value reports, and they never change. This holds what the form looks like now: what the reader typed, what a script wrote, which box is ticked. A viewer draws from it, a script reads and writes it, and io.github.yuroyami.kitepdf.writer.PdfEditor saves it.
Nothing here touches the file. Saving is a separate step, so a reader can fill a form, change its mind, and close without writing anything.
val state = PdfFormState(doc)
state.setValue("total", "42")
state.value("total") // "42"
doc.formField("total")?.value // still what the file saysA viewer keeps one for as long as the document is open, and reads revision to know when to redraw. Reads and writes are safe from two threads, because a document's scripts run on a thread of their own while the viewer draws on its own: the engine that runs the scripts is confined to one thread, but the values it writes are read by another.
Types
Properties
Functions
Cancels a pending choice edit only while its expectedRevision is still current. This advances the field revision without changing its value or requesting a redraw, so an Escape during validation can prevent the eventual store (ISO 32000-1, 12.6.3 and 12.7.4.4). If the edit already committed or another change intervened, returns false and leaves that newer state intact.
The complete live choice value, falling back to the unchanged source file.
Changes and reset requests for this field alone; useful for discarding a stale edit.
Whether the reader may change the field: the file's own flag, unless this state says otherwise.
Performs a reset-form action: the fields it names, by name or by reference, or every field but those when its Include/Exclude flag is set, or every field when it names none. See the other resetForm.
Gives each selected field its default value (/DV) back, or no value when it has none, as a reset-form action and a script's resetForm do (ISO 32000-1, 12.7.5.3). A name selects that field and every field below it, so address selects address.street. With exclude, every field that the names do not select is reset instead. With no names at all, every field is reset. A push button and a signature keep theirs, and visibility and read-only changes stay (#439).
Stores one validated selection and publishes one revision. Returns false for a missing field or an invalid value. Programmatic writes, like setValue, may update read-only fields. A user transaction should use the overload with an expected field revision.
Commits only if the field has not changed since expectedRevision and remains visible and writable. The revision check and update share one lock, so a late script cannot replace a newer choice or one whose flags changed while the script ran. This overload can also restore the exact parsed source or default selection, including unresolved source values, when an editor cancels an edit. Arbitrary unresolved values remain invalid; user commits should first call PdfFormField.validateChoiceSelection.
Makes the field read-only, or gives it back to the reader.
Captures the accepted values, choice selections and field flags at one instant. A renderer can keep this copy through a suspended or repeated draw, so a script cannot change the form halfway through constructing its appearances (ISO 32000-1, 12.7.3.3). All state and revision counters are copied together under the same lock.
The live scalar value, or the file's own value. For choices this is a lossy view: the first selected export in option order, never a joined list. Use choiceSelection for multiple selections and to distinguish an empty selection from an empty export.