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

Delphi

Function TPDFlib.AddCircleAnnotation(Left, Top, Width, Height: Double; BorderWidth: Double; BorderRed, BorderGreen, BorderBlue: Double; Filled: Integer; FillRed, FillGreen, FillBlue: Double; Const Title, Contents: WideString; Transparency: Integer): Integer;

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.