Class PdfAnnotation

Namespace

nebulae.dotPDFium

Assembly

dotPDFium.dll

public class PdfAnnotation : PdfObject, IDisposable

Inheritance

object

PdfObject

PdfAnnotation

Implements

IDisposable

Derived

PdfLinkAnnotation

Inherited Members

PdfObject._handle

PdfObject._type

PdfObject._disposed

PdfObject.Handle

PdfObject.Type

PdfObject.IsDisposed

PdfObject.GetPDFiumError()

PdfObject.Dispose()

PdfObject.Dispose(bool)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

PdfAnnotation(nint, PdfPage)

Initializes a new instance of the PdfAnnotation class with the specified handle and associated page.

public PdfAnnotation(nint handle, PdfPage page)

Parameters

handle nint

A pointer to the native PDF annotation object. Must be a valid, non-null handle.

page PdfPage

The PdfPage object that this annotation is associated with. Cannot be null.

Remarks

The handle parameter is used to reference the underlying native PDF annotation object, and the page parameter links the annotation to a specific page in the PDF document.

Fields

_page

protected readonly PdfPage _page

Field Value

PdfPage

Properties

Subtype

Gets the subtype of the PDF annotation.

public PdfAnnotationSubtype Subtype { get; }

Property Value

PdfAnnotationSubtype

Remarks

The subtype indicates the specific type of the annotation, such as text, link, or highlight.

Methods

AddFileAttachment(string)

Adds a file attachment annotation to the PDF and returns a reference to the attached file.

public PdfFileSpec? AddFileAttachment(string name)

Parameters

name string

The name of the file attachment to be added. This name is used to identify the attachment in the PDF.

Returns

PdfFileSpec

A PdfFileSpec object representing the attached file if the operation is successful; otherwise, null.

Remarks

The method creates a file attachment annotation in the PDF document and associates it with the specified name. If the operation fails, the method returns null.

AddInkStroke(ReadOnlySpan<FsPointF>)

Adds an ink stroke to the annotation using the specified collection of points.

public int AddInkStroke(ReadOnlySpan<FsPointF> strokePoints)

Parameters

strokePoints ReadOnlySpan<FsPointF>

A read-only span of FsPointF representing the points that define the ink stroke. The span must contain at least one point.

Returns

int

An integer representing the result of the operation. The meaning of the return value depends on the underlying implementation.

Remarks

This method adds a new ink stroke to the annotation by passing the provided points to the underlying PDF annotation system. The caller must ensure that the span contains valid points to define the stroke.

Exceptions

ArgumentException

Thrown if strokePoints is empty.

AppendAttachmentPoints(FsQuadPointsF)

Appends an attachment point (quad) to the annotation. This is typically used for annotations like highlights, underlines, or squiggly lines.

public bool AppendAttachmentPoints(FsQuadPointsF quad)

Parameters

quad FsQuadPointsF

The quadrilateral to attach to the annotation.

Returns

bool

true if the quad was successfully appended; otherwise, false.

AppendObject(PdfPageObject)

Appends a specified PDF page object to the annotation.

public bool AppendObject(PdfPageObject obj)

Parameters

obj PdfPageObject

The PdfPageObject to append. This object must be valid and associated with the same document as the annotation.

Returns

bool

true if the object was successfully appended; otherwise, false.

Remarks

The appended object becomes part of the annotation and will be rendered as part of it. Ensure that the obj is properly initialized and compatible with the annotation before calling this method.

ClearInkStrokes()

Removes all ink strokes from the annotation.

public bool ClearInkStrokes()

Returns

bool

true if all ink strokes were successfully removed; otherwise, false.

Remarks

This method clears the ink list associated with the annotation. If the annotation does not contain any ink strokes, the method will return true without performing any action.

CommitChanges()

Commits any changes made to the annotation.

public void CommitChanges()

Remarks

This method finalizes modifications to the annotation and ensures that all changes are saved. After calling this method, the annotation handle is no longer valid and should not be used until or unless you call GetAnnotation() again.

GetAppearanceStreamName(PdfAnnotationAppearanceMode)

Retrieves the name of the appearance stream for the specified annotation appearance mode.

public string? GetAppearanceStreamName(PdfAnnotationAppearanceMode mode)

Parameters

mode PdfAnnotationAppearanceMode

The appearance mode for which to retrieve the stream name. This can be Normal, Rollover, or Down.

Returns

string

The name of the appearance stream as a string, or null if no appearance stream is defined for the specified mode.

Remarks

The appearance stream name is used to identify the visual representation of the annotation in the specified mode.

GetAttachmentPoint(int)

Retrieves the attachment point at the specified index.

public FsQuadPointsF? GetAttachmentPoint(int index)

Parameters

index int

The zero-based index of the attachment point to retrieve. Must be greater than or equal to 0.

Returns

FsQuadPointsF?

An FsQuadPointsF structure representing the attachment point if found; otherwise, null.

Exceptions

ArgumentOutOfRangeException

Thrown if index is less than 0.

GetAttachmentPointCount()

Gets the number of attachment points associated with the annotation.

public int GetAttachmentPointCount()

Returns

int

The total number of attachment points. Returns 0 if the annotation has no attachment points.

Remarks

Attachment points are specific locations within the annotation that can be used for positioning or other purposes.

GetBorder()

Retrieves the border characteristics of the PDF annotation.

public PdfAnnotationBorder? GetBorder()

Returns

PdfAnnotationBorder?

A PdfAnnotationBorder object representing the horizontal radius, vertical radius, and border width of the annotation, or null if the border information is unavailable.

GetColor()

Retrieves the color of the annotation as an RGBA value.

public RgbaColor GetColor()

Returns

RgbaColor

An RgbaColor representing the red, green, blue, and alpha components of the annotation's color.

Exceptions

dotPDFiumException

Thrown if the annotation color cannot be retrieved.

GetFileAttachment()

Retrieves the file attachment associated with the annotation, if any.

public PdfFileSpec? GetFileAttachment()

Returns

PdfFileSpec

A PdfFileSpec object representing the file attachment, or null if no file attachment is associated with the annotation.

GetInkStrokeCount()

Gets the number of ink strokes associated with the annotation.

public int GetInkStrokeCount()

Returns

int

The total number of ink strokes in the annotation. Returns 0 if no ink strokes are present.

Remarks

This method retrieves the count of ink strokes defined in the annotation's ink list. Use this method to determine how many individual strokes are part of the annotation.

GetInkStrokePoints(int)

Retrieves the list of points that define the ink stroke for the specified path index.

public IReadOnlyList<FsPointF> GetInkStrokePoints(int pathIndex)

Parameters

pathIndex int

The zero-based index of the ink stroke path to retrieve.

Returns

IReadOnlyList<FsPointF>

A read-only list of FsPointF objects representing the points in the ink stroke. Returns an empty list if the specified path index does not contain any points.

Remarks

This method retrieves the points for a specific ink stroke path associated with an annotation. The points are returned as a read-only list of FsPointF structures, which represent the coordinates of the ink stroke in the annotation's coordinate space.

GetLine()

Retrieves the start and end points of the line annotation, if available.

public (FsPointF Start, FsPointF End)? GetLine()

Returns

(FsPointF Start, FsPointF End)?

A tuple containing the start and end points of the line as FsPointF objects, or null if the line annotation is not defined or cannot be retrieved.

GetLink(PdfDocument)

If this annotation is a link, retrieves the associated link object handle.

public PdfLink? GetLink(PdfDocument context)

Parameters

context PdfDocument

Returns

PdfLink

The link handle if available, or Zero if not a link.

GetLinkedAnnotation(string)

Retrieves the annotation linked to the specified key.

public nint? GetLinkedAnnotation(string key)

Parameters

key string

The key identifying the linked annotation. Cannot be null or empty.

Returns

nint?

A pointer to the linked annotation if one exists; otherwise, null.

Remarks

This method returns a nullable nint to represent the linked annotation. If no linked annotation is found, the method returns null.

GetNumberValue(string)

Retrieves the numeric value for a given dictionary key on the annotation.

public float? GetNumberValue(string key)

Parameters

key string

The dictionary key (e.g. "F", "CA", etc.).

Returns

float?

The float value if the key is present, or null if not found or not numeric.

GetObject(int)

Retrieves the PdfPageObject at the specified index within the annotation.

public PdfPageObject? GetObject(int index)

Parameters

index int

The zero-based index of the object to retrieve. Must be within the valid range of objects in the annotation.

Returns

PdfPageObject

A PdfPageObject representing the object at the specified index, or null if no object exists at the given index.

GetObjectCount()

Gets the total number of objects associated with the annotation.

public int GetObjectCount()

Returns

int

The number of objects associated with the annotation. Returns 0 if no objects are present.

Remarks

This method retrieves the count of objects linked to the annotation represented by the current instance.

GetRect()

Retrieves the rectangular bounds of the annotation.

public FsRectF GetRect()

Returns

FsRectF

A FsRectF structure representing the annotation's rectangular bounds.

Exceptions

dotPDFiumException

Thrown if the annotation rectangle could not be retrieved.

GetStringValue(string)

Retrieves the string value associated with the specified key from the annotation.

public string? GetStringValue(string key)

Parameters

key string

The key identifying the string value to retrieve. This parameter cannot be null or whitespace.

Returns

string

The string value associated with the specified key, or null if the key does not exist or the value cannot be retrieved.

Remarks

The returned string is decoded from a null-terminated UTF-8 byte array. If the key is not found or the retrieval fails, the method returns null.

Exceptions

ArgumentNullException

Thrown if key is null or consists only of whitespace.

GetSubtype()

Retrieves the subtype of the PDF annotation represented by this instance.

public PdfAnnotationSubtype GetSubtype()

Returns

PdfAnnotationSubtype

A PdfAnnotationSubtype value representing the annotation's subtype.

Exceptions

dotPDFiumException

Thrown if the annotation subtype is not recognized or is not defined in the PdfAnnotationSubtype enumeration.

GetValueType(string)

Retrieves the type of the value associated with the specified key in the PDF annotation.

public PdfValueType GetValueType(string key)

Parameters

key string

The key identifying the value whose type is to be retrieved. Cannot be null or empty.

Returns

PdfValueType

A PdfValueType representing the type of the value associated with the specified key.

Remarks

This method queries the underlying PDF annotation to determine the type of the value associated with the given key. Ensure that the key exists in the annotation to avoid unexpected results.

GetVertices()

Retrieves the vertices of the annotation as a read-only list of points.

public IReadOnlyList<FsPointF> GetVertices()

Returns

IReadOnlyList<FsPointF>

A read-only list of FsPointF representing the vertices of the annotation. The list will be empty if no vertices are defined.

Remarks

This method returns the vertices of the annotation, represented as a collection of FsPointF structures. If the annotation does not have any vertices, an empty list is returned.

HasAttachmentPoints()

Determines whether the annotation has attachment points.

public bool HasAttachmentPoints()

Returns

bool

true if the annotation has attachment points; otherwise, false.

Remarks

Attachment points are specific locations associated with the annotation, such as coordinates or markers, that may be used for positioning or rendering purposes.

HasKey(string)

Determines whether the annotation contains a specific key.

public bool HasKey(string key)

Parameters

key string

The name of the key to check for. This value cannot be null or empty.

Returns

bool

true if the annotation contains the specified key; otherwise, false.

IsObjectSupportedSubtype(PdfAnnotationSubtype)

Determines whether the specified annotation subtype is supported.

public static bool IsObjectSupportedSubtype(PdfAnnotationSubtype subtype)

Parameters

subtype PdfAnnotationSubtype

The annotation subtype to check for support.

Returns

bool

true if the specified annotation subtype is supported; otherwise, false.

IsSupportedSubtype()

Determines whether the annotation's subtype is supported.

public bool IsSupportedSubtype()

Returns

bool

true if the annotation's subtype is supported; otherwise, false.

Remarks

This method checks if the current annotation's subtype is recognized and supported by the underlying system.

RemoveObject(int)

Removes an object at the specified index from the annotation.

public bool RemoveObject(int index)

Parameters

index int

The zero-based index of the object to remove.

Returns

bool

true if the object was successfully removed; otherwise, false.

Remarks

This method attempts to remove an object from the annotation at the specified index. If the index is invalid or the removal operation fails, the method returns false.

SetAppearanceStream(PdfAnnotationAppearanceMode, string)

Sets the appearance stream for the annotation based on the specified mode and name.

public bool SetAppearanceStream(PdfAnnotationAppearanceMode mode, string name)

Parameters

mode PdfAnnotationAppearanceMode

The appearance mode to set, such as normal, rollover, or down.

name string

The name of the appearance stream to apply. This value cannot be null or empty.

Returns

bool

true if the appearance stream was successfully set; otherwise, false.

SetAttachmentPoints(int, FsQuadPointsF)

Sets the attachment points for the annotation at the specified index.

public bool SetAttachmentPoints(int index, FsQuadPointsF quad)

Parameters

index int

The zero-based index of the attachment point to set.

quad FsQuadPointsF

The quadrilateral points defining the attachment area.

Returns

bool

true if the attachment points were successfully set; otherwise, false.

Remarks

The attachment points define the area associated with the annotation. Ensure that the quad parameter is properly initialized before calling this method.

SetBorder(float, float, float)

Sets the border properties for the annotation, including corner radii and border width.

public bool SetBorder(float horizontalRadius, float verticalRadius, float borderWidth)

Parameters

horizontalRadius float

The horizontal radius of the annotation's border corners. Must be non-negative.

verticalRadius float

The vertical radius of the annotation's border corners. Must be non-negative.

borderWidth float

The width of the annotation's border. Must be non-negative.

Returns

bool

true if the border properties were successfully set; otherwise, false.

Remarks

This method modifies the visual appearance of the annotation by setting its border properties. Ensure that the annotation handle is valid before calling this method.

SetColor(RgbaColor)

Sets the color of the annotation using the specified RGBA color.

public void SetColor(RgbaColor color)

Parameters

color RgbaColor

The RgbaColor structure representing the red, green, blue, and alpha components of the color to apply to the annotation.

Exceptions

dotPDFiumException

Thrown if the operation fails to set the annotation color.

SetRect(FsRectF)

Sets the rectangular bounds of the annotation.

public void SetRect(FsRectF rect)

Parameters

rect FsRectF

The rectangle defining the bounds of the annotation. Must be a valid FsRectF structure.

Exceptions

dotPDFiumException

Thrown if the rectangle could not be set due to an internal error.

SetUri(string)

Sets the URI associated with the annotation.

public bool SetUri(string uri)

Parameters

uri string

The URI to associate with the annotation. Must not be null, empty, or consist only of whitespace.

Returns

bool

true if the URI was successfully set; otherwise, false.

Exceptions

ArgumentException

Thrown if uri is null, empty, or consists only of whitespace.

UpdateObject(PdfPageObject)

Updates the specified PDF page object within the annotation.

public bool UpdateObject(PdfPageObject obj)

Parameters

obj PdfPageObject

The PdfPageObject to update. This parameter cannot be null.

Returns

bool

true if the object was successfully updated; otherwise, false.

Exceptions

ArgumentNullException

Thrown if obj is null.