What namespace is FormFieldAnnotation defined in?

FormFieldAnnotation is in the IronSoftware.Forms namespace, shipped in IronPdf.dll. It derives from System.Object and is the sole concrete implementor of IFormFieldAnnotation, inheriting geometry from IFormFieldAnnotationObject. Instances are produced by the form-loading pipeline and read from the IFormField.Annotations collection.

What is the difference between FormFieldAnnotation and IFormFieldAnnotation?

IFormFieldAnnotation is the interface contract for a form field widget annotation; FormFieldAnnotation is the concrete class that implements it. FormFieldAnnotation is the sole concrete implementor in the IronSoftware.Forms namespace, so every entry in an IFormField.Annotations collection is a FormFieldAnnotation instance at runtime. Code that consumes annotations should accept the interface type; code that inspects or modifies them works against the concrete class through the interface.

What is the difference between FormFieldAnnotation and the form-field classes such as TextFormField?

A form-field class such as TextFormField, CheckboxFormField, or RadioFormField represents a whole fillable field with a Name, a Value, and behavior. A FormFieldAnnotation represents one on-page widget belonging to that field. A single field can own multiple FormFieldAnnotation instances, which is how a radio button group exposes its per-option widgets. The form-field class is reached through PdfDocument.Form, and its widgets are read from its Annotations property.

Can FormFieldAnnotation be instantiated directly with new?

The class exposes a public parameterless constructor, but the canonical idiom is to obtain instances from a loaded form. The form-reading pipeline populates the IFormField.Annotations collection with FormFieldAnnotation instances that already have their geometry, appearance state, page index, and parent FormField wired up. Constructing one with new produces an unattached widget that has no parent field or document context.

Class FormFieldAnnotation

Document form field annotation

Inheritance

System.Object

FormFieldAnnotation

Implements

IFormFieldAnnotation

IFormFieldAnnotationObject

IPdfDocumentObject

IronSoftware.Abstractions.Pdf.IPdfDocumentObject

IronSoftware.Abstractions.IDocumentObject

Namespace: IronSoftware.Forms

Assembly: IronPdf.dll

Syntax

public class FormFieldAnnotation : Object, IFormFieldAnnotation, IFormFieldAnnotationObject, IPdfDocumentObject, IPdfDocumentObject, IDocumentObject

FormFieldAnnotation is what you receive when you read a form field's Annotations collection and need the individual on-page widget that represents one instance of a fillable PDF form field in IronPDF. It inherits its geometry from IFormFieldAnnotationObject. FormFieldAnnotation is the sole concrete implementor of the annotation contract: every entry in a form field's Annotations collection is a FormFieldAnnotation instance at runtime.

The class matters whenever a form must be inspected or edited per widget rather than per field. A single fillable field can place multiple widgets across pages, and a radio group surfaces its individual options through Annotations, where each FormFieldAnnotation carries the AppearanceState (such as Yes or Off) that identifies which option that widget represents. Layout audits, per-page rendering checks, appearance customization, and form-flattening pipelines all read from these widget objects.

Members of FormFieldAnnotation fall into four functional buckets. Geometry comes from IFormFieldAnnotationObject: X, Y, Width, and Height are double get/set values in PDF user-space units. Appearance state is AnnotationFlags (a PdfAnnotationFlags value from IronSoftware.Pdfium), Appearances (read-only List<string> of named appearances the widget defines), AppearanceState (the active appearance name), and OnAppearance (the appearance shown when the widget is selected). Backreferences include FormField (the parent IFormFieldObject), Client, and DocumentId. Identity is ObjNum and PageIndex. The Javascript property holds an ECMAScript action the widget runs on user interaction, per ISO 21757-1:2020.

using IronPdf;
using IronSoftware.Forms;

PdfDocument pdf = PdfDocument.FromFile("application.pdf");

// Radio groups expose their option widgets as FormFieldAnnotation instances
// through the IFormField.Annotations collection.
IFormField shipping = pdf.Form.FindFormField("Shipping");
foreach (IFormFieldAnnotation widget in shipping.Annotations)
{
    // The runtime type of each entry is FormFieldAnnotation.
    // AppearanceState identifies which radio option this widget represents.
    System.Console.WriteLine(
        $"option={widget.AppearanceState} page={widget.PageIndex} " +
        $"at ({widget.X},{widget.Y}) size ({widget.Width}x{widget.Height})");
}

// Select the "Express" radio by assigning the parent field's Value.
shipping.Value = "Express";
pdf.SaveAs("application-filled.pdf");

For the field-level workflow that produces these widget objects, see the fill and edit PDF forms how-to. For building forms from scratch in code, the create PDF forms how-to is the entry point.

Constructors

FormFieldAnnotation()

Create a new form field annotation

Declaration

public FormFieldAnnotation()

Properties

AnnotationFlags

Annotation flags

Declaration

public PdfAnnotationFlags AnnotationFlags { get; set; }

Property Value

Type	Description
PdfAnnotationFlags

Appearances

Annotation appearance names

Declaration

public List<string> Appearances { get; protected set; }

Property Value

Type	Description
System.Collections.Generic.List<System.String>

AppearanceState

Current active appearance

Declaration

public string AppearanceState { get; set; }

Property Value

Type	Description
System.String

Client

Pdf client

Declaration

public IPdfClient Client { get; set; }

Property Value

Type	Description
IronSoftware.Pdfium.IPdfClient

DocumentId

Declaration

public IDocumentId DocumentId { get; set; }

Property Value

Type	Description
IronSoftware.Abstractions.Pdf.IDocumentId

FormField

Parent form

Declaration

public IFormFieldObject FormField { get; set; }

Property Value

Type	Description
IFormFieldObject

Height

Annotation height

Declaration

public double Height { get; set; }

Property Value

Type	Description
System.Double

Javascript

Javascript to execute when the annotation is interacted with

Declaration

public string Javascript { get; set; }

Property Value

Type	Description
System.String

Remarks

See ISO 21757-1:2020 for an ECMAScript reference

ObjNum

Declaration

public uint ObjNum { get; set; }

Property Value

Type	Description
System.UInt32

OnAppearance

Name of the appearance which is active when this annotation is selected

Declaration

public string OnAppearance { get; set; }

Property Value

Type	Description
System.String

PageIndex

Declaration

public uint PageIndex { get; set; }

Property Value

Type	Description
System.UInt32

Width

Annotation width

Declaration

public double Width { get; set; }

Property Value

Type	Description
System.Double

X

Annotation X position

Declaration

public double X { get; set; }

Property Value

Type	Description
System.Double

Y

Annotation y position

Declaration

public double Y { get; set; }

Property Value

Type	Description
System.Double

Implements

IFormFieldAnnotation

IFormFieldAnnotationObject

IPdfDocumentObject

IronSoftware.Abstractions.Pdf.IPdfDocumentObject

IronSoftware.Abstractions.IDocumentObject