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 list below for information specific to each field type:

Reading and Writing Text Fields
Reading and Writing CheckBox Fields
Reading and Writing ComboBox Fields
Reading and Writing ListBox Fields
Reading and Writing RadioGroup Fields

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.

Reading TextFields

The following code demonstrates how to read a TextField's value and default value when accessed by its name.

PDF support needs to be initialized first for this snippet to work.

using ImageGear.Formats.PDF;
using ImageGear.Formats.PDF.Forms;

void PrintTextFieldValue(ImGearPDFDocument pdf, string fieldName)
{
    var textField = pdf.Form.Fields[fieldName] as TextField;
    Console.WriteLine(textField.FullName);
    Console.WriteLine(textField.Type.ToString());

        Console.WriteLine("Value:");
    Console.WriteLine(textField.Value);
    Console.WriteLine("Default Value:");
    Console.WriteLine(textField.DefaultValue);
}

Writing TextFields

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.

The following code demonstrates how to update a TextField's value as well as using its maximum length.

void UpdateTextFieldValue(ImGearPDFDocument pdf, string fieldName, string newValue)
{
    var textField = pdf.Form.Fields[fieldName] as TextField;

    if (textField.MaxLength < newValue.Length)
        textField.MaxLength = newValue.Length;

    textField.Value = newValue;
}

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.

Reading CheckBox Fields

The follow code demonstrates how to read checkbox values.

PDF support needs to be initialized first for this snippet to work.

using ImageGear.Formats.PDF;
using ImageGear.Formats.PDF.Forms;

void PrintCheckBoxValue(ImGearPDFDocument pdf, string fieldName)
{
    var checkBox = pdf.Form.Fields[fieldName] as CheckBox;

    Console.WriteLine(checkBox.FullName);
    Console.WriteLine(checkBox.Type.ToString());

    Console.WriteLine("Checked:");
    Console.WriteLine(checkBox.Checked.ToString());
    Console.WriteLine("Checked by default:");
    Console.WriteLine(checkBox.CheckedByDefault.ToString());
}

Writing CheckBox Fields

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.

void UpdateCheckBoxValue(ImGearPDFDocument pdf, string fieldName)
{
    var checkBox = pdf.Form.Fields[fieldName] as CheckBox;
    checkBox.Options[0].ExportValue = "MyNewCheckboxValue";
    checkBox.Checked = !checkBox.Checked;
}

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.

Reading ComboBox Fields

PDF support needs to be initialized first for this snippet to work.

using ImageGear.Formats.PDF;
using ImageGear.Formats.PDF.Forms;

void PrintComboBoxValues(ImGearPDFDocument pdf, string fieldName)
{
    var comboBox = pdf.Form.Fields[fieldName] as ComboBox;
    Console.WriteLine(comboBox.FullName);
    Console.WriteLine(comboBox.Type.ToString());
    Console.WriteLine("Editable:");
    Console.WriteLine(comboBox.Edit);
    Console.WriteLine("Options:");
    foreach (ChoiceOption option in comboBox.Options)
    {
        Console.WriteLine("ExportValue: " + option.ExportValue);
        Console.WriteLine("Label: " + option.Label);
    }
    Console.WriteLine("Selected Index: ");
    Console.WriteLine(comboBox.SelectedIndex);
    Console.WriteLine("Current Value: ");
    Console.WriteLine(comboBox.Value);
}

Writing ComboBox Fields

This snippet demonstrates updating a ComboBox field's options, the Edit flag, and the selected option.

void UpdateComboBoxValues(ImGearPDFDocument pdf, string fieldName)
{
    var comboBox = pdf.Form.Fields[fieldName] as ComboBox;
    comboBox.Options[0].Label = "Option 0";
    comboBox.Options[0].ExportValue = "option0";
    comboBox.Edit = false;
    comboBox.SelectedIndex = 0;
}

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 ListBox Fields

PDF support needs to be initialized first for this snippet to work.

using ImageGear.Formats.PDF;
using ImageGear.Formats.PDF.Forms;

void PrintListBoxValues(ImGearPDFDocument pdf, string fieldName)
{
    var listBox = pdf.Form.Fields[fieldName] as ListBox;
    Console.WriteLine(listBox.FullName);
    Console.WriteLine(listBox.Type.ToString());
    Console.WriteLine("MultiSelect:");
    Console.WriteLine(listBox.MultiSelect);
    Console.WriteLine("Options:");
    foreach (ChoiceOption option in listBox.Options)
    {
        Console.WriteLine("ExportValue: " + option.ExportValue);
        Console.WriteLine("Label: " + option.Label);
    }
    Console.WriteLine("Current Values: ");
    foreach (string value in listBox.Values)
    {
        Console.WriteLine(value);
    }
    Console.WriteLine("Selected Indices: ");
    foreach (int index in listBox.SelectedIndices)
    {
        Console.WriteLine(index);
    }
}

Writing ListBox Fields

void UpdateListBoxValues(ImGearPDFDocument pdf, string fieldName)
{
    var listBox = pdf.Form.Fields[fieldName] as ListBox;
    listBox.Options[0].Label = "Select This Option";
    listBox.Options[0].ExportValue = "option0";
    listBox.MultiSelect = true;
    listBox.SelectedIndices = new int[] { 0, 2, 3 };
}

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.

Reading RadioGroup Fields

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.

PDF support needs to be initialized first for this snippet to work.

using ImageGear.Formats.PDF;
using ImageGear.Formats.PDF.Forms;

void PrintRadioGroupValues(ImGearPDFDocument pdf, string fieldName)
{
    var radioGroup = pdf.Form.Fields[fieldName] as RadioGroup;
    Console.WriteLine(radioGroup.FullName);
    Console.WriteLine(radioGroup.Type.ToString());
    Console.WriteLine("Button values:");
    foreach(ChoiceOption option in radioGroup.Options)
    {
        Console.WriteLine(option.ExportValue);
    }
    Console.WriteLine("Current Value: ");
    Console.WriteLine(radioGroup.Values.Length != 0 ? radioGroup.Values[0] : "<None>");
    Console.WriteLine("Selected Index: ");
    Console.WriteLine(radioGroup.SelectedIndex);
    Console.WriteLine("Value at selected index: ");
    Console.WriteLine(radioGroup.Options[radioGroup.SelectedIndex].ExportValue);
}

Writing RadioGroup Fields

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.

void UpdateRadioGroupValues(ImGearPDFDocument pdf, string fieldName)
{
    var radioGroup = pdf.Form.Fields[fieldName] as RadioGroup;
    radioGroup.Options[0].ExportValue = "MyNewValue1";
    radioGroup.Options[1].ExportValue = "MyNewValue2";
    // The following two lines are equivalent:
    radioGroup.SelectedIndex = 1;
    radioGroup.Values = new string[] { "MyNewValue2" };
}