AddCaretAnnotation

Annotations and hotspot links

Description

Adds a caret markup annotation (PDF /Subtype /Caret) to the selected page. A caret annotation is a visual symbol that conventionally marks a position in the page where text or content has been inserted, omitted, or otherwise needs reviewer attention. Two symbol shapes are available: a plain caret (None) or a paragraph mark (Paragraph). Colour components and opacity are expressed on a 0–1 scale; Transparency is given on a 0–100 scale (0 = fully opaque, 100 = fully transparent). The library bumps the document version to PDF 1.5 when a Caret annotation is emitted under a lower minimum-version lock. Defined in ISO 32000-1 §12.5.6.11.

Syntax

int AddCaretAnnotation(double Left, double Top, double Width, double Height, int SymbolType, double ColorRed, double ColorGreen, double ColorBlue, wchar_t * Title, wchar_t * Contents, int Transparency);

Parameters

Left — Horizontal coordinate of the annotation rectangle's lower-left corner, in current units.

Top — Vertical coordinate of the annotation rectangle's lower-left corner, in current units.

Width — Width of the annotation rectangle.

Height — Height of the annotation rectangle.

SymbolType — Caret symbol style:

0 = None (plain caret "^")

1 = Paragraph (pilcrow "¶")

Any other value is treated as 0 (None).

ColorRed, ColorGreen, ColorBlue — RGB components (0–1) of the caret colour, written into /C.

Title — Author name written into the annotation's /T entry. Pass an empty string to skip.

Contents — Body of the popup associated with the annotation. Pass an empty string to skip.

Transparency — Opacity expressed as percentage transparent (0–100). The library converts this to PDF /CA = 1 - Transparency/100 and clamps to range.

Return Value

1 on success, 0 if no document is selected or the annotation could not be created.

Remarks

The annotation is emitted with /Type /Annot, /Subtype /Caret, /Rect, /Sy (the symbol name), /C, /CA, /F = 4 (printable), /M, /CreationDate, /NM, /T, /Contents, /Subj = "Caret", and /P. The optional /RD field (caret offset within /Rect) is not emitted; readers default it to all zeros so the caret occupies the full annotation rectangle.

To overwrite the annotation rectangle, colour, or contents after creation, use SetAnnotRect, SetAnnotBorderColor, and SetAnnotContents.