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.
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.
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#
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 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#
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]);
}
}
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#
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);
}
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#
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);
}
}
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#
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);
}
}
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#
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" };
}