Read and Write Form Field Values

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

Once a Field object is obtained, each has a Values and DefaultValues property. Each field type is defined under the namespace ImageGear.Formats.PDF.Forms. To iterate over a form to obtain fields, see the help topic Traverse Form Fields.

The field's Values property is the current value of the field on the PDF, which is the text that is exported when the form is submitted. The DefaultValues property is the value which the field is set to on a call to Reset. Writing to these properties will update the field on the PDF.

The ChoiceField derivatives, RadioGroup, ListBox, ComboBox and CheckBox all allow index-based access. For these fields, the SelectedIndex property is the first 0-based option selected in the field, while SelectedIndices is an array of integers with all selected options. For example, if there are three radio buttons in a radio group and the 2nd is selected, SelectedIndex will be 1. The ChoiceField also contains an Options array, of class ChoiceOption, which contains information about each choice in the field.

See the SetPDFFormFields sample for an example of how to set the values of the fields in a PDF form.

See the ReadPDFFormFields sample for an example of how to read the values of the fields in a PDF form.

Reading and Writing Text Fields

For TextField field types, the value that is displayed is always the first value of the TextField's Values. All other values in the array are ignored. Because of this, TextField contains a singular convenience property, Value, to perform this. TextField also supports reading and writing rich text through the property RichTextValue.

Updating a TextField's Values property, or calling Reset, will change the value displayed on the form. Unlike other field types, TextFields have a MaxLength property. If a value is assigned to a TextField that exceeds that field's maximum length, the value is truncated to fit within the field.

Reading and Writing CheckBox Fields

Individual CheckBox fields have a Checked boolean property which indicates whether or not the checkbox is selected. The checked property can be toggled directly or by setting or unsetting a CheckBox field's Values array.

Toggling a CheckBox's Checked property, predictably, toggles whether or not a CheckBox is selected; however, it is also possible to select or unselect a checkbox by writing to its Values array. If a checkbox is unselected, the first member of its Values array will contain "Off". If the first member of the Values array contains any other string or contains no value, the checkbox is selected.

It is also possible that multiple checkboxes exist within one field, similar to RadioGroup. Because of this, ChoiceField index-based access applies.

Reading and Writing ComboBox Fields

ComboBox fields have independent ExportValue and Label properties. A Label is the value of a choice as rendered on the page. The ExportValue is the value of the field when the choice is selected. A ComboBox's SelectedIndex property indicates which entry is selected.

A ComboBox field type also has an Edit property that indicates whether the ComboBox allows the user to enter a custom item in the list. If a user does enter a custom value, the SelectedIndex property for that value will be -1. The value of a custom entry will be the string entered by the user.

This snippet demonstrates adding a custom value to a ComboBox. Setting the value will update the rendered field to show the new value.

This does not add the entered value to the ComboBox Options. Subsequently changing the Value property will discard the custom value.

void CustomComboBoxValue(ImGearPDFDocument pdf, string fieldName)
{
    var comboBox = pdf.Form.Fields[fieldName] as ComboBox;
    comboBox.Value = "My custom value";
}

Reading and Writing ListBox Fields

A ListBox field allows multiple selections if its boolean property MultiSelect is true. Also, like ComboBox, a ListBox's options can have an independent ExportValue and Label. In this case, the Label is the string that is visually rendered on the page, while ExportValue is the corresponding value of the ListBox (or one of the values with MultiSelect enabled) if the item is selected.

Reading and Writing RadioGroup Fields

The RadioGroup has additional properties that should to be considered when reading and writing:

The NoToggleToOff property indicitates that at least one button in the group must be checked at all times. When attempting to turn off all buttons, an exception will be thrown if this property is true.
The RadiosInUnison property indicates that all buttons with the same export value will be selected when any one of these buttons is selected.

A RadioGroup field's value will be the ExportValue of the currently selected button. Use SelectedIndex to determine the currently selected button. To read the value of each button in the field, selected or not, access the Options array.

To update radio group's options, write to the ExportValue or Label of the required index in the Options property. Users can select a button by setting SelectedIndex, or by setting Values to the corresponding ExportValue.