DynaPDF Manual - Page 185

Previous Page 184   Index   Next Page 186

Function Reference
Page 185 of 839
SI32 pdfCaretAnnot(
const PPDF* IPDF,
// Instance pointer
double PosX,
// X-Coordinate
double PosY,
// Y-Coordinate
double Width,
// Width of the annotation
double Height,
// Height of the annotation
UI32 Color,
// Color of the caret symbol
TPDFColorSpace CS,
// Color space in which the color is defined
const char* Author,
// Optional author
const char* Subject, // Optional subject
const char* Content) // Optional content
The function creates a caret annotation. This type of annotation is typically used to mark a position
on a page where a user should add or edit text.
If the coordinate system is bottom-up the point PosX, PosY defines the lower left corner of the
bounding rectangle. If the coordinate system is top-down it defines the upper left corner.
This annotation type has an associated PopUp annotation that displays the string Content in a
floating window. The initial window state of the associated PopUp annotation is closed by default
but the state can be changed with SetAnnotOpenState() if necessary.
The caret annotation is the only annotation type that can be rotated in 90 degrees steps like form
fields. This is not documented in the PDF specs but it works in all Acrobat and Reader versions.
To rotate the annotation call SetFieldOrientation(). Since this function requires normally a field
handle, the annotation handle must be marked as annotation handle with the constant
PDF_ANNOT_INDEX. The annotation handle must be added to the constant with a binary or
Example (C++):
SI32 a = pdfCaretAnnot(pdf, 50.0, 50.0, 20.0, 20.0, PDF_BLUE,
csDeviceRGB, "Jim Tester", "Test", "Test");
// Rotate the annotation 90 degrees
pdfSetFieldOrientation(pdf, a | PDF_ANNOT_INDEX, 90);
This function is implemented in an Ansi and Unicode compatible version.
Return values:
If the function succeeds the return value is the annotation handle, a value greater or equal zero. If
the function fails the return value is a negative error code.

Previous topic: CalcPagePixelSize (Rendering Engine), CalcWidthHeight

Next topic: ChangeAnnotName, ChangeAnnotPos