class HexaPDF::Type::AcroForm::Form

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.

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 the parent fields don’t already exist, they are created as pure namespace fields (see create_namespace_field). If the name doesn’t contain dots, a top-level field is created.

Before a field value other than false can be assigned to the check box, a widget needs to be created.

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 the parent fields don’t already exist, they are created as pure namespace fields (see create_namespace_field). If the name 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.

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 the parent fields don’t already exist, they are created as pure namespace fields (see create_namespace_field). If the name 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

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 the parent fields don’t already exist, they are created as pure namespace fields (see create_namespace_field). If the name 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.

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 the parent fields don’t already exist, they are created as pure namespace fields (see create_namespace_field). If the name 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.

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 the parent fields don’t already exist, they are created as pure namespace fields (see create_namespace_field). If the name 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.

Creates an untyped namespace field for creating hierarchies.

Example:

form.create_namespace_field('text')
form.create_text_field('text.a1')

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 the parent fields don’t already exist, they are created as pure namespace fields (see create_namespace_field). If the name 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.

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 the parent fields don’t already exist, they are created as pure namespace fields (see create_namespace_field). If the name doesn’t contain dots, a top-level field is created.

Before a field value other than nil can be assigned to the radio button, at least one widget needs to be created.

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 the parent fields don’t already exist, they are created as pure namespace fields (see create_namespace_field). If the name doesn’t contain dots, a top-level field is created.

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 the parent fields don’t already exist, they are created as pure namespace fields (see create_namespace_field). If the name 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 not specified, it defaults to Helvetica.

font_options

A hash with font options like :variant that should be used. If not specified, it defaults to the empty hash.

font_size

The font size that should be used. If not specified, it defaults to 0 (= auto-sizing).

font_color

The font color that should be used. If not specified, it defaults to 0 (i.e. black).

align

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

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

Deletes the field specified by the given name or via the given field object.

If the field is a signature field, the associated signature dictionary is also deleted.

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

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

Fills form fields with the values from the given data hash.

The keys of the data hash need to be full field names and the values are the respective values, usually in string form. It is possible to specify only some of the fields of the form.

What kind of values are supported for a field depends on the field type:

• For fields containing text (single/multiline/comb text fields, file select fields, combo boxes and list boxes) the value needs to be a string and it is assigned as is.

• For check boxes, the values “y”/“yes”/“t”/“true” are handled as assigning true to the field, the values “n”/“no”/“f”/“false” are handled as assigning false to the field, and every other string value is assigned as is. See ButtonField#field_value= for details.

• For radio buttons the value needs to be a String or a Symbol representing the name of the radio button widget to select.

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

Finds all root fields and sets /Fields appropriately.

See: find_root_fields

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

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.

Recalculates all form fields that have a calculate action applied (which are all fields listed in the /CO entry).

If HexaPDF doesn’t support a calculation method or an error occurs during calculation, the field value is not updated.

Note that calculations are not done automatically when a form field’s value changes since it would lead to possibly many calls to this actions. So first fill in all field values and then call this method.

See: JavaScriptActions

Returns the PDFArray containing the root fields.

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.