AddSquareAnnotation

Annotations and hotspot links

Description

Adds a rectangular markup annotation (PDF /Subtype /Square) to the selected page. The annotation draws a stroked rectangle inscribed in the given bounding rectangle and 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.AddSquareAnnotation(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 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

BorderWidth — Stroke width of the rectangle 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 rectangle 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 /Square, /Rect, /C, /IC (when Filled), /BS, /Border, /CA, /F = 4 (printable), /M, /CreationDate, /NM, /T, /Contents, /Subj = "Rectangle", /P. This matches what Adobe Acrobat and Foxit produce for their rectangle review tools, so external review workflows can locate, edit, comment on, and reply to the resulting annotation.

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