Getting Started with PDFForm

Requirements: Secure PDF

Introduction

The PDFForm component in Secure PDF provides a powerful and flexible way to create and manipulate interactive form fields within PDF documents.

This guide walks through how to use this component to generate various form fields, as well as modifying and removing them. Before continuing, it is recommended to download the latest version of Secure PDF to follow along with this guide.

Overview

The PDF specification defines seven interactive form field types:

• Button
• Check box
• Radio button
• Text box
• List box
• Combo box
• Signature

The PDFForm component supports the creation and modification all of the above field types in a PDF document (except for signature fields, which are covered by the PDFSign component—please see this article for more details).

To begin, provide the input document as a file (InputFile), byte array (InputData), or stream (SetInputStream) and call the Open method. This method will populate the Fields collection with the existing form fields in the document. When finished editing the form, call the Close method to close the document and save the changes.

Adding and Modifying Form Fields

The below sections contain instructions for adding and modifying each type of form field. Note that each of the following methods returns the index of the newly added field in the Fields collection, making it easy to access the PDFField object later. These objects' properties, such as their current values and dimensions, can then be adjusted to ensure the form meets your requirements.

PDFForm includes three additional methods that allow you to customize the form field before it is created. The SetPage and SetPosition methods can be used to specify the form field's location (the page on which it will be added and its position on the page, respectively). If SetPage is not explicitly called, the field will be placed on the first page of the document by default. The SetFont method can also be used to configure font properties (name, size, style, and color) for form fields that contain text.

Button Fields

A button (also known as pushbutton) field is a button on the form that simply responds as soon as it is clicked. Because of this, it is the only form field that does not retain a permanent value. Use the AddButton method to add a button field:

int buttonIdx = form.AddButton("button", "Press Me");

The action associated with a button field can be updated to perform specific tasks, such as displaying an alert or triggering a script. The example below assigns a JavaScript action to display an alert message when the button is clicked.

form.Fields[buttonIdx].Action = "app.alert('Hello! This is a simple alert message.');";

Check Box Fields

A check box represents a form field that can be toggled between two states: on and off. Use the AddCheckBox method to add a check box field:

int checkBoxIdx = form.AddCheckBox("checkbox", false);

The value associated with a check box field determines whether it will be toggled on or off. The example below toggles the check box on.

form.Fields[checkBoxIdx].Value = "true";

Radio Button Fields

Radio button fields are a set of related buttons, each of which—just like check boxes—can be in one of two states: on or off. Radio buttons belong to a radio group in which at most one button in the group may be in the on state at a time. Use the AddRadioButton method to add a radio button field:

int radioButtonIdx = form.AddRadioButton("radioGroup", "radiobutton", false); int radioButton2Idx = form.AddRadioButton("radioGroup", "radiobutton2", true);

A radio button field can be modified to change its state. The example below selects the first radio button, switching it on, which automatically deselects the other radio button in the same group, switching it off.

form.Fields[radioButtonIdx].Value = "true";

Text Box Fields

A text box field is box or space that allows the user to enter and edit text in a designated area on the form. It can contain default text and can also be configured as a password field to mask the input. Use the AddTextBox method to add a text box field:

int textBoxIdx = form.AddTextBox("textbox", "Enter your name here", false);

As shown in the example below, the value of a text box field can be modified to fill it with the desired text.

form.Fields[textBoxIdx].Value = "My name is John Doe";

List Box Fields

A list box field is a scrollable choice field that displays a list of selectable text items the user can choose from. Use the AddListBox method to add a list box field:

int listBoxIdx = form.AddListBox("numbers", "One\r\nTwo\r\nThree", "One");

A list box field can be modified to select one of the options. The example below updates the list box field to select the option "Three".

form.Fields[listBoxIdx].Value = "Three";

Combo Box Fields

A combo box field is a choice field that consists of a drop-down list of text items the user can choose from. At most one item may be selected at a time. Compared to list box fields, combo box fields include an editable text box that allows the user to enter a custom value in addition to the predefined options. Use the AddComboBox method to add a combo box field:

int comboBoxIdx = form.AddComboBox("colors", "Red\r\nGreen\r\nBlue", "Red");

A combo box field can be modified to select one of the options. The example below updates the combo box field to select the option "Blue".

form.Fields[comboBoxIdx].Value = "Blue";

Removing Form Fields

The RemoveField and RemoveFieldByName methods can be used to remove a form field from the document. These methods will not only deactivate the field on the form but will also remove the corresponding PDFField object from the Fields collection.

RemoveField removes a form field identified by its index, whereas RemoveFieldByName removes a field by using its name.

form.RemoveField(buttonIdx); form.RemoveFieldByName("checkbox");