Introduction to Forms
Form Support in PSPDFKit
PSPDFKit supports all form types specified by the PDF specification.
|Type||Field Object||Annotation Object|
|Check, Radio, and Push Buttons||
|List and Combo Boxes||
We differentiate between field objects and annotation objects; field objects have no visual representation of their own and are represented by
FormField, while annotation objects are visual representations of a single control inside a form field and are represented by
With form elements being programmatically accessible, you can easily prefill all your forms or submit filled-in form values to your server. We modeled our forms API around the
FormProvider, which can be accessed via
PdfDocument#getFormProvider. It can be used to retrieve all form fields or elements in a document or to query form fields by their name.
For a complete example of how to fill forms programmatically, take a look at
FormFillingExample in our Catalog app.
Retrieving Field and Annotation Objects
FormProvider (which can be retrieved from a
PdfDocument), you can fetch field objects with the
getFormFields() method. Associated annotations can be retrieved by retrieving associated
FormElements using the
getFormElements() call on each field and then calling
getAnnotation() on each element.
Form selection can be controlled with a new API in
PdfFragment. This is analogous to the existing annotation selection API. A single
FormElement can be selected by calling
setSelectedFormElement; you can query for the selected form element with
getSelectedFormElement; and you can exit form editing mode via
exitCurrentlyActiveMode. We also have a set of listeners that can be registered on
PdfFragment for listening to form element updates, selection changes, and clicks. Take a look at
FormManager for a list.
Field objects handle the state of form fields and offer appropriate methods to modify them. Each form field has a fully qualified name (retrievable by calling
getFullyQualifiedName()) that can be used to identify and retrieve a specific field object.
Each field object has one or more annotations linked to it. The main purpose of an annotation object is to offer a graphical element on top of a PDF (see Introduction to Annotations for more on this).
Renaming Form Field Names
Due to internal constraints, form field names can’t be renamed using
FormElement instances. It is, however, possible to rename them using
PdfProcessor; see the
setFormFieldMappings call on
PdfProcessorTask. You can simply pass in a map containing your source form field name and the new form field name.
As an example, this can be useful if you have a template PDF with form fields that needs to be appended to a different PDF file. Form field names must be unique, and it would not be possible to append the same template multiple times without changing the names.
Please note, the renaming of form fields requires the Document Editor component to be enabled for your license.