Manipulating Form Fields

Introduction to AcroForm & Form Fields

Adobe Acrobat Form (formerly known as AcroForm) is a collection of form fields, which are used to gather information from the user in an interactive manner. Sometimes, we also refer to such forms as Interactive Forms. One PDF document cannot have more than one form in itself. Fields in such interactive forms are organized in a hierarchy and they can inherit certain characteristics from their parent fields. AcroForms are becoming an official source of collecting data from users in many business and government organizations around the world.

Aspose.Pdf and Form Fields

Aspose.Pdf supports creating such interactive forms. There are some simple types of form fields supported by Aspose.Pdf that can be added to PDF Forms. These form fields are collected together in an enumeration, FormFieldType . The pre-defined form fields included in FormFieldType enumeration are listed below:

Form Field Types	Description
RadioButton	Represents a radio button
List	Represents a list
CheckBox	Represents a check box
Combo	Represents a combo box
Text	Represents a text box

Important: It is must to specify a unique name for each form field when adding to a PDF document. Because, whenever it would be needed to fill a form field, the name of that specific form field is used to access it. For example: If you need to fill form fields using some tool like Aspose.Pdf.Kit.Form then you would be able to fill them using their names.

How to Add a Form Field?

Aspose.Pdf provides FormField class that enables developers to create different kinds of form fields into their PDF forms.

Developers can instantiate FormField objects and then specify their types using FormFieldType enumeration. After that, developers can set the names and values of form fields using FieldName and FieldValue properties of FormField class respectively. There are many other properties of FormField class that can be used by developers to customize any kind of form field supported by Aspose.Pdf .

An example is given below to demonstrate the use of a form field.

Code Snippet

[C#]

//Instantiate a Pdf instance

Pdf pdf1 = new Pdf();

//Add a section in the Pdf document

Section sec1 = pdf1.Sections.Add();

//Create a form field

FormField combo = new FormField();

//Set the type of form field to Combo

combo.FormFieldType = FormFieldType.Combo;

//Set the field name

combo.FieldName = "ACombo";

//Add few options to the combo

combo.ChoiceOptions = new string[]{"Red","Green","Blue"};

//Set the default selected value of the combo field

combo.FieldValue = "Red";

//Set the width of the field

combo.FormWidth = 80;

//Set the height of the field

combo.FormHeight = 20;

//Add the combo form field to the paragraphs collection of the section

sec1.Paragraphs.Add(combo);

//Save the Pdf

pdf1.Save(...);

[VB.NET]

'Instantiate a Pdf instance

Dim pdf1 As Pdf = New Pdf

'Add a section in the Pdf document

Dim sec1 As Section = pdf1.Sections.Add()

'Create a form field

Dim combo As FormField = New FormField

'Set the type of form field to Combo

combo.FormFieldType = FormFieldType.Combo

'Set the field name

combo.FieldName = "ACombo"

'Add few options to the combo

combo.ChoiceOptions = New String() {"Red", "Green", "Blue"}

'Set the default selected value of the combo field

combo.FieldValue = "Red"

'Set the width of the field

combo.FormWidth = 80

'Set the height of the field

combo.FormHeight = 20

'Add the combo form field to the paragraphs collection of the section

sec1.Paragraphs.Add(combo)

'Save the Pdf

pdf1.Save(...)

[XML]

<?xml version="1.0" encoding="utf-8" ?>

<FormField FormFieldType="Combo" FieldName="ACombo"

FieldValue="Red" ChoiceOptions="Red Green Blue"

FormWidth="80" FormHeight="20" />

</Section>

</Pdf>

Using Custom Positioning

In Aspose.Pdf , FormField class is designed as a Paragraph and inline form field is not supported. As form field is usually used together with other content (for example, text) so, there are usually two ways of positioning a form field: using in a table or using custom positioning.

Note: For RadioButton , only custom positioning is supported.

There are some positioning types defined by Aspose.Pdf in PositioningType enumeration. These pre-defined positioning types are listed below with their brief descriptions:

Positioning Types	Description
Auto	Paragraph is positioned automatically by page renderer engine
PageRelative	Paragraph is positioned relative to the page
ColumnRelative	Paragraph is positioned relative to the column
ParagraphRelative	Paragraph is positioned relative to the paragraph

The above positioning types are explained in the figures below for your better understanding.

PageRelative

Figure: PageRelative positioning

ColumnRelative

Figure: ColumnRelative positioning

ParagraphRelative

Figure: ParagraphRelative positioning

The following example shows how to use RadioButton with custom positioning.

Code Snippet

[C#]

//Instantiate the Pdf document and add a section to it

Pdf pdf1 = new Pdf();

Section sec1 = pdf1.Sections.Add();

//Create a table, set its column widths and add it to paragraphs collection

//of the section

Table tab1 = new Table();

tab1.ColumnWidths = "120 120 120";

sec1.Paragraphs.Add(tab1);

//Add a row to the table

Row r1 = tab1.Rows.Add();

//Add 1st cell to the row, set its padding and set the ID of the first paragraph

//in the cell to "text1"

Cell c1 = r1.Cells.Add("item1");

c1.Padding.Left = 30;

c1.Paragraphs[0].ID = "text1";

//Add 2nd cell to the row, set its padding and set the ID of the first paragraph

//in the cell to "text2"

Cell c2 = r1.Cells.Add("item2");

c2.Padding.Left = 30;

c2.Paragraphs[0].ID = "text2";

//Add 3rd cell to the row, set its padding and set the ID of the first paragraph

//in the cell to "text3"

Cell c3 = r1.Cells.Add("item3");

c3.Padding.Left = 30;

c3.Paragraphs[0].ID = "text3";

//Create a form field of RadioButton type. Set its field name and button color.

//Then set the index of the radio button value to be checked

FormField radio = new FormField();

radio.FormFieldType = FormFieldType.RadioButton;

radio.FieldName = "ARadio";

radio.ButtonColor = System.Drawing.Color.FromName("Red");

radio.RadioButtonCheckedIndex = 0;

//Create 1st radio button instance and add it to above created radio form field.

//Set its width and height. The position of the radio button is set to be

//relative to the paragraph. Link this radio button with the paragraph with ID

//equal to "text1".

RadioButton bt1 = radio.RadioButtons.Add();

bt1.ButtonHeight = 12;

bt1.ButtonWidth = 12;

bt1.PositioningType = PositioningType.ParagraphRelative;

bt1.ReferenceParagraphID = "text1";

bt1.Left = -20;

bt1.Top = 0;

//Create 2nd radio button instance and add it to above created radio form field.

//Set its width and height. The position of the radio button is set to be

//relative to the paragraph. Link this radio button with the paragraph with ID

//equal to "text2".

RadioButton bt2 = radio.RadioButtons.Add();

bt2.ButtonHeight = 12;

bt2.ButtonWidth = 12;

bt2.PositioningType = PositioningType.ParagraphRelative;

bt2.ReferenceParagraphID = "text2";

bt2.Left = -20;

bt2.Top = 0;

//Create 3rd radio button instance and add it to above created radio form field.

//Set its width and height. The position of the radio button is set to be

//relative to the paragraph. Link this radio button with the paragraph with ID

//equal to "text3".

RadioButton bt3 = radio.RadioButtons.Add();

bt3.ButtonHeight = 12;

bt3.ButtonWidth = 12;

bt3.PositioningType = PositioningType.ParagraphRelative;

bt3.ReferenceParagraphID = "text3";

bt3.Left = -20;

bt3.Top = 0;

//Add the radio form field to the paragraphs collection of the section

sec1.Paragraphs.Add(radio);

//Save the Pdf

pdf1.Save(...);

[VB.NET]

'Instantiate the Pdf document and add a section to it

Dim pdf1 As Pdf = New Pdf

Dim sec1 As Section = pdf1.Sections.Add()

'Create a table, set its column widths and add it to paragraphs collection

'of the section

Dim tab1 As Table = New Table

tab1.ColumnWidths = "120 120 120"

sec1.Paragraphs.Add(tab1)

'Add a row to the table

Dim r1 As Row = tab1.Rows.Add()

'Add 1st cell to the row, set its padding and set the ID of the first paragraph

in the cell to "text1"

Dim c1 As Cell = r1.Cells.Add("item1")

c1.Padding.Left = 30

c1.Paragraphs(0).ID = "text1"

'Add 2nd cell to the row, set its padding and set the ID of the first paragraph

in the cell to "text2"

Dim c2 As Cell = r1.Cells.Add("item2")

c2.Padding.Left = 30

c2.Paragraphs(0).ID = "text2"

'Add 3rd cell to the row, set its padding and set the ID of the first paragraph

in the cell to "text3"

Dim c3 As Cell = r1.Cells.Add("item3")

c3.Padding.Left = 30

c3.Paragraphs(0).ID = "text3"

'Create a form field of RadioButton type. Set its field name and button color.

'Then set the index of the radio button value to be checked

Dim radio As FormField = New FormField

radio.FormFieldType = FormFieldType.RadioButton

radio.FieldName = "ARadio"

radio.ButtonColor = System.Drawing.Color.FromName("Red")

radio.RadioButtonCheckedIndex = 0

'Create 1st radio button instance and add it to above created radio form field.

'Set its width and height. The position of the radio button is set to be

'relative to the paragraph. Link this radio button with the paragraph with ID

'equal to "text1".

Dim bt1 As RadioButton = radio.RadioButtons.Add()

bt1.ButtonHeight = 12

bt1.ButtonWidth = 12

bt1.PositioningType = PositioningType.ParagraphRelative

bt1.ReferenceParagraphID = "text1"

bt1.Left = -20

bt1.Top = 0

'Create 2nd radio button instance and add it to above created radio form field.

'Set its width and height. The position of the radio button is set to be

'relative to the paragraph. Link this radio button with the paragraph with ID

'equal to "text2".

Dim bt2 As RadioButton = radio.RadioButtons.Add()

bt2.ButtonHeight = 12

bt2.ButtonWidth = 12

bt2.PositioningType = PositioningType.ParagraphRelative

bt2.ReferenceParagraphID = "text2"

bt2.Left = -20

bt2.Top = 0

'Create 3rd radio button instance and add it to above created radio form field.

'Set its width and height. The position of the radio button is set to be

'relative to the paragraph. Link this radio button with the paragraph with ID

'equal to "text3".

Dim bt3 As RadioButton = radio.RadioButtons.Add()

bt3.ButtonHeight = 12

bt3.ButtonWidth = 12

bt3.PositioningType = PositioningType.ParagraphRelative

bt3.ReferenceParagraphID = "text3"

bt3.Left = -20

bt3.Top = 0

'Add the radio form field to the paragraphs collection of the section

sec1.Paragraphs.Add(radio)

'Save the Pdf

pdf1.Save("e:/temp/test.pdf")

[XML]

<?xml version="1.0" encoding="utf-8" ?>

<Row>

</Text>

</Cell>

</Text>

</Cell>

</Text>

</Cell>

</Row>

</Table>

<FormField FormFieldType="RadioButton"

RadioButtonCheckedIndex="0" FieldName="aRadioutton"

ButtonColor="Red">

<RadioButton ButtonWidth="12" ButtonHeight="12"

PositioningType="ParagraphRelative"

ReferenceParagraphID="text1" Left="-20" Top="0">

</RadioButton>

<RadioButton ButtonWidth="12" ButtonHeight="12"

PositioningType="ParagraphRelative"

ReferenceParagraphID="text2" Left="-20" Top="0">

</RadioButton>

<RadioButton ButtonWidth="12" ButtonHeight="12"

PositioningType="ParagraphRelative"

ReferenceParagraphID="text3" Left="-20" Top="0">

</RadioButton>

</FormField>

</Section>

</Pdf>