PdfElixide.Form.Field (pdf_elixide v0.13.0)

Copy Markdown View Source

A single AcroForm field, one struct per field type this API covers:

Obtained from PdfElixide.Form.fields/1, or one at a time from PdfElixide.Form.field/2.

Every struct carries :name — the fully qualified, dotted name ("person.first", not "first") that PdfElixide.Form.field/2, PdfElixide.Form.value/2 and PdfElixide.Form.put_value/3 address it by, identical whether the form was read from a PdfElixide.Document or a PdfElixide.Editor — :value, a plain term (value/0) — and :flags, the decoded /Ff bits its type can carry.

The first three also carry a :kind, naming the widget the type covers — each struct's t:kind/0 lists its own. Unknown has none, having no type whose bits would say.

A parent that carries a name but declares no type is itself reported as a field, so a nested form yields a struct for the grouping level as well as for each leaf under it.

The "Field kinds and flags" section of the Forms guide covers both in full.

Summary

Types

t()

Any form field.

value()

A field's value as a plain term: a string, a boolean, a list of strings, or nil for a field carrying no value.

Types

t()

@type t() ::
  PdfElixide.Form.Field.Text.t()
  | PdfElixide.Form.Field.Button.t()
  | PdfElixide.Form.Field.Choice.t()
  | PdfElixide.Form.Field.Unknown.t()

Any form field.

value()

@type value() :: String.t() | boolean() | [String.t()] | nil

A field's value as a plain term: a string, a boolean, a list of strings, or nil for a field carrying no value.

This is both what a field reports and exactly what PdfElixide.Form.put_value/3 accepts — anything else raises ArgumentError — so a value read from one form can be written straight into another.

Button fields are the exception, and writing one back is not always faithful — see the Forms guide before round-tripping a PdfElixide.Form.Field.Button.

Each struct's moduledoc describes the subset a well-formed PDF can put on its kind; a malformed /V whose PDF type is foreign to the field's kind (say, an array on a text field) is passed through as the corresponding plain term rather than dropped, so any of these shapes can in principle appear on any struct.