Struct Field 

pub struct Field {
    pub dict: Dict,
    pub reference: Option<ObjRef>,
    pub name: String,
    pub kind: FieldKind,
    pub flags: FieldFlags,
    pub widgets: Vec<Widget>,
}

One terminal form field.

A record of where the field is — the dictionary, the reference that names it, its widgets — plus the classification derived once at load. What it currently holds is read back through Field::value, because a FieldValues edit may have superseded the file’s own /V.

Fields

dict: Dict

The field’s own dictionary.

reference: Option<ObjRef>

The reference that names it, when it has one. A field written inline in its parent’s /Kids has none, and cannot be written back.

name: String

The fully-qualified name: the ancestors’ /T values and its own, joined with dots.

kind: FieldKind

What kind of control it is.

flags: FieldFlags

The /Ff flag word, read through the inheritance chain.

widgets: Vec<Widget>

The widget annotations that draw it.

Usually one. A radio group has one per button, and a field whose dictionary is its widget has one that is the field itself.

Implementations

impl Field

pub fn value<R: Resolve>(&self, values: Option<&FieldValues>, r: &R) -> String

The field’s current value, as text.

values is consulted first, so a field written through FieldValues::set reads back as what was written rather than what the file holds. Pass None to read the file’s own /V.

For a check box or radio button this is the state name — Off for clear, and whatever the widget’s /AP /N calls its on-state otherwise. Use Field::is_checked for the boolean.

use pdfrum_common::{Diagnostics, Limits};
use pdfrum_doc::form::Form;
use pdfrum_object::{Array, Dict, Name, NoResolve, Object, PdfString};

let field = Dict::from_pairs([
    (Name::from("FT"), Object::Name(Name::from("Tx"))),
    (Name::from("T"), Object::Str(PdfString::literal(b"name"))),
    (Name::from("V"), Object::Str(PdfString::literal(b"Ada"))),
]);
let catalog = Dict::from_pairs([(
    Name::from("AcroForm"),
    Object::Dict(Dict::from_pairs([(
        Name::from("Fields"),
        Object::Array(Array::of([Object::Dict(field)])),
    )])),
)]);

let mut diags = Diagnostics::default();
let form = Form::load(&catalog, &NoResolve, &Limits::default(), &mut diags)
    .expect("the catalog declares an /AcroForm");
use pdfrum_doc::form::FieldValues;

let field = form.field("name").expect("one terminal field");
assert_eq!(field.value(None, &NoResolve), "Ada");

// An edit supersedes the file's own `/V`.
let mut values = FieldValues::new();
values.set("name", "Grace");
assert_eq!(field.value(Some(&values), &NoResolve), "Grace");

pub fn stored_value<R: Resolve>(&self, r: &R) -> String

The value the file holds, ignoring any edit.

use pdfrum_common::{Diagnostics, Limits};
use pdfrum_doc::form::Form;
use pdfrum_object::{Array, Dict, Name, NoResolve, Object, PdfString};

let field = Dict::from_pairs([
    (Name::from("FT"), Object::Name(Name::from("Tx"))),
    (Name::from("T"), Object::Str(PdfString::literal(b"name"))),
    (Name::from("V"), Object::Str(PdfString::literal(b"Ada"))),
]);
let catalog = Dict::from_pairs([(
    Name::from("AcroForm"),
    Object::Dict(Dict::from_pairs([(
        Name::from("Fields"),
        Object::Array(Array::of([Object::Dict(field)])),
    )])),
)]);

let mut diags = Diagnostics::default();
let form = Form::load(&catalog, &NoResolve, &Limits::default(), &mut diags)
    .expect("the catalog declares an /AcroForm");

let field = form.field("name").expect("one terminal field");
assert_eq!(field.stored_value(&NoResolve), "Ada");

pub fn default_value<R: Resolve>(&self, r: &R) -> String

The field’s default value (/DV) — what a form reset restores.

pub fn is_checked<R: Resolve>( &self, values: Option<&FieldValues>, r: &R, ) -> bool

Whether a check box or radio button is on.

Always false for a field that is not a toggle. A state of Off, and an absent state, both read as clear — every other name is on, which is the spec’s own rule.

pub fn states<R: Resolve>(&self, r: &R) -> Vec<String>

The states a check box or radio button can take, from its widgets’ /AP /N sub-dictionaries.

Off is included when a widget offers it. The order is the widgets’ order, then each widget’s own appearance-dictionary order.

pub fn options<R: Resolve>(&self, r: &R) -> Vec<String>

A choice field’s selectable options (/Opt).

An entry written as a two-element array is an export-value/label pair; the label is what a reader shows, and that is what comes back here.

pub fn tooltip<R: Resolve>(&self, r: &R) -> Option<String>

The field’s user-facing tooltip (/TU), when it has one.

Trait Implementations

impl Clone for Field

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Field

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Field

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Field