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. For more examples, see the ManipulatePDFAcroForms sample in Samples.
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.
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.
The following code demonstrates how to read a TextField’s value and default value when accessed by its name.
C# |
Copy Code |
---|---|
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); } |
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.
C# |
Copy Code |
---|---|
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; } |
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.
The follow code demonstrates how to read checkbox values.
C# |
Copy Code |
---|---|
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()); } |
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.
C# |
Copy Code |
---|---|
void UpdateCheckBoxValue(ImGearPDFDocument pdf, string fieldName) { var checkBox = pdf.Form.Fields[fieldName] as CheckBox; checkBox.Options[0].ExportValue = "MyNewCheckboxValue" checkBox.Checked = !checkBox.Checked; } |
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.
C# |
Copy Code |
---|---|
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); } |
This snippet demonstrates updating a ComboBox field’s options, the Edit flag, and the selected option.
C# |
Copy Code |
---|---|
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.
C# |
Copy Code |
---|---|
void CustomComboBoxValue(ImGearPDFDocument pdf, string fieldName) { var comboBox = pdf.Form.Fields[fieldName] as ComboBox; comboBox.Value = "My custom value"; } |
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.
C# |
Copy Code |
---|---|
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); } } |
C# |
Copy Code |
---|---|
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 }; } |
The RadioGroup has additional properties that should to be considered when reading and writing:
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.
C# |
Copy Code |
---|---|
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); } |
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.
C# |
Copy Code |
---|---|
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" }; } |