Widget Annotations in Form Fields

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

Widget Annotations are the visual elements of a form field. A field can have zero or more widgets attached to it: a TextField, ListBox, ComboBox, and CheckBox usually have exactly one, while the RadioGroup has multiple widgets, one for each radio button.

In some cases, you may want a field to appear on more than one page, repeating the same value. In that case, fields that normally have just one widget may have multiple widgets attached. Someone filling out the form may use any of those widgets to update the field's value, and this is reflected in all the other widgets as well.

Creating

Widget Annotations can be created explicitly with the new operator. Since each field has specific needs for its widget annotations, there are classes derived from the abstract base class WidgetAnnotation for each of them: RadioButtonWidgetAnnotation, CheckBoxWidgetAnnotation, TextBoxWidgetAnnotation, CombBoxWidgetAnnotation, and ListBoxWidgetAnnotation.

The constructors take two parameters: the page on which the annotation is to appear and the rectangle defining the location and size on that page:

// Explicit creation of a CheckBoxWidgetAnnotation.
CheckBoxWidgetAnnotation widget = new CheckBoxWidgetAnnotation(myPage, myRectangle);

Each widget annotation will have an appropriate graphics (appearance) depending on its type. After creation, certain visual aspects can be changed, such as border style and background color (see Modify Field Appearance). Other properties such as text color and font can be changed through the field, once attached to one (see below: Adding)

Widget Annotations are also created implicitly by most Form's field creation member functions (CreateListBox, CreateComboBox, CreateCheckBox, and CreateTextField, but not CreateRadioGroup) and by the field's AddWidget and AddOption member functions. Each of these functions take the page and rectangle as parameters in order to create the Widget Annotation internally. These functions create the widget and add them to the field, all in one call.

// Implicit creation of a TextBoxWidgetAnnotation when creating the field.
TextField textField = myDocument.Form.CreateTextField("Name", page1, nameRect);
TextBoxWidgetAnnotation textBoxWidget1 = textField.Widgets[0];

// Implicit creation of an additional TextBoxWidgetAnnotation on the same field using AddWidget. The widgets will show the same text.
TextBoxWidgetAnnotation textBoxWidget2 = textField.AddWidget(page2, nameRect);

// Implicit creation of RadioButtonWidgetAnnotations using AddOption.
// Note that CreateRadioGroup, unlike the other Create functions, does not create an initial widget.
RadioGroup radioGroup = myDocument.Form.CreateRadioGroup("Color");
ChoiceOption optionBlue = radioGroup.AddOption(page, rect, "Blue");
ChoiceOption optionRed = radioGroup.AddOption(page, rect, "Red");
RadioButtonWidgetAnnotation radioWidgetBlue = radioGroup.Widgets[0];
RadioButtonWidgetAnnotation radioWidgetRed = radioGroup.Widgets[1];

Adding

If you have a widget annotation that is not attached to a field yet (for instance, you just created one with the new operator), there are 3 ways it can be attached to a field:

Using the Form's CreateListBox, CreateComboBox, CreateCheckBox, and CreateTextField functions. These functions take a widget annotation of the appropriate type as a parameter and link it to the field.
Using Field.AddWidget This function is part of the Field base class and takes a widget annotation of any kind. Care should be taken not to mix widget annotations of one type with field of another type (e.g. calling TextField.AddWidget with a RadioButtonWidgetAnnotation).
Using CheckBox.AddOption and RadioGroup.AddOption For RadioGroup and CheckBox fields, each widget represents an option and the use of their AddOption function is preferred over the AddWidget function. The function takes a widget annotation of the corresponding type as a parameter, as well as the export value that is submitted when the widget is selected.

// 1. Using the form's Create functions.
TextBoxWidgetAnnotation textWidget1 = new TextWidgetAnnotation(page1, nameRect);
TextField textField = myDocument.Form.CreateTextField("Name", textWidget1);

// 2. Using the field's AddWidget function.
TextBoxWidgetAnnotation textWidget2 = new TextWidgetAnnotation(page2, nameRect);
textField.AddWidget(textWidget2);

// 3. Using the field's AddOption function.
RadioGroup radioGroup = myDocument.Form.CreateRadioGroup("Color");
radioButton1 = new RadioButtonWidgetAnnotation(page, rect1);
radioButton2 = new RadioButtonWidgetAnnotation(page, rect2);
ChoiceOption option1 = radioGroup.AddOption(radioButton1, "Blue");
ChoiceOption option2 = radioGroup.AddOption(radioButton2, "Red");

Once added to the field, the widgets can be accessed through the field's Widgets property. In case of a RadioGroup or CheckBox field, a ChoiceOption is also created in the field's Options property when a widget is added to the field.

AddWidget vs AddOption

For widget based choice fields (RadioGroup and CheckBox), the use of AddWidget is discouraged. It is preferable to use AddOption instead, so you can immediately set the ExportValue for each option along with the widget. In all other aspects, the functionality is the same.

For text based choice fields (ListBox and ComboBox), there is no separate widget associated with each option and there is no other way than to use AddOption to include options in the list. Using AddWidget will create a completely new visual ListBox or ComboBox rendering of the same field reflecting the same options. Since they are separate widgets however, they may have a different appearance, for instance with regard to background color or border style.

A widget can only be attached to one field. If it is already attached to another field, an exception is thrown.

Once attached to a field, that field becomes owner of the widget. This means that if the field is removed from the form, it will delete the widget. Any reference your application may have to the widget will become invalid.

Removing

You can detach a widget from a field by calling the field's RemoveWidget member function. For choice fields (RadioButton, CheckBox, ListBox and ComboBox) you can alternatively use RemoveOption, which has the same effect, but uses an index instead of a reference to the widget.

Removing a widget from the field does not delete the widget, nor will it remove the widget from the page. However, ownership of the widget annotation object now no longer lies with the field and it will no longer be destroyed when the field is deleted.

If you also want to remove the widget from the page, use the widget's Remove member function. If the widget is still attached to a field, this function will also detach the widget from the field.

// Get the radio group.
RadioGroup radioGroup = myDocument.Form.Fields[0] as RadioGroup;

// Remove the third radio button from the radio group, but not from the page.
radioGroup.RemoveWidget(radioGroup.Widgets[2]);

// Remove the second radio button from both the radio group and from the page.
radioGroup.Widgets[1].Remove();