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 color. Color 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 AddSquareAnnotation(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 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 color, written into /C.

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

FillRed, FillGreen, FillBlue — RGB components (0–1) of the interior fill color. 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, color, contents, or border after creation, use SetAnnotRect, SetAnnotBorderColor, SetAnnotContents, and SetAnnotBorderStyle.