AddCircleAnnotation

Annotations and hotspot links

Description

Adds an ellipse markup annotation (PDF /Subtype /Circle) inscribed in the given rectangle. Despite the name, the annotation is a full ellipse and only renders as a true circle when Width equals Height. The annotation can optionally be filled with a solid interior colour. 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). Because this entry point emits the PDF 1.4 annotation /CA opacity key, the library raises lower unlocked documents to PDF 1.4 before saving; locked lower targets are rejected by the compatibility gate. Defined in ISO 32000-1 §12.5.6.8.

Syntax

int AddCircleAnnotation(double Left, double Top, double Width, double Height, double BorderWidth, double BorderRed, double BorderGreen, double BorderBlue, int Filled, double FillRed, double FillGreen, double FillBlue, wchar_t * Title, wchar_t * Contents, int Transparency);

Parameters

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

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

Width — Width of the bounding rectangle.

Height — Height of the bounding rectangle.

BorderWidth — Stroke width of the ellipse border, in current units. Written into both the /Border legacy field and the /BS border-style dictionary.

BorderRed, BorderGreen, BorderBlue — RGB components (0–1) of the stroke colour, written into /C.

Filled — 1 to emit an interior fill colour (/IC), 0 to leave the ellipse unfilled.

FillRed, FillGreen, FillBlue — RGB components (0–1) of the interior fill colour. Ignored when Filled is 0.

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 a standard markup field set: /Type /Annot, /Subtype /Circle, /Rect, /C, /IC (when Filled), /BS, /Border, /CA, /F = 4 (printable), /M, /CreationDate, /NM, /T, /Contents, /Subj = "Ellipse", /P. This matches what Adobe Acrobat and Foxit produce for their ellipse review tools, so external review workflows can locate, edit, comment on, and reply to the resulting annotation.

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