HexaPDF

Menu

Home Examples Docs Code News

class HexaPDF::Type::AcroForm::Form

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

Represents the PDF’s interactive form dictionary. It is linked from the catalog dictionary via the /AcroForm entry.

Overview¶ ↑

An interactive form consists of fields which can be structured hierarchically and shown on pages by using Annotations::Widget annotations. This means one field can have zero, one or more visual representations on one or more pages. The fields at the bottom of the hierarchy which have no parent are called “root fields” and are stored in /Fields.

Each field in a form has a certain type which determines how it should be displayed and what a user can do with it. The most common type is “text field” which allows the user to enter one or more lines of text. There are also check boxes, radio buttons, list boxes and combo boxes.

Visual Appearance¶ ↑

The visual appearance of a field is normally provided by the application creating the PDF. This is done by generating the so called appearances for all widgets of a field. However, it is also possible to instruct the PDF reader application to generate the appearances on the fly using the /NeedAppearances key, see need_appearances!.

HexaPDF uses the configuration option acro_form.create_appearance_streams to determine whether appearances should automatically be generated.

See: PDF2.0 s12.7.3, Field, HexaPDF::Type::Annotations::Widget

Field Definitions

Name	Type/Allowed Values	Required	Default Value
Fields	HexaPDF::PDFArray or Array	true	[]
NeedAppearances	TrueClass or FalseClass	false	false
SigFlags	Integer	false	nil
CO	HexaPDF::PDFArray or Array	false	nil
DR	HexaPDF::Type::Resources or Hash	false	nil
DA	String	false	nil
XFA	HexaPDF::Stream or HexaPDF::PDFArray or Hash or Array	false	nil

Public Instance Methods

create_appearances(force: false)¶

Creates the appearances for all widgets of all terminal fields if they don’t exist.

If force is true, new appearances are created even if there are existing ones.

create_check_box(name)¶

Creates a new check box with the given name and adds it to the form.

The name may contain dots to signify a field hierarchy. If so, the referenced parent fields must already exist. If it doesn’t contain dots, a top-level field is created.

create_comb_text_field(name, max_chars:, font: nil, font_options: nil, font_size: nil, font_color: nil, align: nil)¶

Creates a new comb text field with the given name and adds it to the form.

The max_chars argument defines the maximum number of characters the comb text field can accommodate.

The name may contain dots to signify a field hierarchy. If so, the referenced parent fields must already exist. If it doesn’t contain dots, a top-level field is created.

The optional keyword arguments allow setting often used properties of the field, see create_text_field for details.

create_combo_box(name, option_items: nil, editable: nil, font: nil, font_options: nil, font_size: nil, font_color: nil, align: nil)¶

Creates a combo box with the given name and adds it to the form.

The name may contain dots to signify a field hierarchy. If so, the referenced parent fields must already exist. If it doesn’t contain dots, a top-level field is created.

The optional keyword arguments allow setting often used properties of the field:

option_items: Specifies the values of the list box.
editable: If set to true, the combo box allows entering an arbitrary value in addition to selecting one of the provided option items.
font, font_options, font_size and align: See create_text_field

create_file_select_field(name, font: nil, font_options: nil, font_size: nil, font_color: nil, align: nil)¶

Creates a new file select field with the given name and adds it to the form.

The name may contain dots to signify a field hierarchy. If so, the referenced parent fields must already exist. If it doesn’t contain dots, a top-level field is created.

The optional keyword arguments allow setting often used properties of the field, see create_text_field for details.

create_list_box(name, option_items: nil, multi_select: nil, font: nil, font_options: nil, font_size: nil, font_color: nil, align: nil)¶

Creates a list box with the given name and adds it to the form.

The name may contain dots to signify a field hierarchy. If so, the referenced parent fields must already exist. If it doesn’t contain dots, a top-level field is created.

The optional keyword arguments allow setting often used properties of the field:

option_items: Specifies the values of the list box.
multi_select: If set to true, the list box allows selecting multiple items instead of only one.
font, font_options, font_size and align: See create_text_field.

create_multiline_text_field(name, font: nil, font_options: nil, font_size: nil, font_color: nil, align: nil)¶

Creates a new multiline text field with the given name and adds it to the form.

The name may contain dots to signify a field hierarchy. If so, the referenced parent fields must already exist. If it doesn’t contain dots, a top-level field is created.

The optional keyword arguments allow setting often used properties of the field, see create_text_field for details.

create_password_field(name, font: nil, font_options: nil, font_size: nil, font_color: nil, align: nil)¶

Creates a new password field with the given name and adds it to the form.

The name may contain dots to signify a field hierarchy. If so, the referenced parent fields must already exist. If it doesn’t contain dots, a top-level field is created.

The optional keyword arguments allow setting often used properties of the field, see create_text_field for details.

create_radio_button(name)¶

Creates a radio button with the given name and adds it to the form.

The name may contain dots to signify a field hierarchy. If so, the referenced parent fields must already exist. If it doesn’t contain dots, a top-level field is created.

create_signature_field(name)¶

Creates a signature field with the given name and adds it to the form.

The name may contain dots to signify a field hierarchy. If so, the referenced parent fields must already exist. If it doesn’t contain dots, a top-level field is created.

create_text_field(name, font: nil, font_options: nil, font_size: nil, font_color: nil, align: nil)¶

Creates a new text field with the given name and adds it to the form.

The name may contain dots to signify a field hierarchy. If so, the referenced parent fields must already exist. If it doesn’t contain dots, a top-level field is created.

The optional keyword arguments allow setting often used properties of the field:

font

The font that should be used for the text of the field. If font_size, font_options or font_color is specified but font isn’t, the font Helvetica is used.

If no font is set on the text field, the default font properties of the AcroForm form are used. Note that field specific or form specific font properties have to be set. Otherwise there will be an error when trying to generate a visual representation of the field value.

font_options

A hash with font options like :variant that should be used.

font_size

The font size that should be used. If font, font_options or font_color is specified but font_size isn’t, font size defaults to 0 (= auto-sizing).

font_color

The font color that should be used. If font, font_options or font_size is specified but font_color isn’t, font color defaults to 0 (i.e. black).

align

The alignment of the text, either :left, :center or :right.

default_resources()¶

Returns the dictionary containing the default resources for form field appearance streams.

each_field(terminal_only: true) {|field| block} → acroform ¶

each_field(terminal_only: true) → Enumerator ¶

Yields all terminal fields or all fields, depending on the terminal_only argument.

field_by_name(name)¶

Returns the field with the given name or nil if no such field exists.

find_root_fields()¶

Returns an array with all root fields that were found in the PDF document.

find_root_fields!()¶

Finds all root fields and sets /Fields appropriately.

See: find_root_fields

flatten(fields: nil, create_appearances: true)¶

Flattens the whole interactive form or only the given fields, and returns the fields that couldn’t be flattened.

Flattening means making the appearance streams of the field widgets part of the respective page’s content stream and removing the fields themselves.

If the whole interactive form is flattened, the form object itself is also removed if all fields were flattened.

The create_appearances argument controls whether missing appearances should automatically be created.

See: HexaPDF::Type::Page#flatten_annotations

need_appearances!()¶

Sets the /NeedAppearances field to true.

This will make PDF reader applications generate appropriate appearance streams based on the information stored in the fields and associated widgets.

root_fields()¶

Returns the PDFArray containing the root fields.

set_default_appearance_string(font: 'Helvetica', font_options: {}, font_size: 0, font_color: 0)¶

Sets the global default appearance string using the provided values or the default values which provide a sane default.

See VariableTextField::create_appearance_string for information on the arguments.