AddLineAnnotation

Annotations and hotspot links

Description

Adds a line markup annotation (PDF /Subtype /Line) between two endpoints on the selected page. Each end can carry a different end-line style (arrow, square, circle, diamond, …) and the body of the line can be drawn in any RGB colour with configurable opacity. End decorations that have an interior (ClosedArrow, Square, Circle, Diamond) can optionally be filled. 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.7.

Syntax

int AddLineAnnotation(double StartLeft, double StartTop, double EndLeft, double EndTop, double BorderWidth, double LineRed, double LineGreen, double LineBlue, int StartStyle, int EndStyle, int Filled, double FillRed, double FillGreen, double FillBlue, wchar_t * Title, wchar_t * Contents, int Transparency);

Parameters

StartLeft, StartTop — Coordinates of the line's start endpoint, in current units.

EndLeft, EndTop — Coordinates of the line's end endpoint, in current units.

BorderWidth — Stroke width of the line and its end decorations, in current units.

LineRed, LineGreen, LineBlue — RGB components (0–1) of the line colour, written into /C.

StartStyle, EndStyle — End-line styles for the start and end endpoints respectively. Use one of:

0 = None, 1 = Square, 2 = Circle, 3 = Diamond, 4 = OpenArrow, 5 = ClosedArrow, 6 = Butt, 7 = ROpenArrow, 8 = RClosedArrow, 9 = Slash.

Out-of-range values clamp to 0 (None).

Filled — 1 to emit an interior fill colour (/IC) for the end decorations, 0 to leave them unfilled.

FillRed, FillGreen, FillBlue — RGB components (0–1) of the end-decoration 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 /Rect is automatically computed from the two endpoints plus a padding proportional to the border width so end decorations remain inside the annotation bounding box. PDF readers require the bounding /Rect to contain the entire visible drawing or end decorations may be clipped.

Optional advanced fields described by the PDF specification — /LL (leader length), /LLE, /LLO, /Cap, /CP, /CO, and /Measure — are not emitted by this entry point. They can be appended after creation by writing them onto the annotation dictionary directly.

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