Add Interactive Form Fields

  • 5 minutes to read

You can create interactive form fields (for example, a text box, combo box, check box, list box) and add these fields to a document using graphics represented by an instance of the PdfGraphics class.

To create a PdfGraphics object, call the PdfDocumentProcessor.CreateGraphics method.

Note

To access the PdfGraphics class, you need to reference the DevExpress.Pdf.Drawing assembly.

The PdfGraphics class methods use a world coordinate system. See Coordinate Systems to learn more about this coordinate system.

An instance of the PdfGraphicsAcroFormField object represents the interactive form field.

Create a Form Field

To create a form field:

Then, specify the interactive form field properties. For example, you can specify the text box text and type using PdfGraphicsAcroFormTextBoxField.Text, and PdfGraphicsAcroFormTextBoxField.Type properties, respectively.

To specify the text box name, tooltip and appearance settings, use the PdfGraphicsAcroFormField.Name, PdfGraphicsAcroFormField.ToolTip, and PdfGraphicsAcroFormField.Appearance properties.

Note

Form field names must be unique in an interactive form.

To add an interactive form field to graphics, call the PdfGraphics.AddFormField method, and pass the form field to this method as an argument.

The graphics that contain interactive form fields can be added only to a single page.

To clear form fields that were previously added to graphics, call the PdfGraphics.ClearFormFields method.

Finally, add interactive form fields to a document using one of the following ways:

Example

This example shows how to create a text box field and add it to a document.

using DevExpress.Pdf;
using System.Drawing;

namespace AddTextBoxField {
    class Program {
        static void Main(string[] args) {
            using (PdfDocumentProcessor processor = new PdfDocumentProcessor()) {

                // Create an empty document. 
                processor.CreateEmptyDocument("..\\..\\Result.pdf");

                // Create and draw a text box field.
                using (PdfGraphics graphics = processor.CreateGraphics()) {
                    DrawTextBoxField(graphics);

                    // Render a page with graphics.
                    processor.RenderNewPage(PdfPaperSize.Letter, graphics);
                }
            }
        }

        static void DrawTextBoxField(PdfGraphics graphics) {

            // Create a text box field and specify its location on the page using a RectangleF object.
            PdfGraphicsAcroFormTextBoxField textBox = new PdfGraphicsAcroFormTextBoxField("text box", new RectangleF(0, 10, 200, 30));

            // Specify text box properties.
            textBox.Text = "Text Box";           
            textBox.TextAlignment = PdfAcroFormStringAlignment.Near;
            textBox.Appearance.FontSize = 12;
            textBox.Appearance.BackgroundColor = Color.AliceBlue;          

            // Add the field to graphics.
            graphics.AddFormField(textBox);
        }
    }
}

Field Name Collisions

When you add a form field to a document, make sure that it’s name is unique. Otherwise, a conflict may occur.

Pass created form fields to the PdfDocumentProcessor.CheckFormFieldNameCollisions method to check whether the form field name already exists. Use the PdfAcroFormFieldNameCollision.Field property to obtain a conflicting form field.

The PdfDocumentProcessor generates a collection of conflicting names after a collision is found. Use the PdfAcroFormFieldNameCollision.ForbiddenNames property to access the collection of forbidden names.

The code sample below checks whether the created fields’ names already exist in the loaded document and renames the conflicting field.

List<PdfAcroFormField> fields = new List<PdfAcroFormField>();
fields.Add(textBox);
fields.Add(radioGroup);
//Check whether new form fields' names already exist in the document
IList<PdfAcroFormFieldNameCollision> collisions = processor.CheckFormFieldNameCollisions(fields);
if (collisions.Count == 0)
    Console.WriteLine("No name conflicts are detected");
else
{
    foreach (var collision in collisions)
    {
        //Rename conflicting field
        Console.WriteLine("The specified form field name ({0}) already exist in the document. Renaming...", collision.Field.Name);
        while (collision.ForbiddenNames.Contains(collision.Field.Name))
            collision.Field.Name = Guid.NewGuid().ToString();
    }
}
//Add fields to the document
//And save the result
processor.AddFormFields(fields);
processor.SaveDocument("Result.pdf");

Obtain Form Field’s Location

Use the PdfInteractiveFormField.Widget property to access the visual representation of a form field (the PdfWidgetAnnotation object).

The PdfAnnotation.Rect property allows you to obtain the widget’s margins, the PdfAnnotation.Page property) provides access to the page where the widget is located.

Refer to the How to: Replace a Form Field with an Image topic for information on how to use the retrieved information to replace an interactive form.