Struct Field

pub struct Field<'a> { /* private fields */ }

Writer for an form field dictionary.

This struct is created by Chunk::form_field.

Implementations

impl<'a> Field<'a>

Permissible on all fields.

pub fn field_type(&mut self, typ: FieldType) -> &mut Self

Write the /FT attribute to set the type of this field.

pub fn parent(&mut self, id: Ref) -> &mut Self

Write the /Parent attribute to set the immediate parent of this field.

pub fn children(&mut self, children: impl IntoIterator<Item = Ref>) -> &mut Self

Write the /Kids attribute to set the immediate children of this field. These references shall refer to other fields, or widget annotations.

pub fn partial_name(&mut self, name: TextStr<'_>) -> &mut Self

Write the /T attribute to set the partial field name.

The fully qualified field name of a field is a path along it’s ancestor’s partial field names separated by periods .. Therefore, a partial field name may not contain a period ..

If two fields have the same parent and no partial field name, then they refer to two representations of the same field and should only differ in properties that specify their visual appearance. In particular, they should have the same /FT, /V and /DV attribute values.

pub fn alternate_name(&mut self, alternate: TextStr<'_>) -> &mut Self

Write the /TU attribute to set the alternative field name. This field name is used in place of the actual field name whenever the field shall be identified in the user interface (such as in error or status messages). This text is also useful when extracting the document’s contents in support of accessibility to users with disabilities or for other purposes. PDF 1.3+.

pub fn mapping_name(&mut self, name: TextStr<'_>) -> &mut Self

Write the /TM attribute to set the mapping field name. This name shall be used when exporting interactive form field data from the document.

pub fn field_flags(&mut self, flags: FieldFlags) -> &mut Self

Write the /Ff attribute to set various characteristics of this field.

pub fn additional_actions(&mut self) -> AdditionalActions<'_>

Start writing the /AA dictionary to set the field’s response to various trigger events.

Note that this attribute is forbidden in PDF/A.

pub fn into_annotation(self) -> Annotation<'a>

Finish writing this field as a widget annotation. This is encouraged for fields which are non-root and terminal (i.e. they have a parent and no children).

While the widget annotation could be a single child to a terminal field, most readers will not correctly read the form field, if it’s not merged with its annotation.

impl<'a> Field<'a>

Only permissible on button fields.

pub fn button_options<'b>( &mut self, options: impl IntoIterator<Item = TextStr<'b>>, ) -> &mut Self

Write the /Opt array to set the export values of children of this field. Only permissible on checkbox fields, or radio button fields. PDF 1.4+.

impl<'a> Field<'a>

Only permissible on check box fields.

pub fn checkbox_value(&mut self, state: CheckBoxState) -> &mut Self

Write the /V attribute to set the state of this check box field. The state corresponds to an appearance stream in the appearance dictionary of this field’s widget annotation. Only permissible on check box fields.

pub fn checkbox_default_value(&mut self, state: CheckBoxState) -> &mut Self

Write the /DV attribute to set the default state of this check box field. The state corresponds to an appearance stream in the appearance dictionary of this field’s widget annotation. Only permissible on check box fields.

impl<'a> Field<'a>

Only permissible on radio button fields.

pub fn radio_value(&mut self, state: Name<'_>) -> &mut Self

Write the /V attribute to set the state of this radio button field. The state corresponds to an appearance stream in the appearance subdictionary of this field’s widget annotation and is either a custom name unique for all unique fields, or /Off. Only permissible on radio button fields.

pub fn radio_default_value(&mut self, state: Name<'_>) -> &mut Self

Write the /DV attribute to set the default state of this radio button field. The state corresponds to an appearance stream in the appearance subdictionary of this field’s widget annotation and is either a custom name unique for all unique fields, or /Off. Only permissible on radio button fields.

impl<'a> Field<'a>

Only permissible on text fields.

pub fn text_max_len(&mut self, len: i32) -> &mut Self

Write the /MaxLen attribute to set the maximum length of the fields text in characters. Only permissible on text fields.

The definition of a chracter depends on the encoding of the content of /V. Which is either one byte for PDFDocEncoding or 2 for UTF16-BE.

pub fn text_value(&mut self, value: TextStr<'_>) -> &mut Self

Write the /V attribute to set the value of this text field. Only permissible on text fields.

pub fn text_default_value(&mut self, value: TextStr<'_>) -> &mut Self

Start writing the /DV attribute to set the default value of this text field. Only permissible on text fields.

impl<'a> Field<'a>

Only permissible on fields containing variable text.

pub fn vartext_default_appearance(&mut self, appearance: Str<'_>) -> &mut Self

Write the /DA attribute containing a sequence of valid page-content graphics or text state operators that define such properties as the field’s text size and colour. Only permissible on fields containing variable text.

pub fn vartext_quadding(&mut self, quadding: Quadding) -> &mut Self

Write the /Q attribute to set the quadding (justification) that shall be used in dispalying the text. Only permissible on fields containing variable text.

pub fn vartext_default_style(&mut self, style: TextStr<'_>) -> &mut Self

Write the /DS attribute to set the default style string. Only permissible on fields containing variable text. PDF 1.5+.

pub fn vartext_rich_value(&mut self, value: TextStr<'_>) -> &mut Self

Write the /RV attribute to set the value of this variable text field. Only permissible on fields containing variable text. PDF 1.5+.

impl<'a> Field<'a>

Only permissible on choice fields.

pub fn choice_options(&mut self) -> ChoiceOptions<'_>

Start writing the /Opt array to set the options that shall be presented to the user.

pub fn choice_top_index(&mut self, index: i32) -> &mut Self

Write the /TI attribute to set the index in the Field::choice_options array of the first visible option for scrollable lists.

pub fn choice_indices( &mut self, indices: impl IntoIterator<Item = i32>, ) -> &mut Self

Write the /I array to set the indices of the currently selected options. The integers in this array must be sorted in ascending order and correspond to 0-based indices in the Field::choice_options array.

This entry shall be used for choice fields which allow multiple selections (FieldFlags::MULTI_SELECT). This means when two or more elements in the Field::choice_options array have different names but export the same value or when the value fo the choice field is an array. This entry should not be used for choice fields that do not allow multiple selections. PDF 1.4+.

pub fn choice_value(&mut self, option: Option<TextStr<'_>>) -> &mut Self

Write the /V attribute to set the currently selected values of this choice field. Should be one of the values given in Self::choice_options or None if no choice is selected. Only permissible on choice fields.

pub fn choice_values<'b>( &mut self, options: impl IntoIterator<Item = TextStr<'b>>, ) -> &mut Self

Write the /V attribute to set the currently selected values of this choice field. See also Self::choice_value, for a single or no value. Only permissible on choice fields.

pub fn choice_default_value(&mut self, option: Option<TextStr<'_>>) -> &mut Self

Write the /DV attribute to set the default selected value of this choice field. Should be one of the values given in Self::choice_options or None if no choice is selected. Only permissible on choice fields.

pub fn choice_default_values<'b>( &mut self, options: impl IntoIterator<Item = TextStr<'b>>, ) -> &mut Self

Write the /DV attribute to set the default selected values of this choice field. See also Self::choice_default_value, for a single or no value. Only permissible on choice fields.

Methods from Deref<Target = Dict<'a>>

pub fn len(&self) -> i32

The number of written pairs.

pub fn is_empty(&self) -> bool

Whether no pairs have been written so far.

pub fn insert(&mut self, key: Name<'_>) -> Obj<'_>

Start writing a pair with an arbitrary value.

pub fn pair<T: Primitive>(&mut self, key: Name<'_>, value: T) -> &mut Self

Write a pair with a primitive value.

This is a shorthand for dict.insert(key).primitive(value).

pub fn pairs<'n, T: Primitive>( &mut self, pairs: impl IntoIterator<Item = (Name<'n>, T)>, ) -> &mut Self

Write a sequence of pairs with primitive values.

Trait Implementations

impl<'a> Deref for Field<'a>

type Target = Dict<'a>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a> DerefMut for Field<'a>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'a, 'any> Rewrite<'a> for Field<'any>

type Output = Field<'a>

The writer with the rewritten lifetime.

impl<'a> Writer<'a> for Field<'a>

fn start(obj: Obj<'a>) -> Self

Start writing the object.