PDF Document API - Form Field Enhancements and Facade API (v21.1)

As you already know, interactive forms (AcroForms) - with fillable form fields – are essential to many businesses. These forms help organizations facilitate/simplify data acquisition and record keeping processes. For example, AcroForms can be used to conduct polls, initiate market research, and eliminate the need for paper-based contracts.

In our most recent major release (v21.1), we added new interactive form field capabilities to our PDF Document API and our WinForms PDF Viewer and WPF PDF Viewer controls. You can now modify properties/display options for available form field types, retrieve complex field items, and change form field values with relative ease.

Though older versions of our PDF API/PDF Viewers allowed you to organize interactive form fields, you had to navigate complex form field hierarchies to retrieve fields and associated options. With v21.1, we decided to simplify our implementation with a new API layer (Facade API). Because Facade API hides the complexity of the document model, you can now execute multiple operations against a PDF document without access to its internal structure.

Note: You must own an active DevExpress Office File API Subscription or DevExpress Universal Subscription to use this method in production code. For more information on Office File API licensing, please write to us at clientservcies@devexpress.com.

Form Field Facade API

Our new Facade API allows you to execute the following form field actions:

• Change form field options
• Change widget annotation properties associated with the form field
• Obtain form field location
• Fill interactive form fields

To explore the capabilities of this new API, be sure to check out our Edit Form Field Properties demo (To execute the following demo, you’ll need to install the most recent version of the DevExpress Office File API).

How to Change Form Field Options

You can change form field and appearance properties as needs dictate. Use the PdfDocumentFacade.AcroForm property to obtain interactive form field options.  You can obtain the properties for all fields, a field with a specific name, or a specific form field type.

The code sample below changes available form field options:

using (PdfDocumentProcessor pdfDocumentProcessor = new PdfDocumentProcessor()) 
{ 
    pdfDocumentProcessor.LoadDocument("Documents//FormDemo.pdf"); 
    PdfDocumentFacade documentFacade = pdfDocumentProcessor.DocumentFacade; 
    PdfAcroFormFacade acroForm = documentFacade.AcroForm;  

    // Obtain text form field properties: 
    PdfTextFormFieldFacade visaField = acroForm.GetTextFormField("VisaNo"); 

    // Divide field text into equally spaced positions: 
    visaField.InputType = PdfTextFieldInputType.Comb; 
    visaField.Multiline = false;  

    // Limit number of inserted characters: 
    visaField.MaxLength = 8;  

    // Enable multiline text in the text field: 
    PdfTextFormFieldFacade addressField = acroForm.GetTextFormField("Address"); 

    addressField.Multiline = true; 
    addressField.Scrollable = true;
    addressField.SpellCheck = false;  

    // Set radio group options: 
    PdfRadioGroupFormFieldFacade genderField =
        acroForm.GetRadioGroupFormField("Gender"); 
    genderField.RadiosInUnison = true; 
    genderField.ToggleToOff = false;  

    PdfComboBoxFormFieldFacade nationalityField =
        acroForm.GetComboBoxFormField("Nationality"); 

    // Disable user input in the combo box: 
    nationalityField.Editable = false; 

    // Disable multiple selection: 
    nationalityField.MultiSelect = false;  

    // Sort list items alphabetically: 
    nationalityField.Sorted = true;  

    pdfDocumentProcessor.SaveDocument("FormDemo_new.pdf"); 
} 

How to Change Widget Annotation Properties

A widget annotation contains a form field’s display properties – background color, border color/width, font options, etc. The PdfWidgetFacade class contains widget options that apply to all form fields. Each form field type includes its own widget annotation properties. Use the PdfFormFieldFacade<T, V>.Widgets property to retrieve widget settings.

The code below changes the push button’s icon, specifies the radio group’s marker options, and applies color to all widget annotations.

using (PdfDocumentProcessor pdfDocumentProcessor = new PdfDocumentProcessor())
{
  pdfDocumentProcessor.LoadDocument("Documents//FormDemo.pdf");
  PdfDocumentFacade documentFacade = pdfDocumentProcessor.DocumentFacade;
  PdfAcroFormFacade acroForm = documentFacade.AcroForm; 

  //Obtain button form field parameters:
  PdfButtonFormFieldFacade pushButton = acroForm.GetButtonFormField("Submit");
  PdfButtonWidgetFacade buttonWidget = pushButton.Widgets[0];

  //Specify button icon and set its options:
  buttonWidget.SetNormalIcon("Documents/submit_3802014.png");
  buttonWidget.IconOptions.FitToAnnotationBounds = true;
  buttonWidget.IconOptions.ScaleCondition =
      PdfIconScalingCircumstances.BiggerThanAnnotationRectangle;
  buttonWidget.TextPosition = PdfWidgetAnnotationTextPosition.NoCaption;
  PdfRadioGroupFormFieldFacade genderField =
      acroForm.GetRadioGroupFormField("Gender");

  //Change marker style for all radio buttons:
  foreach (PdfRadioButtonWidgetFacade widget in genderField.Widgets)
  {
    widget.ButtonStyle = PdfAcroFormButtonStyle.Square;
  }

 //Change color and border settings for all form fields:
 var fields = acroForm.GetFields();
 foreach (PdfFormFieldFacade field in fields)
 {
   ChangeFormFieldColor(field);
 }
 pdfDocumentProcessor.SaveDocument("FormDemo_new.pdf");
} 

private static void ChangeFormFieldColor(PdfFormFieldFacade field)
{
  foreach (PdfWidgetFacade pdfWidget in field)
  {
    //Specify color and border settings
    //for all form fields:
    pdfWidget.BorderWidth = 1;
    pdfWidget.BackgroundColor = new PdfRGBColor(0.81, 0.81, 0.81);
    pdfWidget.BorderColor = new PdfRGBColor(0.47, 0.44, 0.67);
    pdfWidget.FontColor = new PdfRGBColor(0.34, 0.25, 0.36);                 

    //Change border style for text form fields:
    if (field.Type == PdfFormFieldType.Text)
    {
       pdfWidget.BorderStyle = PdfBorderStyle.Underline;
    }
}

How to Fill Interactive Form Fields

Each FormFieldFacade class (PdfButtonFormFieldFacade, PdfCheckBoxFormFieldFacade, etc.) includes a Value property. This property allows you to specify form field values. Use the PdfChoiceFormFieldFacade.Items property to obtain a list of values for choice form fields (combo box, list box, etc.). 

using (PdfDocumentProcessor pdfDocumentProcessor = new PdfDocumentProcessor()) 
{ 
    pdfDocumentProcessor.LoadDocument("Documents//FormDemo.pdf");   

    PdfDocumentFacade documentFacade = pdfDocumentProcessor.DocumentFacade; 
    PdfAcroFormFacade acroForm = documentFacade.AcroForm;
    FillFormFields(acroForm); 
    pdfDocumentProcessor.SaveDocument("FormDemo_new.pdf"); 
}  

private static void FillFormFields(PdfAcroFormFacade acroForm) 
{ 
    PdfTextFormFieldFacade visaField = acroForm.GetTextFormField("VisaNo"); 
    visaField.Value = "73203393";   

    PdfTextFormFieldFacade addressField = acroForm.GetTextFormField("Address");
    addressField.Value = "98033, 722 Moss Bay Blvd., Kirkland, WA, USA";
    
    PdfRadioGroupFormFieldFacade genderField =
        acroForm.GetRadioGroupFormField("Gender");
    genderField.Value = genderField.Field.Items[2].Value;  

    PdfComboBoxFormFieldFacade nationalityField =
        acroForm.GetComboBoxFormField("Nationality"); 
    nationalityField.Value = nationalityField.Items[68].Value; 
} 

Additional Facade API Features

We plan to extend our Facade API over the coming months and have already added a PdfPageFacade class thanks to feedback received in the following support ticket: T999903. You can use this class method to flatten page annotations. We also implemented a PdfAnnotationFacade class to flatten a specific annotation. This API will be available with our v21.1.4 minor update.

The code below flattens all annotations located on the lower half of the page:

using (PdfDocumentProcessor processor = new PdfDocumentProcessor())
{
  // Load document:
  processor.LoadDocument("..\\..\\Document.pdf"); 

  // Flatten annotations located
  // on the lower half of the page:
  PdfPageFacade pageFacade = documentFacade.Pages[0]; 

  double halfPage = processor.Document.Pages[0].CropBox.Top / 2;
  pageFacade.FlattenAnnotations(x => x.Rectangle.Top < halfPage); 

  // Save the result:
  processor.SaveDocument("..\\..\\Result.pdf");
} 

Tell Us What You Think

As always, we welcome your feedback. Please feel free to leave comments below or contact us via the DevExpress Support Center.

Free DevExpress Products - Get Your Copy Today