Interactive Forms

PDF is mainly used as format that provides consistent output regardless of the output device. However, it also provides various interactive features, one of them being support for forms.

AcroForm vs XFA Forms

The PDF specification provides two different ways for representing forms: AcroForm and XFA forms:

XFA forms need much more functionality in a PDF reader application than AcroForm forms. Due to this support for XFA forms is only available in certain commercial software applications.

Since XFA forms are already deprecated, HexaPDF only has support for interactive forms.

Interactive Forms (AcroForm)

An interactive form consists of the main form dictionary, form fields and widget annotations. Together they define the structure and visible appearance of the form.

The main form dictionary references the root fields which in turn can reference child fields. This allows one to build a hierarchy of fields and to inherit attributes from parent fields. Fields without child fields are called terminal fields.

These terminal fields can have a visible appearance which is provided by a widget annotation. Each field can have zero, one or more associated widgets.

Main Interactive Form Dictionary

The main form dictionary can be referenced from the document catalog via the /AcroForm key (see HexaPDF::Type::Catalog#acro_form). It is implemented by the HexaPDF::Type::AcroForm::Form class.

It only provides a few entries, the most important of which are:

The form dictionary object is the main entry point for handling interactive forms with HexaPDF. It allows you to list, modify, create and delete the form fields. By relying on the provided convenience methods all the tedious but needed book-keeping is done behind the scenes.

Form Fields

A form field dictionary contains, among other things, the type of the field, its name and its value.

There are four main types of fields which are further sub-divided:

Button fields

These fields represent interactive controls that a user can manipulate with a mouse.

A button field may be a push button (something to click which produces a result immediately), a check box (for toggling between two states) or a radio button (typically one button in a set can be turned on).

See HexaPDF::Type::AcroForm::ButtonField.

Text fields

These fields allow the user to input text from the keyboard.

The text can be entered into a single-line or multi-line field and there is also the possibility for rich text strings which allow inline formatting of the text.

See HexaPDF::Type::AcroForm::TextField.

Choice fields

These fields contain several text items of which the user can select one or more.

A choice field may be presented as a scrollable list box or a combo box. The latter also allows the user to input a value other than the predefined ones.

See HexaPDF::Type::AcroForm::ChoiceField.

Signature fields

These fields represent digital signatures and optional data for authenticating the signer name and the document’s contents.

The visual appearance is defined by associated widget annotations. Each terminal field can have zero, one or more associated widgets. For example, each widget annotation of a radio button field describes one possible selection value. Another use for multiple widget annotations is on a multi-page form where a name entered by the user should appear in a header or footer on every page.

Widget Annotations

A widget annotation describes the visual appearance of a form field on a page. It is implemented by HexaPDF::Type::Annotations::Widget.

As with all other annotations the widgets placement on the page is specified by the /Rect key and the visual appearance by the /AS and /AP keys.

Additionally, each widget can specify a background color and border style and, depending on the type of the associated field, other properties.

When using HexaPDF you don’t have to worry about the visual appearance. HexaPDF creates the needed appearance streams automatically using a default style similar to those found in popular PDF reader applications (see HexaPDF::Type::AcroForm::AppearanceGenerator). This is done by setting the needed widget annotation and field properties when the widget is created. Later these properties are used during the creation of the appearance (like some PDF readers would do when the /NeedAppearances key on the main form object is set).

You can naturally provide the appearance streams yourself if needed since those are just Form XObjects.