Add a New Form Field

In addition to reading and writing, you can also create new fields in a PDF document. The creation method for each field is specific to the type. In the following examples, a new field of each type with the given name will be created on the first page of a PDF document. To read fields values, see Read and Write Form Field Values. For more examples of field creation, see the ManipulatePDFAcroForms sample.

Field Creation Notes

All field creation functions that require a location and page for the field take an ImGearPDFPage and an ImGearPDFFixedRect containing the page coordinates.

Invalid Creation Exceptions

To insert a field into a document, two conditions must hold in addition to normal conditions, such as, not attempting to add a field to a non-existent page. If one of these conditions are not met, a corresponding exception is thrown.

The field name must be not be empty.
The field name must be unique among the other field names.

TextField

TextField creation requires a page and a location in page coordinates. After a TextField is created, the value can be set either as non-formatted text or as rich text. To assign as rich text, use the RichTextValue property.

There are many properties which control how text is displayed and handled in a field, such as, whether to display the field as a password (Password) or enforce a maximum length (MaxLength). Properties DoNotScroll and MaxLength are available for reading and writing, but currently do not have an impact on the behavior. Refer to the TextField class for more information.

C#	Copy Code
void CreateTextField(ImGearPDFDocument document, string fullName, string valueText) { // Create a text field at (50,50) on the first page. // The field will be 24 points high by 100 points wide. var location = new ImGearPDFFixedRect(50, 50, 150, 74); var textField = document.Form.CreateTextField(fullName, document.Pages[0] as ImGearPDFPage, location); textField.Value = valueText; }

Copy Code

void CreateTextField(ImGearPDFDocument document, string fullName, string valueText)
{
   // Create a text field at (50,50) on the first page.
   // The field will be 24 points high by 100 points wide.
   var location = new ImGearPDFFixedRect(50, 50, 150, 74);
 
   var textField = document.Form.CreateTextField(fullName,
       document.Pages[0] as ImGearPDFPage, location);

   textField.Value = valueText;
}

RadioGroup

RadioGroup has one creation function requiring a field name. Because options require placement information for the new button, not on the RadioGroup itself, you must add options with placement information after the field is created.

Note than when adding an option for RadioGroup, the AddOption overload which requires a page and rectangle must be used. The AddOption versions taking strings only are not valid for RadioGroup and will throw exceptions when used.

C#	Copy Code
void CreateRadioGroup(ImGearPDFDocument document, string fullName, string[] options) { var radioGroup = document.Form.CreateRadioGroup(fullName); // Add options at incrementing vertical locations on the first page for (int i = 0; i != options.Length; ++i) { var location = new ImGearPDFFixedRect(0, 100 * i, 18, 100 * i + 18); radioGroup.AddOption(document.Pages[0] as ImGearPDFPage, location, options[i]); } }

Copy Code

void CreateRadioGroup(ImGearPDFDocument document, string fullName, string[] options)
{
   var radioGroup = document.Form.CreateRadioGroup(fullName);
 
   // Add options at incrementing vertical locations on the first page
   for (int i = 0; i != options.Length; ++i)
   {
       var location = new ImGearPDFFixedRect(0, 100 * i, 18, 100 * i + 18);
       radioGroup.AddOption(document.Pages[0] as ImGearPDFPage, location, options[i]);
   }
}

CheckBox

A new Checkbox requires placement data, and a value to return when the checkbox is selected. This value is passed directly in the creation method.

C#	Copy Code
void CreateCheckBox(ImGearPDFDocument document, string fullName, string exportValue) { // Create a checkbox at 0,0 on the first page var location = new ImGearPDFFixedRect(0, 0, 18, 18); document.Form.CreateCheckBox(fullName, document.Pages[0] as ImGearPDFPage, location, exportValue); }

Copy Code

void CreateCheckBox(ImGearPDFDocument document, string fullName, string exportValue)
{
   // Create a checkbox at 0,0 on the first page
   var location = new ImGearPDFFixedRect(0, 0, 18, 18);
   document.Form.CreateCheckBox(fullName, document.Pages[0] as ImGearPDFPage, location, exportValue);
}

ListBox

The ListBox requires a page and location to create. Afterwards, you can add options using the AddOption method.

For the ListBox and ComboBox, an overloaded AddOption method is supplied which contains an export value string. This second value is the actual value of the field, while the optionLabel string would be the value displayed. For the single-string method, the string supplied will be both.

The ListBox contains helpful properties such as TopIndex which returns the first option visible on scrollable list boxes. Some properties such as Sort are available for reading and writing, but currently do not have an impact on the behavior.

C#	Copy Code
void CreateListBox(ImGearPDFDocument document, string fullName, string[] options) { // Create a field at 0,0 on the first page var location = new ImGearPDFFixedRect(0, 0, 72, 72); var listBox = document.Form.CreateListBox(fullName, document.Pages[0] as ImGearPDFPage, location); // Optional: Allows multiple selections listBox.MultiSelect = true; // Add options to the listbox foreach(string option in options) { listBox.AddOption(option); } }

Copy Code

void CreateListBox(ImGearPDFDocument document, string fullName, string[] options)
{
   // Create a field at 0,0 on the first page
   var location = new ImGearPDFFixedRect(0, 0, 72, 72);
   var listBox = document.Form.CreateListBox(fullName,
       document.Pages[0] as ImGearPDFPage, location);
 
   // Optional: Allows multiple selections
   listBox.MultiSelect = true;
 
   // Add options to the listbox
   foreach(string option in options)
   {
       listBox.AddOption(option);
   }
}

ComboBox

The ComboBox is similar to the ListBox and works in the same way. It requires a page and location to create. Afterwards, user can add options using the AddOption method.

If the Edit flag of the ComboBox is set, you can type in an arbitrary value in addition to the list provided. If this happens, the SelectedIndex of the ComboBox will be -1. Some properties such as Sort are available for reading and writing, but currently do not have an impact on the behavior.

C#	Copy Code
void CreateComboBox(ImGearPDFDocument document, string fullName, string[] options) { // Create a field at 0,0 on the first page var location = new ImGearPDFFixedRect(0, 0, 200, 100); var comboBox = document.Form.CreateComboBox(fullName, document.Pages[0] as ImGearPDFPage, location); // Add options to the combo box foreach(string option in options) { comboBox.AddOption(option); } }

Copy Code

void CreateComboBox(ImGearPDFDocument document, string fullName, string[] options)
{
   // Create a field at 0,0 on the first page
   var location = new ImGearPDFFixedRect(0, 0, 200, 100);
   var comboBox = document.Form.CreateComboBox(fullName,
       document.Pages[0] as ImGearPDFPage, location);
 
   // Add options to the combo box
   foreach(string option in options)
   {
       comboBox.AddOption(option);
   }
}

PushButton

The PushButton is created with a caption that is displayed on the button. After creation, use the Captions property to update the caption of any widget of the button. The PushButtonWidgetAnnotation, accessible through the field’s Widgets property, also has a Caption property that can be changed to update the corresponding text.

C#	Copy Code
void CreatePushButton(ImGearPDFDocument document, string fullName, string caption) { var location = new ImGearPDFFixedRect(0, 0, 200, 100); // Create a field at 0,0 on the first page var pushButton = document.Form.CreatePushButton(fullName, document.Pages[0] as ImGearPDFPage, location, caption); // Update the first (and only) widget's caption pushButton.Captions = new string[] { "FirstCaptionHere" }; }

Copy Code

void CreatePushButton(ImGearPDFDocument document, string fullName, string caption)
{
   var location = new ImGearPDFFixedRect(0, 0, 200, 100);
 
   // Create a field at 0,0 on the first page
   var pushButton = document.Form.CreatePushButton(fullName, document.Pages[0] as ImGearPDFPage, location, caption);

   // Update the first (and only) widget's caption
   pushButton.Captions = new string[] { "FirstCaptionHere" };
}