AddInkAnnotation

Annotations and hotspot links

Description

Adds an ink markup annotation (PDF /Subtype /Ink) representing one or more handwritten strokes, freeform marks, or freehand sketches drawn on the page. The /InkList dictionary entry contains an array of strokes; each stroke is an array of alternating x/y coordinates representing the path traced by a pointing device between pen-down and pen-up events. 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.13.

Syntax

int AddInkAnnotation(wchar_t * InkPaths, double BorderWidth, double InkRed, double InkGreen, double InkBlue, wchar_t * Title, wchar_t * Contents, int Transparency);

Parameters

InkPaths — One or more strokes encoded as a single string. Strokes are separated by '|' or by a newline (CR / LF / CRLF). Within each stroke the coordinate pairs use the same delimiter convention as AddPolygonAnnotation: alternating x/y values separated by spaces, commas, semicolons, or tabs. Example: "100 100 110 105 120 110 | 200 200 210 205" describes two separate strokes. Each stroke must contain at least two coordinate pairs (four numbers) and an even total number of values, otherwise the call returns 0.

BorderWidth — Stroke width of the ink, in current units.

InkRed, InkGreen, InkBlue — RGB components (0–1) of the ink color, written into /C.

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, the ink string fails to parse to a valid stroke list, or the annotation could not be created.

Remarks

The annotation /Rect is computed automatically from the combined extent of all strokes plus a small padding proportional to the border width so the rendered strokes remain inside the annotation bounding box.

This entry point is suitable both for digitized handwriting captured from a touch / pen device and for programmatic freehand shapes such as scribbled signatures or annotations imported from other tools. To overwrite the ink color, border, contents, or rectangle after creation, use SetAnnotBorderColor, SetAnnotBorderStyle, SetAnnotContents, and SetAnnotRect.