HomeExamplesDocsCodeNews
Home  »  Docs  »  API Reference  »  HexaPDF  »  Type  »  AcroForm  »  HexaPDF::Type::AcroForm::TextField

Classes and Modules

class HexaPDF::Type::AcroForm::TextField

Parent VariableTextField

AcroForm text fields provide a box or space to fill-in data entered from keyboard. The text may be restricted to a single line or can span multiple lines.

A special type of single-line text field is the comb text field. This type of field divides the existing space into /MaxLen equally spaced positions.

Type Specific Field Flags ↑

See the class description for Field for the general field flags.

:multiline

If set, the text field may contain multiple lines.

:password

The field is a password field. This changes the behaviour of the PDF reader application to not echo the input text and to not store it in the PDF file.

:file_select

The text field represents a file selection control where the input text is the path to a file.

:do_not_spell_check

The text should not be spell-checked.

:do_not_scroll

The text field should not scroll (horizontally for single-line fields and vertically for multiline fields) to accomodate more text than fits into the annotation rectangle. This means that no more text can be entered once the field is full.

:comb

The field is divided into /MaxLen equally spaced positions (so /MaxLen needs to be set). This is useful, for example, when entering things like social security numbers which always have the same length.

:rich_text

The field is a rich text field.

See: PDF2.0 s12.7.5.3

Constants

FLAGS_BIT_MAPPING

Updated list of field flags.

INHERITABLE_FIELDS

All inheritable dictionary fields for text fields.

Public Instance Methods

comb_text_field?()

Returns true if this field is a comb text field.

concrete_field_type()

Returns the concrete text field type, either :single_line_text_field, :multiline_text_field, :password_field, :file_select_field, :comb_text_field or :rich_text_field.

create_appearances(force: false)

Creates appropriate appearances for all widgets.

For information on how this is done see AppearanceGenerator.

Note that no new appearances are created if the field value hasn’t changed between invocations.

By setting force to true the creation of the appearances can be forced.

default_field_value()

Returns the default field value.

See: field_value

default_field_value=(str)

Sets the default field value.

See: field_value=

field_value()

Returns the field value, i.e. the text contents of the field, or nil if no value is set.

Note that modifying the returned value *might not* modify the text contents in case it is stored as stream! So always use field_value= to set the field value.

field_value=(str)

Sets the field value, i.e. the text contents of the field, to the given string.

Note that for single line text fields, all whitespace characters are changed to simple spaces.

file_select_field?()

Returns true if this field is a file select field.

initialize_as_comb_text_field()

Initializes the text field to be a comb text field.

This method should only be called directly after creating a new text field because it doesn’t completely reset the object.

initialize_as_file_select_field()

Initializes the text field to be a file select field.

This method should only be called directly after creating a new text field because it doesn’t completely reset the object.

initialize_as_multiline_text_field()

Initializes the text field to be a multiline text field.

This method should only be called directly after creating a new text field because it doesn’t completely reset the object.

initialize_as_password_field()

Initializes the text field to be a password field.

This method should only be called directly after creating a new text field because it doesn’t completely reset the object.

multiline_text_field?()

Returns true if this field is a multiline text field.

password_field?()

Returns true if this field is a password field.

set_calculate_action(type, fields: nil)

Sets the specified JavaScript calculate action on the field.

This action is executed by a viewer when any field’s value changes so as to recalculate the value of this field. Usually, the field is also flagged as read only to avoid a user changing the value manually.

Note that HexaPDF *doesn’t* automatically recalculate field values, use Form#recalculate_fields to manually kick off recalculation.

The argument type can be one of the following:

:sum

Sums the values of the given fields.

:average

Calculates the average value of the given fields.

:product

Multiplies the values of the given fields.

:min

Uses the minimum value of the given fields.

:max

Uses the maximum value of the given fields.

:sfn

Uses the Simplified Field Notation for calculating the field’s value. This allows for more complex calculations involving addition, subtraction, multiplication and division. Field values are specified by using the full field names which should not contain spaces or punctuation characters except point.

The fields argument needs to contain a string with the SFN calculation rule.

Here are some examples:

field1 + field2 - field3
(field.1 + field.2) * (field.3 - field.4)

Note: Setting this action appends the field to the main Form’s /CO entry which specifies the calculation order. Rearrange the entries as needed.

set_format_action(type, **arguments)

Sets the specified JavaScript format action on the field’s widgets.

This action is executed when the field value needs to be formatted for rendering in the appearance streams of the associated widgets.

The argument type can be one of the following:

:number

Assumes that the field value is a number and formats it according to the given arguments. See JavaScriptActions.af_number_format_action for details on the arguments.

:percent

Assumes that the field value is a number and formats it as percentage (where 1=100% and 0=0%). See JavaScriptActions.af_percent_format_action for details on the arguments.

:time

Assumes that the field value is a string with a time value and formats it according to the given argument. See JavaScriptActions.af_time_format_action for details on the arguments.

update_widgets()

Updates the widgets so that they reflect the current field value.