Interactive Forms
- 5 minutes to read
A PDF document can include a form with interactive fields. Users can edit such fields directly in the PDF Viewer control:
Set the PDF Viewer control’s OptionsForm.AllowEdit property to True to allow users to edit interactive fields.
Interactive Form API
The PDF document container has the Form property that provides access to the loaded document’s interactive form. The form class implements an API you can use to import, export, and edit interactive field values. If the document has no form with interactive fields, the Form property getter creates an empty form object.
Access Fields
The form class has two series of functions that allow you to access interactive fields by their names:
- Get~ Functions
- Return a field object directly. Note that these functions raise an exception if the form has no field with the specified name or the types of the found and requested fields do not match.
- TryGet~ Functions
- This is a safe alternative to Get~ functions. A TryGet~ function returns a field object as the AField parameter if the form includes a field with the specified name. A TryGet~ function returns a Boolean value to indicate if the specified field is available.
The following table lists all field access functions available in the TdxPDFForm class:
| Get~ Function | TryGet~ Function | Description |
|---|---|---|
| GetButtonField | TryGetButtonField | Returns a non-exportable button field. |
| GetCheckBoxField | TryGetCheckBoxField | Returns a check box field. |
| GetComboBoxField | TryGetComboBoxField | Returns a combo box field. |
| GetListBoxField | TryGetListBoxField | Returns a list box field. |
| GetRadioGroupField | TryGetRadioGroupField | Returns a radio group field. |
| GetTextField | TryGetTextField | Returns a text box field. |
| GetField | TryGetField | Returns any supported interactive field. Cast the returned value to the corresponding field class to access all class-specific API members. |
Manage Interactive Form States
The interactive form API allows you to clear all populated fields or restore the default field values. To achieve these goals, call the PDF document container’s Form.ClearValues or Form.Reset procedure, respectively.
Flatten Fields
The flatten operation converts an interactive field into static PDF draw commands. For example, you can flatten the populated fields you no longer need to edit. PDF documents with flattened interactive fields also take less time to render.
Call the PDF document container’s Form.Flatten or Form.Flatten(dxPDFForm.TdxPDFCustomField) procedure to flatten all or only specific interactive fields in a document.
Fill Interactive Forms
You can programmatically edit any field obtained from an interactive form. The following code example loads the Demo.pdf file with an interactive form, populates its interactive fields, makes them static PDF content, and saves the result to the Result.pdf file:
var
ADocument: TdxPDFDocument;
ANationalityField: TdxPDFComboBoxField;
AFirstNameField, ALastNameField: TdxPDFTextField;
AGenderField: TdxPDFRadioGroupField;
I: Integer;
begin
ADocument := TdxPDFDocument.Create;
try
ADocument.LoadFromFile('Data\Demo.pdf');
// Attempts to obtain a text field named "FirstName"
if ADocument.Form.TryGetTextField('FirstName', AFirstNameField) then
AFirstNameField.Text := 'Janet';
// Attempts to obtain a text field named "LastName"
if ADocument.Form.TryGetTextField('LastName', ALastNameField) then
ALastNameField.Text := 'Leverling';
// Attempts to obtain a combo box field named "Nationality"
if ADocument.Form.TryGetComboBoxField('Nationality', ANationalityField) then
for I := 0 to ANationalityField.ItemCount - 1 do
if ANationalityField.Items[I].Value = 'United States' then
begin
ANationalityField.ItemIndex := I;
break;
end;
// Attempts to obtain a radio group field named "Gender"
if ADocument.Form.TryGetRadioGroupField('Gender', AGenderField) then
for I := 0 to AGenderField.ItemCount - 1 do
if AGenderField.Items[I].CheckedStateName = 'Female' then
begin
AGenderField.ItemIndex := I;
break;
end;
ADocument.Form.Flatten; // Flattens all fields on the form
ADocument.SaveToFile('Data\Result.pdf');
finally
ADocument.Free;
end;
end;
Import and Export Interactive Form Data
The PDF document container has the following API that you can use to import and export interactive field values in FDF, XFDF, XML, and TXT formats:
- Form.LoadDataFromFile and Form.LoadDataFromStream
- These procedures automatically detect the source data format, load field values, and populate the corresponding fields. If the loaded document’s form does not contain a field present in the source file or stream, the procedure ignores the field’s value.
- Form.SaveDataToFile and Form.SaveDataToStream
- These procedures save all exportable field values to the specified file or stream in any supported format. The SaveDataToFile procedure identifies the target format by the specified file name extension, while SaveDataToStream accepts the target format as the AFormat parameter.
The following code example imports interactive form data from a file in XFDF format and then exports the data in XML format:
var
ADocument: TdxPDFDocument;
begin
ADocument := TdxPDFDocument.Create;
try
ADocument.LoadFromFile('Data\Demo.pdf');
ADocument.Form.LoadDataFromFile('Data\FieldData.xdf');
ADocument.Form.SaveDataToFile('Data\FieldData.xml');
finally
ADocument.Free;
end;
Limitations
The current interactive form implementation does not allow you to edit the form structure or add/remove fields. You can use the interactive form API only to do the following:
- Import and export interactive form data.
- Access interactive fields by their names and edit field values.
- Add or remove options available in list box, combo box, and radio group fields.
- Flatten interactive fields (that is, make them static PDF document content).
Note
Signature fields are uneditable. Use the PDF document container’s SignatureOptions property to configure a digital signature.