PdfAnnotation Class

An annotation of a page (ISO 32000-2, 12.5): a link, a note, a form field widget, ...

public class PdfAnnotation

Remarks

The class cannot be derived outside the library. Each type of annotation the specification defines has its class: PdfLinkAnnotation, PdfWidgetAnnotation, PdfPopupAnnotation, PdfFileAttachmentAnnotation, and the markup annotations, which derive from PdfMarkupAnnotation (PdfTextAnnotation, PdfFreeTextAnnotation, PdfLineAnnotation, PdfInkAnnotation, ...). The annotations of other types are instances of this class. The properties read and write the annotation dictionary directly.

Properties

NameDescription
AdditionalActionsGets the additional actions of the annotation (/AA, ISO 32000-2, 12.6.3): the actions run when the mouse enters or leaves it, when it gets or loses the focus, when its page is opened... A widget also has the actions of its field when the field and the widget are the same dictionary (PdfActionTrigger.Keystroke, PdfActionTrigger.Format, PdfActionTrigger.Validate, PdfActionTrigger.Calculate).
BorderGets the border of the annotation (/BS, /Border and /BE, 12.5.4): its width, its style, its dashes and its cloudy effect.
ColorGets or sets the color of the annotation (/C, 12.5.2): the background of its icon, the title bar of its pop-up window, the border of a link or of a shape, the color of a text markup; null when it is transparent or has none. Changing it does not change an appearance stream the annotation already has: call PdfAnnotation.UpdateAppearance.
ContentsGets or sets the text of the annotation, or an alternate description of its content.
DictionaryGets the annotation dictionary.
FlagsGets or sets the flags of the annotation (/F, 12.5.3): whether it is printed, hidden, locked... The bits the enumeration does not name are kept.
HasAppearanceGets a value indicating whether the annotation has a normal appearance (/AP /N, 12.5.5), a stream or a dictionary of appearance states.
ModificationDateGets or sets the date the annotation was last modified (/M, 12.5.2), or null when it has none or it is not a valid date.
OptionalContentGets or sets the optional content group (the layer) the annotation belongs to (/OC, ISO 32000-2, 8.11.3.3): the annotation is shown when the group is on. null when the annotation has none, or when it belongs to an optional content membership dictionary (read PdfAnnotation.Dictionary).
PageGets the page of the annotation.
RectangleGets or sets the location of the annotation on the page, in default user space.
ReferenceGets the reference to the annotation, or null for a direct object (which the specification does not allow, but some files have).
SubtypeGets the type of the annotation, such as Link, Text or Widget.
UniqueNameGets or sets the name of the annotation (/NM, 12.5.2): a text that identifies it among the annotations of its page.

AdditionalActions

PdfAnnotation.cs

Gets the additional actions of the annotation (/AA, ISO 32000-2, 12.6.3): the actions run when the mouse enters or leaves it, when it gets or loses the focus, when its page is opened... A widget also has the actions of its field when the field and the widget are the same dictionary (PdfActionTrigger.Keystroke, PdfActionTrigger.Format, PdfActionTrigger.Validate, PdfActionTrigger.Calculate).

public PdfAdditionalActions AdditionalActions { get; }

Property value

PdfAdditionalActions

Gets the border of the annotation (/BS, /Border and /BE, 12.5.4): its width, its style, its dashes and its cloudy effect.

public PdfAnnotationBorder Border { get; }

Property value

PdfAnnotationBorder

Gets or sets the color of the annotation (/C, 12.5.2): the background of its icon, the title bar of its pop-up window, the border of a link or of a shape, the color of a text markup; null when it is transparent or has none. Changing it does not change an appearance stream the annotation already has: call PdfAnnotation.UpdateAppearance.

public PdfColor? Color { get; set; }

Property value

PdfColor?

Gets or sets the text of the annotation, or an alternate description of its content.

public string? Contents { get; set; }

Property value

string?

Gets the annotation dictionary.

public PdfDictionary Dictionary { get; }

Property value

PdfDictionary

Gets or sets the flags of the annotation (/F, 12.5.3): whether it is printed, hidden, locked... The bits the enumeration does not name are kept.

public PdfAnnotationFlags Flags { get; set; }

Property value

PdfAnnotationFlags

HasAppearance

PdfAnnotation.cs

Gets a value indicating whether the annotation has a normal appearance (/AP /N, 12.5.5), a stream or a dictionary of appearance states.

public bool HasAppearance { get; }

Property value

bool

ModificationDate

PdfAnnotation.cs

Gets or sets the date the annotation was last modified (/M, 12.5.2), or null when it has none or it is not a valid date.

public DateTimeOffset? ModificationDate { get; set; }

Property value

DateTimeOffset?

OptionalContent

PdfAnnotation.cs

Gets or sets the optional content group (the layer) the annotation belongs to (/OC, ISO 32000-2, 8.11.3.3): the annotation is shown when the group is on. null when the annotation has none, or when it belongs to an optional content membership dictionary (read PdfAnnotation.Dictionary).

public PdfOptionalContentGroup? OptionalContent { get; set; }

Property value

PdfOptionalContentGroup?

Exceptions

ArgumentException
The group belongs to another document.

Gets the page of the annotation.

public PdfPage Page { get; }

Property value

PdfPage

Gets or sets the location of the annotation on the page, in default user space.

public PdfRectangle Rectangle { get; set; }

Property value

PdfRectangle

Gets the reference to the annotation, or null for a direct object (which the specification does not allow, but some files have).

public PdfReference? Reference { get; }

Property value

PdfReference?

Gets the type of the annotation, such as Link, Text or Widget.

public string Subtype { get; }

Property value

string

Gets or sets the name of the annotation (/NM, 12.5.2): a text that identifies it among the annotations of its page.

public string? UniqueName { get; set; }

Property value

string?

Methods

NameDescription
UpdateAppearance()Replaces the appearance of the annotation (/AP, 12.5.5) with one drawn from its properties: its geometry, its colors, its border and its text. Call it after changing the properties of an annotation, since the viewers draw the appearance, not the properties.

UpdateAppearance()

PdfAnnotation.cs

Replaces the appearance of the annotation (/AP, 12.5.5) with one drawn from its properties: its geometry, its colors, its border and its text. Call it after changing the properties of an annotation, since the viewers draw the appearance, not the properties.

public bool UpdateAppearance()

Returns

bool true when the appearance was replaced; false when the library does not draw the annotations of this type (links, file attachments, sounds, ...), or the annotation has nothing to draw (no color, an empty rectangle): its appearance is left as it is.

Remarks

The rectangle of a line, a polygon, a polyline or an ink annotation is computed again from its points, with room for its width, its endings and its leader lines, so that a moved point is not clipped.

The widget of a text or a choice field gets the appearance of the value of its field, as setting the value does. The widgets of buttons keep their appearances, whose states (/AS) are the values of their fields: the method returns false for them.