Pdfium.Net SDK. User Manual

Get access acroforms

Overview

An interactive form - sometimes referred to as an AcroForm - is a collection of fields for gathering information interactively from the user. A PDF document may contain any number of fields appearing on any combination of pages, all of which make up a single, global interactive form spanning the entire document.

The initial class for accessing acroforms is PdfForms. Each field in a document’s interactive form is defined by a PdfField class. A field may also have one or more PdfControl that define its appearance on the page.

The AlternateName property in the PdfField class holds a text string defining the field’s partial field name. The FullName holds a fully qualified field name constructed from the alternate field names of the field and all of its ancestors. For a field with no parent, the partial and fully qualified names are the same. For a field that is the child of another field, the fully qualified name is formed by appending the child field’s partial name to the parent’s fully qualified name, separated by a period (.):

parent’s_full_name.child’s_partial_name

The MappingName to be used when exporting interactive form field data from the document. Please refer this article for details.

Interactive forms support the following field types:

Button fields represent interactive controls on the screen that the user can manipulate with the mouse. They include pushbuttons, check boxes, and radio buttons.
Text fields are boxes or spaces in which the user can enter text from the keyboard.
Choice fields contain several text items, at most one of which may be selected as the field value. They include scrollable list boxes and combo boxes.
Signature fields represent electronic signatures for authenticating the identity of a user and the validity of the document’s contents.

Open in full size

Acro Forms

Enumerate the form fields

All the form fields are maintained in PdfFieldCollections class. You can enumerate the fields from this form field collection.

C#

var forms = new PdfForms();
using (var doc = PdfDocument.Load(@"test.pdf", forms))
{
    int i = 0;
    foreach (var field in forms.InterForm.Fields)
    {
        if (field is PdfPushButtonField)
        {
            var pushbutton = field as PdfPushButtonField;
            //...
        }
        else if (field is PdfCheckBoxField)
        {
            var checkbox = field as PdfCheckBoxField;
            //...
        }
        else if (field is PdfRadioButtonField)
        {
            var radiobutton = field as PdfRadioButtonField;
            //...
        }
        else if (field is PdfTextBoxField)
        {
            var textbox = field as PdfTextBoxField;
            //...
        }
        else if (field is PdfComboBoxField)
        {
            var combobox = field as PdfComboBoxField;
            //...
        }
        else if (field is PdfListBoxField)
        {
            var listbox = field as PdfListBoxField;
            //...
        }
    }
}

You can also get a list of controls for a given page and thus get all the fields presented on that page.

C#

using (var doc = PdfDocument.Load(@"test.pdf", new PdfForms()))
{
    var controls = doc.FormFill.InterForm.GetPageControls(doc.Pages[0]);
    foreach(var ctrl in controls)
    {
        var field = ctrl.Field;
        //...
    }    

}

Creating a new PDF form

AcroForm are especially convenient for preparation of various applications, such as taxes and other government forms. Patagames SDK provides APIs to add or remove form fields to or from a PDF file. Designing a form from scratch allows developers to create the exact content and layout of the form they want.

Adding the text box field

PdfTextBoxField and PdfTextBoxControl classes are used to create a text box field in PDF forms.

The below code snippet illustrates how to add a text box that displays its content in two separate controls with different appearances.

C#

//Load the existing PDF document.
using (var doc = PdfDocument.Load(@"test.pdf", new PdfForms()))
{
    //Set default appearance. Helvetica and autosize is used by default
    if(!doc.FormFill.InterForm.HasDefaultAppearance())
        doc.FormFill.InterForm.SetDefaultAppearance();

    //Create a textbox field 
    var textField = new PdfTextBoxField(doc.FormFill.InterForm);

    //Create a textbox control that uses default appearance.
    var page = doc.Pages[0];
    float left = 10.0f;
    float right = page.Width - 10;
    float top = page.Height - 10;
    float bottom = top - 32;
    var textCtrl = new PdfTextBoxControl(textField, page, new FS_RECTF(left, top, right, bottom));

    //create a second control assigned to the same textbox field and uses a different font and color.
    var borderColor = FS_COLOR.Red;
    var backgroundColor = FS_COLOR.Yellow;
    var textColor = FS_COLOR.Blue;
    var font = PdfFont.CreateFont(doc, "Times New Roman");
    float fontSize = 10.0f;
    var textCtrl02 = new PdfTextBoxControl(textField, page, new FS_RECTF(left, top - 42, right, bottom - 42), borderColor, backgroundColor, textColor, font, fontSize);

    //Add the form field to the document.
    doc.FormFill.InterForm.Fields.Add(textField);

    //Save the document
    doc.Save(@"Form.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

The text typed in the first control will be reflected in the second control since they are both assigned to the same textbox field.

Text Field Example

Adding the button field

PdfPushButtonField and PdfPushButtonControl classes are used to create a push button field in PDF forms.

The below code snippet illustrates how to add a button with submit forms action. Please refer to the actions section for more details.

C#

//Load the existing PDF document.
using (var doc = PdfDocument.Load(@"test.pdf", new PdfForms()))
{
    //Set default appearance. Helvetica and autosize is used by default
    if (!doc.FormFill.InterForm.HasDefaultAppearance())
        doc.FormFill.InterForm.SetDefaultAppearance();

    //Create a pushbutton field 
    var pushbuttonField = new PdfPushButtonField(doc.FormFill.InterForm);

    //Create a pushbutton control that uses default appearance.
    var page = doc.Pages[0];
    var action = new PdfSubmitFormAction(doc, "https://mydomain.com");
    var pushbuttonCtrl = new PdfPushButtonControl(pushbuttonField, page, new FS_RECTF(10, page.Height - 92, 220, page.Height - 124), "Submit forms", action);

    //Add the form field to the document.
    doc.FormFill.InterForm.Fields.Add(pushbuttonField);

    //Save the document
    doc.Save(@"Form.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

To implement sending data to a remote server, subscribe to the PdfFormsSubmitForm.

C#

doc.FormFill.SubmitForm += (s, e) =>
{
    using (var fdf = FdfDocument.Load(e.FormData))
    {
        //...
    }
};

Adding the editable combo box field

C#

//Load the existing PDF document.
using (var doc = PdfDocument.Load(@"test.pdf", new PdfForms()))
{
    //Set default appearance. Helvetica and autosize is used by default
    if (!doc.FormFill.InterForm.HasDefaultAppearance())
        doc.FormFill.InterForm.SetDefaultAppearance();

    //Create a combobox field 
    var comboboxField = new PdfComboBoxField(doc.FormFill.InterForm);
    comboboxField.Items.Add(new ChoiceFieldItem("name 1", "value1"));
    comboboxField.Items.Add(new ChoiceFieldItem("name 2", "value2"));
    comboboxField.Items.Add(new ChoiceFieldItem("name 3", "value3"));

    comboboxField.Edit = true;

    //Create a combobox control that uses default appearance.
    var page = doc.Pages[0];
    var comboboxCtrl = new PdfComboBoxControl(comboboxField, page, new FS_RECTF(10, page.Height - 134, 220, page.Height - 166));

    //Add the form field to the document.
    doc.FormFill.InterForm.Fields.Add(comboboxField);

    //Save the document
    doc.Save(@"Form.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Adding the multiselect list box field

C#

//Load the existing PDF document.
using (var doc = PdfDocument.Load(@"test.pdf", new PdfForms()))
{
    //Set default appearance. Helvetica and autosize is used by default
    if (!doc.FormFill.InterForm.HasDefaultAppearance())
        doc.FormFill.InterForm.SetDefaultAppearance();

    //Create a listbox field 
    var listboxField = new PdfListBoxField(doc.FormFill.InterForm);
    listboxField.Items.Add(new ChoiceFieldItem("item 1", "item1_value"));
    listboxField.Items.Add(new ChoiceFieldItem("item 2", "item2_value"));
    listboxField.Items.Add(new ChoiceFieldItem("item 3", "item3_value"));

    listboxField.MultiSelect = true;

    //Create a listbox control that uses default appearance.
    var page = doc.Pages[0];
    var listboxCtrl = new PdfListBoxControl(listboxField, page, new FS_RECTF(10, page.Height - 176, 220, page.Height - 230));

    //Add the form field to the document.
    doc.FormFill.InterForm.Fields.Add(listboxField);

    //Select items
    listboxField.SelectItem(0, false);
    listboxField.SelectItem(1, true);
    listboxField.SelectItem(2, true);

    //Save the document
    doc.Save(@"Form.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

List Box Example

Adding the signature field

C#

//Load the existing PDF document.
using (var doc = PdfDocument.Load(@"test.pdf", new PdfForms()))
{
    //Create a signature field 
    var signatureField = new PdfSignatureField(doc.FormFill.InterForm);

    //Specify the rest of the fields that must be locked by the signature.
    PdfField[] fieldsToProtect = {
        doc.FormFill.InterForm.Fields[0],
        doc.FormFill.InterForm.Fields[2]
    };
    signatureField.Lock = new PdfLock(doc.FormFill.InterForm);
    signatureField.Lock.Fields = fieldsToProtect;
    signatureField.Lock.Action = Patagames.Pdf.Enums.SignatureActions.Include;

    //Create a signature control.
    var page = doc.Pages[0];
    var listboxCtrl = new PdfSignatureControl(signatureField, page, new FS_RECTF(10, page.Height - 240, 220, page.Height - 272));

    //Add the form field to the document.
    doc.FormFill.InterForm.Fields.Add(signatureField);

    //Save the document
    doc.Save(@"Form.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Adding the radio button field

The code below shows how to create 3 radio buttons, two of which turn on and off together and have different shapes.

C#

//Load the existing PDF document.
using (var doc = PdfDocument.Load(@"test.pdf", new PdfForms()))
{
    //Create a radio button
    var radiobuttonField = new PdfRadioButtonField(doc.FormFill.InterForm);

    //Radio buttons with the same export value will turn off and on together.
    radiobuttonField.RadiosInUnison = true;

    //Exactly one radio button must be selected at all times; clicking the currently selected button has no effect.
    radiobuttonField.NoToggleToOff = true;

    //Set export values
    radiobuttonField.ExportValues.Add("value 1");
    radiobuttonField.ExportValues.Add("value 1");
    radiobuttonField.ExportValues.Add("value 2");

    ///Create controls
    var page = doc.Pages[0];
    new PdfRadioButtonControl(radiobuttonField, page, new FS_RECTF(10, page.Height - 282, 42, page.Height - 314));
    new PdfRadioButtonControl(radiobuttonField, page, new FS_RECTF(52, page.Height - 282, 84, page.Height - 314), CheckboxCaptions.Diamond);
    new PdfRadioButtonControl(radiobuttonField, page, new FS_RECTF(94, page.Height - 282, 126, page.Height - 314));

    //Add the form field to the document.
    doc.FormFill.InterForm.Fields.Add(radiobuttonField);

    //Save the document
    doc.Save(@"Form.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Example Radio Buttons

Setting the PdfRadioButtonFieldNoToggleToOff to false allows you to turn off all radio buttons in the group (like a checkbox).

C#

radiobuttonField.NoToggleToOff = false;

Example Radio Buttons 02

Note
RadiosInUnison and NoToggleToOff flags are not fully supported by some third party PDF viewers.

Adding the check box field

C#

//Load the existing PDF document.
using (var doc = PdfDocument.Load(@"test.pdf", new PdfForms()))
{
    //Create a caheckbox field
    var checkboxField = new PdfCheckBoxField(doc.FormFill.InterForm);

    //Set export values
    checkboxField.ExportValues.Add("value 1");

    ///Create control
    var page = doc.Pages[0];
    var cb = new PdfCheckBoxControl(checkboxField, page, new FS_RECTF(10, page.Height - 324, 42, page.Height - 356));

    //Add the form field to the document.
    doc.FormFill.InterForm.Fields.Add(checkboxField);

    //Save the document
    doc.Save(@"Form.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Modifying the existing form field in PDF document

You can modify an existing form field by getting the field from the PdfFieldCollections. You can retrieve a field from the field collection by index or by field name.

C#

var field = doc.FormFill.InterForm.Fields[0];

C#

var field = doc.FormFill.InterForm.Fields["FieldName"];

After changing most of the properties of the field or its controls, it is necessary to call method RegenerateAppearance in order for these changes to take effect.

The following code snippet explains how to modify an existing form field in a PDF document.

C#

using (var doc = PdfDocument.Load(@"Form.pdf", new PdfForms()))
{
    //Get form field
    var field = doc.FormFill.InterForm.Fields[0] as PdfTextBoxField;

    //modify the properties
    field.Password = true;
    field.Comb = true;
    field.MaxLen = 7;

    //Delete the existing appearance of all controls associated with this field and build a new one in accordance with the changes above.
    field.RegenerateAppearance();

    //Save the document
    doc.Save(@"Form_modified.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Below are some other scenarios for modifying fields

Retrieving/Modifying the fore and back color of an existing form fields

C#

using (var doc = PdfDocument.Load(@"Form.pdf", new PdfForms()))
{
    //Get the form field
    var field = doc.FormFill.InterForm.Fields[0] as PdfTextBoxField;

    //Get the fore (text) color back and border color
    FS_COLOR textColor = field.Controls[0].Color;
    FS_COLOR bgColor = field.Controls[0].BackgroundColor;
    var borderColor = field.Controls[0].BorderColor;

    //Modify these colors.
    field.Controls[0].Color = FS_COLOR.Magenta;
    field.Controls[0].BackgroundColor = FS_COLOR.LightGreen;
    field.Controls[0].BorderColor = FS_COLOR.DarkGreen;

    //Delete the existing appearance of all controls associated with this field and build a new one in accordance with the changes above.
    field.RegenerateAppearance();

    //Save the document
    doc.Save(@"Form_modified.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Filling form fields in an existing PDF Document

Patagames PDF SDK allows you to fill the form fields.

Filling the text box field

C#

using (var doc = PdfDocument.Load(@"Form.pdf", new PdfForms()))
{
    //Get the form field
    var field = doc.FormFill.InterForm.Fields[0] as PdfTextBoxField;

    //Remove input focus from text box field if it is set. Active focus prevents the field value from being changed.
    field.InterForms.FillForms.ForceToKillFocus();

    //Set new value.
    field.Value = "New text";

    //Save the document
    doc.Save(@"Form_modified.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Filling the combo box field

C#

using (var doc = PdfDocument.Load(@"Form.pdf", new PdfForms()))
{
    //Get the form field
    var field = doc.FormFill.InterForm.Fields[2] as PdfComboBoxField;

    //Remove input focus from field if it is set. Active focus prevents the field value from being changed.
    field.InterForms.FillForms.ForceToKillFocus();

    //Set an arbitrary value in the combo box input field.
    field.Value = "New text";

    //Or select an item in the dropdown list by index.
    field.SelectItem(1, true);

    //You can also select an item in the dropdown list by specifying its export value through the field.Value property.
    field.Value = "value3";

    //Save the document
    doc.Save(@"Form_modified.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Filling the list box field

C#

using (var doc = PdfDocument.Load(@"Form.pdf", new PdfForms()))
{
    //Get the form field
    var field = doc.FormFill.InterForm.Fields[3] as PdfListBoxField;

    //Remove input focus from field if it is set. Active focus prevents the field value from being changed.
    field.InterForms.FillForms.ForceToKillFocus();

    //Select an item in the dropdown list by index.
    //If the field allows multiple selection, then you can specify multiple values for selection.
    field.SelectItem(0, true);
    field.SelectItem(1, true);
    field.SelectItem(2, false);

    //You can also select an item in the list by specifying its export value through the field.Value property.
    field.Value = "item3_value";

    //Save the document
    doc.Save(@"Form_modified.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Filling the check Box field

C#

using (var doc = PdfDocument.Load(@"Form.pdf", new PdfForms()))
{
    //Get the form field
    var field = doc.FormFill.InterForm.Fields[6] as PdfCheckBoxField;

    //Remove input focus from field if it is set. Active focus prevents the field value from being changed.
    field.InterForms.FillForms.ForceToKillFocus();

    //Check the checkbox field
    field.Check(true);

    //You can also uncheck the field by setting the "Off" value to the field.Value property.
    field.Value = "Off";

    //And check by setting export value to the field.Value property.
    field.Value = "value 1";

    //Save the document
    doc.Save(@"Form_modified.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Filling the radio button field

C#

using (var doc = PdfDocument.Load(@"Form.pdf", new PdfForms()))
{
    //Get the form field
    var field = doc.FormFill.InterForm.Fields[5] as PdfRadioButtonField;

    //Remove input focus from field if it is set. Active focus prevents the field value from being changed.
    field.InterForms.FillForms.ForceToKillFocus();

    //Turn on the radiobutton field
    field.Check(1, true);

    //You can also turn off the field by setting the "Off" value to the field.Value property.
    field.Value = "Off";

    //And turn on by setting export value to the field.Value property.
    field.Value = "value 2";

    //Save the document
    doc.Save(@"Form_modified.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Removing editing capability of form fields

The form field editing or filling capabilities can be removed by either flattening the PDF document or by marking the form or field as read only.

Patagames PDF SDK provides support to Flatten a form field by removing the existing form field and replacing it with graphical objects that would resemble the form field and cannot be edited.

Please refer the sample for flattening the form fields in new PDF document.

C#

//Load the existing PDF document.
using (var doc = PdfDocument.Load(@"Form.pdf", new PdfForms()))
{
    doc.Pages[0].FlattenPage(FlattenFlags.NormalDisplay);

    //Save the document
    doc.Save(@"Form_flattened.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Note
The form fields will be flattened only after the PDF document is saved.

To prevent the user from changing the form field content, you can also use ReadOnly property.

C#

using (var doc = PdfDocument.Load(@"Form.pdf", new PdfForms()))
{
    //Get the form field
    var field = doc.FormFill.InterForm.Fields[0];

    //Set the readonly flag
    field.ReadOnly = true;

     //Save the document
    doc.Save(@"Form_modified.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

Removing the form fields

You can remove the form fields from an existing PDF document using Remove method of PdfFieldCollections class.

C#

using (var doc = PdfDocument.Load(@"Form.pdf", new PdfForms()))
{
    //Get form field
    var field = doc.FormFill.InterForm.Fields[0];

    //Remove the field
    doc.FormFill.InterForm.Fields.Remove(field);

    //Save the document
    doc.Save(@"Form_modified.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

The above code calls ReloadForms while removing each field. If that's not what you want, here's another way to do the same.

C#

using (var doc = PdfDocument.Load(@"Form.pdf", new PdfForms()))
{
    //Get form fields
    var field1 = doc.FormFill.InterForm.Fields[0];
    var field2 = doc.FormFill.InterForm.Fields[1];

    //Remove the fields
    doc.FormFill.InterForm.RemoveField(field1);
    doc.FormFill.InterForm.RemoveField(field2);

    doc.FormFill.InterForm.ReloadForms();

    //Save the document
    doc.Save(@"Form_modified.pdf", Patagames.Pdf.Enums.SaveFlags.NoIncremental);
}

See Also

Reference

Patagames.Pdf.Net.AcroForms

Other Resources

Forms Data Format