Skip to main content
Version: Version 4.2

Annotations and form fields

The PDF Toolbox SDK lets you add annotations and form fields to PDF documents.

Annotations​

Annotations are elements that are not part of a page’s content, but are applied on top of a page. In contrast to ordinary page content, many annotation types are meant to behave interactively in a PDF viewer.

Form fields​

AcroForm form fields in a PDF consist of data structures that represent variable values, potentially to be modified by a user in a PDF viewing application.

Form fields are structured in a tree topology in which the Document acts as the tree root. The immediate child form field nodes thereof can be accessed via the Document.FormFields property.

Each child form field node in the tree can itself have more children. Such form field is called a “sub form”. A child form field node that has no children is simply a “form field”.

There are several form field sub­types:

  • General text field
  • Comb text field
  • Check box field
  • Push button field
  • Radio button field
  • Combo box field
  • List box field

In the PDF Toolbox SDK, the subtypes are modeled by classes that inherit from a base class FieldNode in the following way:

FieldNodes are contained in a FieldNodeMap in the form of key-­value pairs, for which the keys act as form field node identifiers. The identifier must not contain any full stops (“.”).

The fully qualified identifier of a form field node is defined as the concatenation of all its ancestor SubForm’s identifiers and its own identifier, separated by full stops (“.”), e.g. MySubForm.MyField. The fully qualified identifier of each form field node is unique within a document. While the form field tree models the form’s data, the visual manifestations of form fields are managed by Widgets contained in Page.Widgets, of which each form field has at least one.

Create form fields​

In an output document (a document created with Document.Create), form fields can be created from scratch by means of the following methods:

  • CheckBox.Create
  • ComboBox.Create
  • CombTextField.Create
  • GeneralTextField.Create
  • ListBox.Create
  • RadioButtonGroup.Create
  • SubForm.Create

A PushButton cannot be created.

After creating a ChoiceField, i.e. a ComboBox or a ListBox, ChoiceItems should be created and added with the ChoiceField.AddNewItem method.

After creating a RadioButtonGroup, new RadioButtons should be created and added with the RadioButtonGroup.AddNewButton method. Each created form field must be added either to the document’s Document.FormFields, or to the SubForm.Children of a SubForm. You should set all form field properties prior to creating any Widgets. Specifically, changing form field properties that affect the form field’s visual appearance fails with an UnsupportedOperation error if the form field has widgets.

For each form field, at least one Widget should be created using the RadioButton.AddNewWidget method for radio button groups, or the form field’s Field.AddNewWidget method for all other field types. Finally, each created widget must be added to one of the Page.Widgets of any of the document’s Pages. A page can either be created from scratch with the Page.Create method or it can be copied with Page.Copy from an input document (a document created with Document.Open). In the latter case, PageCopyOptions.FormFields must not be set to FormFieldCopyStrategy.Copy and PageCopyOptions.UnsignedSignatures not to CopyStrategy.Copy. The combination of creating form fields and copying form fields or unsigned signatures via Page.Copy or PageList.Copy (with PageCopyOption argument in which either the PageCopyOptions.FormFields property is set to FormFieldCopyStrategy.Copy or the PageCopyOptions.UnsignedSignatures property is set to CopyStrategy.Copy) is not supported. Specifically:

  • Once Page.Copy or PageList.Copy has been called with PageCopyOptions.FormFields set to FormFieldCopyStrategy.Copy or PageCopyOptions.UnsignedSignatures set to CopyStrategy.Copy, any subsequent call to any of the form field creation methods fails with an IllegalState error.
  • Once any of the form field creation methods has been called, any subsequent call to Page.Copy or PageList.Copy with PageCopyOptions.FormFields set to FormFieldCopyStrategy.Copy or PageCopyOptions.UnsignedSignatures set to CopyStrategy.Copy fails with an IllegalArgument error.

Fill form fields​

Filling a form means that the values (field content) of form fields are modified. Depending on the field type, this implies the following:

  • TextField: modify text using TextField.Text.
  • CheckBox: modify the state using CheckBox.Checked.
  • RadioButtonGroup: modify the choice using RadioButtonGroup.ChosenButton.
  • ComboBox: modify choice using ComboBox.ChosenItem or ComboBox.EditableItemName.
  • ListBox: modify choice using ListBox.ChosenItems.

To use the PDF Toolbox SDK for filling out the values of form fields in a PDF, the following procedure must be followed:

  1. An input document is opened with Document.Open and an output document is created with Document.Create.
  2. Before copying pages, the form fields must be copied from the input document to the output document as follows:
  3. Access the form field node map of the input and the output document via Document.FormFields.
  4. Copy each form field node found in the input to the output document using the FieldNode.Copy method. Copying SubForms automatically copies their children. (Note that the copied form fields have no widgets yet.)
  5. The value of a copied form field can be modified here or later in Step 3.
  6. Add each copied form field node to the output document’s field node mapDocument.FormFields, preferably using the same key as used in the input document’s field node map
  7. The output document’s form field nodes can be accessed, e.g. using FieldNodeMap.Lookup to modify form field values.
  8. Copy all pages with the PageList.Copy method. Hereby, the PageCopyOptions.FormFields property in the PageCopyOptions argument must be set to FormFieldCopyStrategy.CopyAndUpdateWidgets and the PageCopyOptions.UnsignedSignatures must be set to CopyStrategy.Remove or CopyStrategy.Flatten. In this step, the Widgets of input form fields are copied to the output form fields and automatically updated to reflect the new form field values. (As soon as a form field has Widgets, its value can no longer be modified.) The combination of filling form fields and copying form fields via Page.Copy or PageList.Copy (with PageCopyOptions argument in which CopyOptions.FormFields is set to FormFieldCopyStrategy.Copy) is not supported. Specifically:
  • Once Page.Copy or PageList.Copy has been called with PageCopyOptions.FormFields set to FormFieldCopyStrategy.Copy, any subsequent call to FieldNode.Copy fails with an IllegalState error.
  • Once FieldNode.Copy has been called, any subsequent call to Page.Copy or PageList.Copy with PageCopyOptions.FormFields set to FormFieldCopyStrategy.Copy or PageCopyOptions.UnsignedSignatures set to CopyStrategy.Copy fails with an IllegalArgument error.