An annotation. More...

#include <SignDocSDK-c.h>

Public Member Functions
void	SIGNDOC_Annotation_delete (struct SIGNDOC_Annotation *aObj)
	SIGNDOC_Annotation destructor. More...

int	SIGNDOC_Annotation_getType (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Annotation aObj)
	Get the type of the annotation. More...

char *	SIGNDOC_Annotation_getName (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Annotation aObj, int aEncoding)
	Get the name of the annotation. More...

int	SIGNDOC_Annotation_getPage (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Annotation aObj)
	Get the page number of the annotation. More...

int	SIGNDOC_Annotation_getBoundingBox (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Annotation aObj, struct SIGNDOC_Rect *aOutput)
	Get the bounding box of the annotation. More...

int	SIGNDOC_Annotation_setName (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, int aEncoding, const char *aName)
	Set the name of the annotation. More...

int	SIGNDOC_Annotation_setNameW (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, const wchar_t *aName)
	Set the name of the annotation. More...

int	SIGNDOC_Annotation_setLineEnding (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, int aStart, int aEnd)
	Set line ending styles. More...

int	SIGNDOC_Annotation_setColor (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, const struct SIGNDOC_Color *aColor)
	Set the foreground color of the annotation. More...

int	SIGNDOC_Annotation_setBackgroundColor (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, const struct SIGNDOC_Color *aColor)
	Set the background color of the annotation. More...

int	SIGNDOC_Annotation_setBorderColor (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, const struct SIGNDOC_Color *aColor)
	Set the border color of the annotation. More...

int	SIGNDOC_Annotation_setOpacity (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, double aOpacity)
	Set the opacity of the annotation. More...

int	SIGNDOC_Annotation_setLineWidthInPoints (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, double aWidth)
	Set line width in points. More...

int	SIGNDOC_Annotation_setBorderLineWidthInPoints (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, double aWidth)
	Set border line width in points. More...

int	SIGNDOC_Annotation_newStroke (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj)
	Start a new stroke in a scribble annotation. More...

int	SIGNDOC_Annotation_addPoint (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, const struct SIGNDOC_Point *aPoint)
	Add a point to the current stroke of a scribble annotation. More...

int	SIGNDOC_Annotation_addPointXY (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, double aX, double aY)
	Add a point to the current stroke of a scribble annotation. More...

int	SIGNDOC_Annotation_setPlainText (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, int aEncoding, const char aText, const char aFont, double aFontSize, int aHAlignment)
	Set the text of a text annotation. More...

int	SIGNDOC_Annotation_getPlainText (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, int aEncoding, char **aText)
	Get the text of a text annotation. More...

int	SIGNDOC_Annotation_getFont (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, int aEncoding, char *aFont, double aFontSize)
	Get the font of a text annotation. More...

int	SIGNDOC_Annotation_setFlags (struct SIGNDOC_Exception *aEx, struct SIGNDOC_Annotation aObj, int aFlags)
	Set flags. More...

const char *	SIGNDOC_Annotation_getErrorMessage (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Annotation aObj, int aEncoding)
	Get an error message for the last function call. More...

const wchar_t *	SIGNDOC_Annotation_getErrorMessageW (struct SIGNDOC_Exception *aEx, const struct SIGNDOC_Annotation aObj)
	Get an error message for the last function call. More...

Detailed Description

An annotation.

Currently, annotations are supported for PDF documents only.

See also: SIGNDOC_Document_createLineAnnotation(), SIGNDOC_Document_createScribbleAnnotation(), SIGNDOC_Document_createFreeTextAnnotation(), SIGNDOC_Document_getAnnotation()

Member Function Documentation

int SIGNDOC_Annotation_addPoint	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		const struct SIGNDOC_Point *	aPoint
	)

Add a point to the current stroke of a scribble annotation.

This function can be used for annotations of type SIGNDOC_ANNOTATION_TYPE_SCRIBBLE. Each stroke must contain at least two points. This function uses document (page) coordinates, see Coordinate Systems.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aPoint	The point to be added.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SIGNDOC_Annotation_newStroke()

int SIGNDOC_Annotation_addPointXY	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		double	aX,
		double	aY
	)

Add a point to the current stroke of a scribble annotation.

This function can be used for annotations of type SIGNDOC_ANNOTATION_TYPE_SCRIBBLE. Each stroke must contain at least two points. This function uses document (page) coordinates, see Coordinate Systems.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aX	The X coordinate of the point.
[in]	aY	The Y coordinate of the point.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SIGNDOC_Annotation_newStroke()

void SIGNDOC_Annotation_delete ( struct SIGNDOC_Annotation * aObj )

SIGNDOC_Annotation destructor.

Parameters

[in] aObj A pointer to the SIGNDOC_Annotation object.

int SIGNDOC_Annotation_getBoundingBox	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Annotation *	aObj,
		struct SIGNDOC_Rect *	aOutput
	)

Get the bounding box of the annotation.

The bounding box is available for objects returned by SIGNDOC_Document_getAnnotation() only.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[out]	aOutput	The bounding box (using document coordinates, see Coordinate Systems) will be stored here.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

const char * SIGNDOC_Annotation_getErrorMessage	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Annotation *	aObj,
		int	aEncoding
	)

Get an error message for the last function call.

Note: Do not call SIGNDOC_free() on the return value.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aEncoding	The encoding to be used for the error message (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).

Returns: A pointer to a string describing the reason for the failure of the last function call. The string is empty if the last call succeeded. The pointer is valid until aObj is destroyed or a member function of aObj is called.

See also: SIGNDOC_Annotation_getErrorMessageW()

const wchar_t * SIGNDOC_Annotation_getErrorMessageW	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Annotation *	aObj
	)

Get an error message for the last function call.

Note: Do not call SIGNDOC_free() on the return value.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.

Returns: A pointer to a string describing the reason for the failure of the last function call. The string is empty if the last call succeeded. The pointer is valid until aObj is destroyed or a member function of aObj is called.

See also: SIGNDOC_Annotation_getErrorMessage()

int SIGNDOC_Annotation_getFont	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		int	aEncoding,
		char **	aFont,
		double *	aFontSize
	)

Get the font of a text annotation.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aEncoding	The encoding to be used for the font name returned in aFont (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[out]	aFont	A pointer to the font name will be stored here. The string must be freed with SIGNDOC_free().
[out]	aFontSize	The font size in user space units will be stored here.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SIGNDOC_Annotation_getPlainText(), SIGNDOC_Annotation_setPlainText(), SIGNDOC_free

char * SIGNDOC_Annotation_getName	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Annotation *	aObj,
		int	aEncoding
	)

Get the name of the annotation.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aEncoding	The encoding to be used for the return value (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).

Returns: The name of the annotation or an empty string if the name is not available If flag SIGNDOC_DOCUMENT_FLAGS_KEEP_ESCAPE_SEQUENCES is set, the string may contain escape sequences for selecting natural languages. The string must be freed with SIGNDOC_free().

See also: SIGNDOC_free()

int SIGNDOC_Annotation_getPage	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Annotation *	aObj
	)

Get the page number of the annotation.

The page number is available for objects returned by SIGNDOC_Document_getAnnotation() only.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.

Returns: the 1-based page number of the annotation or 0 if the page number is not available.

int SIGNDOC_Annotation_getPlainText	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		int	aEncoding,
		char **	aText
	)

Get the text of a text annotation.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aEncoding	The encoding to be used for the text returned in aText (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[out]	aText	A pointer to the text will be stored here. The start of a new paragraph (except for the first one) is represented by CR and/or LF characters. If flag SIGNDOC_DOCUMENT_FLAGS_KEEP_ESCAPE_SEQUENCES is set, the string may contain escape sequences for selecting natural languages. The string must be freed with SIGNDOC_free().

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SIGNDOC_Annotation_getFont(), SIGNDOC_Annotation_setPlainText(), SIGNDOC_free()

int SIGNDOC_Annotation_getType	(	struct SIGNDOC_Exception **	aEx,
		const struct SIGNDOC_Annotation *	aObj
	)

Get the type of the annotation.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.

Returns

The type of the annotation:

int SIGNDOC_Annotation_newStroke	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj
	)

Start a new stroke in a scribble annotation.

This function can be used for annotations of type SIGNDOC_ANNOTATION_TYPE_SCRIBBLE. Each stroke must contain at least two points. This function need not be called for the first stroke of a scribble annotation.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SGINDOC_Annotation_addPoint()

int SIGNDOC_Annotation_setBackgroundColor	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		const struct SIGNDOC_Color *	aColor
	)

Set the background color of the annotation.

This function can be used for annotations of type SIGNDOC_ANNOTATION_TYPE_FREETEXT.

The default background color is white.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aColor	The background color of the annotation.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

int SIGNDOC_Annotation_setBorderColor	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		const struct SIGNDOC_Color *	aColor
	)

Set the border color of the annotation.

This function can be used for annotations of type SIGNDOC_ANNOTATION_TYPE_FREETEXT.

The default border color is black.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aColor	The border color of the annotation.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SIGNDOC_Annotation_setBorderLineWidthInPoints()

int SIGNDOC_Annotation_setBorderLineWidthInPoints	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		double	aWidth
	)

Set border line width in points.

This function can be used for annotations of type SIGNDOC_ANNOTATION_TYPE_FREETEXT. The default border line width for PDF documents is 1 point.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aWidth	The border line width in points (1/72 inch). If this value is negative, no border lines will be drawn.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SIGNDOC_Annotation_setBorderColor()

int SIGNDOC_Annotation_setColor	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		const struct SIGNDOC_Color *	aColor
	)

Set the foreground color of the annotation.

This function can be used for annotations of types SIGNDOC_ANNOTATION_TYPE_LINE, SIGNDOC_ANNOTATION_TYPE_SCRIBBLE, and SIGNDOC_ANNOTATION_TYPE_FREETEXT.

The default foreground color is black.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aColor	The foreground color of the annotation.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

int SIGNDOC_Annotation_setFlags	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		int	aFlags
	)

Set flags.

This function can be used for annotations of type SIGNDOC_ANNOTATION_TYPE_FREETEXT. Initially, no flag is set.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aFlags	See SIGNDOC_ANNOTATION_FLAGS_AUTO_ALIGNMENT, SIGNDOC_ANNOTATION_FLAGS_LTR, SIGNDOC_ANNOTATION_FLAGS_RTL, SIGNDOC_ANNOTATION_FLAGS_DEFAULT_LTR, and SIGNDOC_ANNOTATION_FLAGS_DEFAULT_RTL.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SIGNDOC_Annotation_setPlainText()

int SIGNDOC_Annotation_setLineEnding	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		int	aStart,
		int	aEnd
	)

Set line ending styles.

This function can be used for annotations of type SIGNDOC_ANNOTATION_TYPE_LINE. The default line ending style is SIGNDOC_ANNOTATION_LINEENDING_NONE.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aStart	Line ending style for start point (SIGNDOC_ANNOTATION_LINEENDING_NONE or SIGNDOC_ANNOTATION_LINEENDING_ARROW).
[in]	aEnd	Line ending style for end point (SIGNDOC_ANNOTATION_LINEENDING_NONE or SIGNDOC_ANNOTATION_LINEENDING_ARROW).

Returns: SIGNDOC_RETURNCODE_OK iff successful.

int SIGNDOC_Annotation_setLineWidthInPoints	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		double	aWidth
	)

Set line width in points.

This function can be used for annotations of types SIGNDOC_ANNOTATION_TYPE_LINE and SIGNDOC_ANNOTATION_TYPE_SCRIBBLE. The default line width for PDF documents is 1 point.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aWidth	The line width in points (1/72 inch).

Returns: SIGNDOC_RETURNCODE_OK iff successful.

int SIGNDOC_Annotation_setName	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		int	aEncoding,
		const char *	aName
	)

Set the name of the annotation.

In PDF documents, an annotation can have a name. The names of annotations must be unique within a page. By default, annotations are unnamed.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aEncoding	The encoding of aName (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[in]	aName	The name of the annotation.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

int SIGNDOC_Annotation_setNameW	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		const wchar_t *	aName
	)

Set the name of the annotation.

In PDF documents, an annotation can have a name. The names of annotations must be unique within a page. By default, annotations are unnamed.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aName	The name of the annotation.

Returns: SIGNDOC_RETURNCODE_OK iff successful.

int SIGNDOC_Annotation_setOpacity	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		double	aOpacity
	)

Set the opacity of the annotation.

This function can be used for annotations of types SIGNDOC_ANNOTATION_TYPE_LINE, SIGNDOC_ANNOTATION_TYPE_SCRIBBLE, and SIGNDOC_ANNOTATION_TYPE_FREETEXT.

The default opacity is 1.0. Documents conforming to PDF/A-1 must use an opacity of 1.0.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aOpacity	The opacity, 0.0 (transparent) through 1.0 (opaque).

Returns: SIGNDOC_RETURNCODE_OK iff successful.

int SIGNDOC_Annotation_setPlainText	(	struct SIGNDOC_Exception **	aEx,
		struct SIGNDOC_Annotation *	aObj,
		int	aEncoding,
		const char *	aText,
		const char *	aFont,
		double	aFontSize,
		int	aHAlignment
	)

Set the text of a text annotation.

This function can be used for annotations of type SIGNDOC_ANNOTATION_TYPE_FREETEXT.

Any sequence of CR and LF characters in the text starts a new paragraph (ie, text following such a sequence will be placed at the beginning of the next output line). In consequence, empty lines in the input do not produce empty lines in the output. To get an empty line in the output, you have to add a paragraph containing a non-breaking space (0xa0) only:

"Line before empty line\n\xa0\nLine after empty line"

Complex scripts are supported, see Complex Scripts. By default, this function uses paragraph direction LTR. Use SIGNDOC_Annotation_setFlags() if you need to set a different paragraph direction.

Parameters

[out]	aEx	Any exception will be returned in the object pointed to by this parameter.
[in]	aObj	A pointer to the SIGNDOC_Annotation object.
[in]	aEncoding	The encoding of aText and aFont (SIGNDOC_ENCODING_NATIVE, SIGNDOC_ENCODING_UTF_8, or SIGNDOC_ENCODING_LATIN_1).
[in]	aText	The text. Allowed control characters are CR and LF. Any sequence of CR and LF characters starts a new paragraph. Escape sequences must not be used.
[in]	aFont	The name of the font to be used. The font substitition rules of the loaded font configuration files will be used. The resulting font must be a standard PDF font or a font for which a file is specified in the font configuration files.
[in]	aFontSize	The font size in user space units.
[in]	aHAlignment	Horizontal alignment of the text (SIGNDOC_ANNOTATION_HALIGNMENT_LEFT, SIGNDOC_ANNOTATION_HALIGNMENT_CENTER, or SIGNDOC_ANNOTATION_HALIGNMENT_RIGHT).

Returns: SIGNDOC_RETURNCODE_OK iff successful.

See also: SIGNDOC_Annotation_getFont(), SIGNDOC_Annotation_getPlainText(), SIGNDOC_Annotation_setFlags(), SIGNDOC_DocumentLoader_loadFontConfigBlob(), SIGNDOC_DocumentLoader_loadFontConfigEnvironment(), SIGNDOC_DocumentLoader_loadFontConfigFile(), SIGNDOC_DocumentLoader_loadFontConfigStream()

The documentation for this class was generated from the following file:

SignDocSDK-c.h

Public Member Functions

Detailed Description

Member Function Documentation