Type:: AcroForm:: Field
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.
Subclasses are used to implement the specific
AcroForm field types:
ButtonFieldimplements the button fields (pushbuttons, check boxes and radio buttons)
TextFieldimplements single or multiline text fields.
ChoiceFieldimplements scrollable list boxes or (editable) combo boxes.
SignatureFieldimplements signature fields.
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:
The field is read only which means the user can't change the value or interact with associated widget annotations.
The field is required if the form is exported by a submit-form action.
The field should not be exported by a submit-form action.
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 s22.214.171.124
|Name||Type/Allowed Values||Required||Default Value|
One of: :Btn, :Tx, :Ch, :Sig
|Parent||HexaPDF::Type::AcroForm::Field or Hash||false||nil|
|Kids||HexaPDF::PDFArray or Array||false||nil|
|V||HexaPDF::Dictionary or Symbol or String or HexaPDF::Stream or HexaPDF::PDFArray or Hash or Array||false||nil|
|DV||HexaPDF::Dictionary or Symbol or String or HexaPDF::Stream or HexaPDF::PDFArray or Hash or Array||false||nil|
|AA||HexaPDF::Dictionary or Hash||false||nil|
Public Class Methods
Public Instance Methods
Returns the alternate field name that should be used for display purposes (e.g. Acrobat shows this as tool tip).
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.
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 oject.
false, embedding the first widget in the field itself is not allowed.
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!
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.
Yields each widget, i.e. visual representation, of this field.
Widgets can be associated to the field in three ways:
The widget can be embedded in the field itself.
One or more widgets are defined as children of this field.
Widgets of *another field instance with the same full field name*.
With the default of
true, only the usual cases 1 and 2 are handled/ If case 3 also needs to be handled, set
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).
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.
true if the field contains an embedded widget.
Returns the name of the field or
nil if no name is set.
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).
Sets the given flags, given as flag names or bit indices. If
true, all prior flags will be cleared.
true if the given flag is set. The argument can either be the flag name or the bit index.
Returns an array of flag names representing the set bit flags.
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.
true if this is a terminal field.