Widgets

Updated on May 11, 2026

Widget annotations are used for visual representation of some FormField value on a PDF page. There are different widget annotations depending on the type of content that they should visualize. All Widget annotations are created from the FormField class inheritor Widgets property through the AddWidget() method in the corresponding Widgets collection.

Defining Widget Content

All widgets have two type of content properties:

• AnnotationContentSource properties: Properties of this type provide three FormSource instances for the three mouse interactions with the widget – normal (no mouse interaction) source, mouse over source and mouse down source. The AnnotationContentSource is usually taken with higher priority when visualizing the widget in a PDF viewer.

  There are two exceptional cases when these properties are ignored in favor of the Dynamic appearance properties.

  • The first exceptional case is when the widget is visualizing some variable content which is dynamically modified by the user interaction.
  • The second exceptional case is when the AcroForm class has ViewersShouldRecalculateWidgetAppearances property set to true which forces the viewer to ignore the provided AnnotationContentSource.

• Dynamic appearance properties: These properties are used to dynamically construct the widget appearance depending on the field value. They are separated in two classes:

  • VariableTextProperties: Defining the text specific properties
  • DynamicAppearanceCharacteristics: Defining the geometry properties of the annotation content.

  For more information on these classes, check the Dynamic Appearance Properties topic.

Widget Class

The Widget class is inheritor of Annotation and is the base class for all widgets. It provides common properties for all widgets and has WidgetContentType property, which helps you to recognize the concrete widget type and cast the base class instance to get the concrete widget inheritor.

All widgets are created using the Widgets collection of the FormField class inheritors. Using the AddWidget() and Remove() methods, you can respectively add or remove a widget from the collection. As the widget collection implements the IEnumerable interface, you can iterate all the available in the FormField instance widgets.

Example 1: Creating a widget

C#

VariableContentWidget textBoxWidget = textBoxField.Widgets.AddWidget();
textBoxWidget.Rect = new Rect(100, 100, 20, 20);

Don't forget to specify the size of the widget. Otherwise, it won't be visualized in the PDF document.

Example 2 demonstrates how to iterate the Widgets collection of a TexBoxField instance. Additionally, the code shows you how to add a widget to the Annotations collection of a RadFixedPage. Note, that you must add each widget to this collection so it can be visualized on the PDF page. Otherwise, the element will not be shown on the page.

Example 2: Iterating the widgets in the FormField's collection

C#

foreach (var widget in textBoxField.Widgets)
{
    document.Pages[0].Annotations.Add(widget);
}

The Widget class inherits from Annotation. It is important to add each annotation to the Annotations collection of RadFixedPage.

Widget Properties

The Widget class provides the following common widget properties and methods:

Member	Description
WidgetContentType	Provides the widget content type of this widget instance. Use it to recognize the type and cast to the concrete Widget class inheritor.
Field	Provides a reference to the FormField object that this widget visualizes.
TextProperties	Provides a VariableTextProperties instance specifying how to dynamically construct the text in the widget appearance.
HighlightingMode	The highlighting effect used by the PDF viewer when the mouse is over the widget.
RecalculateContent()	Recalculates the AnnotationContentSource properties so their content corresponds to the Dynamic appearance properties of the widget. Changes to VariableTextProperties and DynamicAppearanceCharacteristics are not visually displayed until this method is called.

The inherited from the Annotation class property IsPrintable is set to true for the widgets by default. If you want to exclude a widget from the document when printing, you can set its IsPrintable property to false.

Widget Types

There are several Widget class inheritors, which represent different types of content.

VariableContentWidget Class

This class corresponds to the WidgetContentType.VariableContent enum value and represents a widget, whose content is dynamically changed when the user interacts with the field value. This widget type is used by TextBoxField, CombTextBoxField, ListBoxField and ComboBoxField classes.

VariableContentWidget provides the following properties:

Property	Description
Content	Provides the AnnotationContentSource used for the initial visualization of the field value in the PDF viewer. This is used only for initial visualization before the user has interacted with the field value.
AppearanceCharacteristics	A DynamicAppearanceCharacteristics instance providing information on how to dynamically recalculate the widget appearance.

SignatureWidget Class

This class corresponds to WidgetContentType.SignatureContent enum value and represents a widget that visualizes a digital signature. This widget type is used by the SignatureField class and provides the following properties:

Property	Description
Content	Provides the AnnotationContentSource used to visualize the digital signature in the PDF viewer. This property takes higher priority over AppearanceCharacteristics.
AppearanceCharacteristics	A DynamicAppearanceCharacteristics instance providing information on how to dynamically recalculate the widget appearance. Used only when AcroForm.ViewersShouldRecalculateWidgetAppearances is true.

PushButtonWidget Class

This class corresponds to WidgetContentType.PushButtonContent enum value and represents a widget that visualizes a push button. This widget type is used by the PushButtonField class and provides the following properties:

Property	Description
Content	Provides the AnnotationContentSource used to visualize the button in the PDF viewer. This property takes higher priority over AppearanceCharacteristics.
AppearanceCharacteristics	A PushButtonAppearanceCharacteristics instance providing information on how to dynamically recalculate the widget appearance. Used only when AcroForm.ViewersShouldRecalculateWidgetAppearances is true. Call RecalculateContent() to apply these properties to Content.

TwoStatesButtonWidget Class

This class corresponds to WidgetContentType.TwoStatesContent enum value and represents a widget that visualizes a button with ON and OFF states. This widget type is used by the CheckBoxField and provides the following properties:

Property	Description
OnStateContent	Provides the AnnotationContentSource used to visualize the selected state of the field in the PDF viewer. This property takes higher priority over AppearanceCharacteristics.
OffStateContent	Provides the AnnotationContentSource used to visualize the deselected state of the field in the PDF viewer. This property takes higher priority over AppearanceCharacteristics.
AppearanceCharacteristics	A ButtonAppearanceCharacteristics instance providing information on how to dynamically recalculate the widget appearance. Used only when AcroForm.ViewersShouldRecalculateWidgetAppearances is true. Call RecalculateContent() to apply these properties to OnStateContent and OffStateContent.

RadioButtonWidget Class

This class inherits the TwoStatesButtonWidget class and represents a widget that visualizes a radio button option. It is used by the RadioButtonField class and adds the following property to TwoStatesButtonWidget:

Property	Description
Option	The concrete RadioOption that this widget represents.

See Also

• AcroForm
• FormField
• Annotations Overview
• FormSource