HomeExamplesDocsCodeNews
Home  »  Docs  »  API Reference  »  HexaPDF  »  Type  »  AcroForm  »  Field

Classes and Modules

class HexaPDF::Type::AcroForm::Field

Parent HexaPDF::Dictionary
Extended With HexaPDF::Utils::BitField

AcroForm field dictionaries are used to define the properties of form fields of AcroForm objects.

Fields can be organized in a hierarchy using the /Kids and /Parent keys, for namespacing purposes and to set default values. Those fields that have other fields as children are called non-terminal fields, otherwise they are called terminal fields.

While field objects can be created manually, it is best to use the various create_ methods of the main Form object to create them so that all necessary things are set up correctly.

Field Types ↑

Subclasses are used to implement the specific AcroForm field types:

  • ButtonField implements the button fields (pushbuttons, check boxes and radio buttons)

  • TextField implements single or multiline text fields.

  • ChoiceField implements scrollable list boxes or (editable) combo boxes.

  • SignatureField implements signature fields.

Field Flags ↑

Various characteristics of a field can be changed by setting a certain flag. Some flags are defined for all types of field, some are specific to a certain type.

The following flags apply to all fields:

:read_only

The field is read only which means the user can’t change the value or interact with associated widget annotations.

:required

The field is required if the form is exported by a submit-form action.

:no_export

The field should not be exported by a submit-form action.

Also see the class description of the subclasses for additional, type specific field flags.

Field Type Implementation Notes ↑

If an AcroForm field type adds additional inheritable dictionary fields, it has to set the constant INHERITABLE_FIELDS to all inheritable dictionary fields, including those from the superclass.

Similarily, if additional flags are provided, the constant FLAGS_BIT_MAPPING has to be set to combination of the superclass value of the constant and the mapping of flag names to bit indices.

See: PDF2.0 s12.7.4.1

Field Definitions

NameType/Allowed ValuesRequiredDefault Value
FTSymbol
One of: :Btn, :Tx, :Ch, :Sig		falsenil
ParentHexaPDF::Type::AcroForm::Field or Hashfalsenil
KidsHexaPDF::PDFArray or Arrayfalsenil
TStringfalsenil
TUStringfalsenil
TMStringfalsenil
FfIntegerfalse0
VHexaPDF::Dictionary or Symbol or String or HexaPDF::Stream or HexaPDF::PDFArray or Hash or Arrayfalsenil
DVHexaPDF::Dictionary or Symbol or String or HexaPDF::Stream or HexaPDF::PDFArray or Hash or Arrayfalsenil
AAHexaPDF::Dictionary or Hashfalsenil

Constants

INHERITABLE_FIELDS

The inheritable dictionary fields common to all AcroForm field types.

WIDGET_FIELDS

An array of all widget annotation field names.

Public Class Methods

inherited_value(field, name)

Treats name as an inheritable dictionary field and resolves its value for the AcroForm field field.

wrap(document, field)

Wraps the given field object inside the correct field class and returns the wrapped object.

Public Instance Methods

[](name)

Returns the value for the entry name.

If name is an inheritable field and the value has not been set on this field object, its value is retrieved from the parent fields.

See: Dictionary#[]

Calls superclass method HexaPDF::Dictionary#[]
alternate_field_name()

Returns the alternate field name that should be used for display purposes (e.g. Acrobat shows this as tool tip).

alternate_field_name=(value)

Sets the alternate field name.

See alternate_field_name

concrete_field_type()

Returns the concrete field type (:button_field, :text_field, :choice_field or :signature_field) or nil is no field type is set.

In constrast to field_type this method also considers the field flags and not just the field type. This means that subclasses can return a more concrete name for the field type.

Also see field_type

create_widget(page, allow_embedded: true, **values)

Creates a new widget annotation for this form field (must be a terminal field!) on the given page, adding the values to the created widget annotation object.

If allow_embedded is false, embedding the first widget in the field itself is not allowed.

The values argument should at least include :Rect for setting the visible area of the widget.

If the field already has an embedded widget, i.e. field and widget are the same PDF object, its widget data is extracted to a new PDF object and stored in the /Kids field, together with the new widget annotation. Note that this means that a possible reference to the formerly embedded widget (=this field) is not valid anymore!

See: HexaPDF::Type::Annotations::Widget

delete_widget(widget)

Deletes the given widget annotation object from this field, the page it appears on and the document.

If the given widget is not a widget of this field, nothing is done.

each_widget(direct_only: true) {|widget| block} → field
each_widget(direct_only: true) → Enumerator

Yields each widget, i.e. visual representation, of this field.

Widgets can be associated to the field in three ways:

  1. The widget can be embedded in the field itself.

  2. One or more widgets are defined as children of this field.

  3. Widgets of *another field instance with the same full field name*.

With the default of direct_only being true, only the usual cases 1 and 2 are handled/ If case 3 also needs to be handled, set direct_only to false or run the validation on the main AcroForm object (HexaPDF::Document#acro_form) before using this method (this will reduce case 3 to case 2).

Note: Setting direct_only to false will have a severe performance impact since all fields of the form have to be searched to check whether there is another field with the same full field name.

See: HexaPDF::Type::Annotations::Widget

embedded_widget?()

Returns true if the field contains an embedded widget.

field_name()

Returns the name of the field or nil if no name is set.

field_type()

Returns the type of the field, either :Btn (pushbuttons, check boxes, radio buttons), :Tx (text fields), :Ch (scrollable list boxes, combo boxes) or :Sig (signature fields).

Also see concrete_field_type

flag(*flags, clear_existing: false)

Sets the given flags, given as flag names or bit indices. If clear_existing is true, all prior flags will be cleared.

See the class description for a list of available flags.

flagged?(flag)

Returns true if the given flag is set. The argument can either be the flag name or the bit index.

See the class description for a list of available flags.

flags()

Returns an array of flag names representing the set bit flags.

See the class description for a list of available flags.

form_field()

Returns self.

This method is only here to make it easier to get the form field when the object may either be a form field or a field widget.

full_field_name()

Returns the full name of the field or nil if no name is set.

The full name of a field is constructed using the full name of the parent field, a period and the field name of the field.

must_be_indirect?()

Form fields must always be indirect objects.

terminal_field?()

Returns true if this is a terminal field.