Add a New Form Field

ImageGear does not support modification of forms in PDF documents containing XFA. Please see XFA Support for more information.

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 CreatePDFForm 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.

Refer to our CreatePDFFormField sample for a demonstration of how to create a new TextField.

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.

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.

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 MultiSelect property can be set to true to allow multiple selections at once.

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.

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.

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.