An annotation. More...

#include <SignDocSDK-cpp.h>

Public Types
enum	Type { t_unknown, t_line, t_scribble, t_freetext }
	Annotation types. More...

enum	LineEnding { le_unknown, le_none, le_arrow }
	Line ending styles. More...

enum	HAlignment { ha_left, ha_center, ha_right }
	Horizontal alignment. More...

enum	Flags { f_auto_alignment = 0x200, f_ltr = 0x1000, f_rtl = 0x2000, f_default_ltr = 0x4000, f_default_rtl = 0x8000 }
	Flags for setFlags(). More...

Public Member Functions
	~SignDocAnnotation ()
	Destructor. More...

Type	getType () const
	Get the type of the annotation. More...

std::string	getName (Encoding aEncoding) const
	Get the name of the annotation. More...

int	getPage () const
	Get the page number of the annotation. More...

ReturnCode	getBoundingBox (Rect &aOutput) const
	Get the bounding box of the annotation. More...

ReturnCode	setName (Encoding aEncoding, const std::string &aName)
	Set the name of the annotation. More...

ReturnCode	setName (const wchar_t *aName)
	Set the name of the annotation. More...

ReturnCode	setLineEnding (LineEnding aStart, LineEnding aEnd)
	Set line ending styles. More...

ReturnCode	setColor (const SignDocColor &aColor)
	Set the foreground color of the annotation. More...

ReturnCode	setBackgroundColor (const SignDocColor &aColor)
	Set the background color of the annotation. More...

ReturnCode	setBorderColor (const SignDocColor &aColor)
	Set the border color of the annotation. More...

ReturnCode	setOpacity (double aOpacity)
	Set the opacity of the annotation. More...

ReturnCode	setLineWidthInPoints (double aWidth)
	Set line width in points. More...

ReturnCode	setBorderLineWidthInPoints (double aWidth)
	Set border line width in points. More...

ReturnCode	newStroke ()
	Start a new stroke in a scribble annotation. More...

ReturnCode	addPoint (const Point &aPoint)
	Add a point to the current stroke of a scribble annotation. More...

ReturnCode	addPoint (double aX, double aY)
	Add a point to the current stroke of a scribble annotation. More...

ReturnCode	setPlainText (Encoding aEncoding, const std::string &aText, const std::string &aFont, double aFontSize, HAlignment aHAlignment)
	Set the text of a text annotation. More...

ReturnCode	getPlainText (Encoding aEncoding, std::string &aText)
	Get the text of a text annotation. More...

ReturnCode	getFont (Encoding aEncoding, std::string &aFont, double &aFontSize)
	Get the font of a text annotation. More...

ReturnCode	setFlags (int aFlags)
	Set flags. More...

const char *	getErrorMessage (Encoding aEncoding) const
	Get an error message for the last function call. More...

const wchar_t *	getErrorMessageW () const
	Get an error message for the last function call. More...

	SignDocAnnotation (SIGNDOC_Annotation *aP)
	Internal function. More...

SIGNDOC_Annotation *	getImpl ()
	Internal function. More...

const SIGNDOC_Annotation *	getImpl () const
	Internal function. More...

void	setImpl (SIGNDOC_Annotation *aP)
	Internal function. More...

Protected Member Functions
	SignDocAnnotation ()
	Constructor. More...

Detailed Description

An annotation.

Currently, annotations are supported for PDF documents only.

See also: SignDocDocument::createLineAnnotation(), SignDocDocument::createScribbleAnnotation(), SignDocDocument::createFreeTextAnnotation(), SignDocDocument::getAnnotation()

Member Enumeration Documentation

enum Flags

Flags for setFlags().

Enumerator
f_auto_alignment	Align left if the text begins with an LTR run, align right if the text begins with an RTL run. This flag overrides for creating the appearance stream ha_left and ha_right passed to aHAlignment of setPlainText(). This flag is ignored for ha_center.
f_ltr	Paragraph direction: LTR. If none of f_ltr, f_rtl, f_default_ltr, and f_default_rtl is set, f_ltr will be used. At most one of f_ltr, f_rtl, f_default_ltr, and f_default_rtl can be set. See also f_auto_alignment
f_rtl	Paragraph direction: RTL. If none of f_ltr, f_rtl, f_default_ltr, and f_default_rtl is set, f_ltr will be used. At most one of f_ltr, f_rtl, f_default_ltr, and f_default_rtl can be set. Usage of f_rtl is not recommended as the visual representation of the text of the annotation may not match the plain text of the annotation (as interpreted by software which does not know that the paragraph direction is supposed to be RTL). Use f_rtl only as last resort if you cannot modify the text received from an RTL input field appropriately for paragraph direction LTR used in PDF annotations. See also f_auto_alignment
f_default_ltr	Choose direction automatically, default to LTR. The base direction of each paragraph (BiDi paragraph level) will depend on the first strong directional character in the paragraph. The paragraph level will be 0 (LTR) for paragraphs having no strong directional character. If none of f_ltr, f_rtl, f_default_ltr, and f_default_rtl is set, f_ltr will be used. At most one of f_ltr, f_rtl, f_default_ltr, and f_default_rtl can be set. Usage of f_default_ltr is not recommended as the visual representation of the text of the annotation may not match the plain text of the annotation (as interpreted by software which does not know that the paragraph direction is supposed to be default-LTR). Use f_default_ltr only as last resort if you cannot modify the text received from a default-LTR input field appropriately for paragraph direction LTR used in PDF annotations. See also f_auto_alignment
f_default_rtl	Choose direction automatically, default to RTL. The base direction of each paragraph (BiDi paragraph level) will depend on the first strong directional character in the paragraph. The paragraph level will be 1 (RTL) for paragraphs having no strong directional character. If none of f_ltr, f_rtl, f_default_ltr, and f_default_rtl is set, f_ltr will be used. At most one of f_ltr, f_rtl, f_default_ltr, and f_default_rtl can be set. Usage of f_default_rtl is not recommended as the visual representation of the text of the annotation may not match the plain text of the annotation (as interpreted by software which does not know that the paragraph direction is supposed to be default-RTL). Use f_default_rtl only as last resort if you cannot modify the text received from a default-RTL input field appropriately for paragraph direction LTR used in PDF annotations. See also f_auto_alignment

enum HAlignment

Horizontal alignment.

Enumerator
ha_left	Align left.
ha_center	Center.
ha_right	Align right.

enum LineEnding

Line ending styles.

Enumerator
le_unknown	Unknown line ending style.
le_none	No line ending.
le_arrow	Two short lines forming an arrowhead.

enum Type

Annotation types.

Most annotation types are supported for PDF documents only.

Enumerator
t_unknown	Unknown annotation type.
t_line	Line annotation.
t_scribble	Scribble annotation (freehand scribble).
t_freetext	FreeText annotation.

Constructor & Destructor Documentation

SignDocAnnotation ( )

inlineprotected

Constructor.

~SignDocAnnotation ( )

inline

Destructor.

SignDocAnnotation ( SIGNDOC_Annotation * aP )

inline

Internal function.

Member Function Documentation

ReturnCode addPoint ( const Point & aPoint )

inline

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

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

Parameters

[in] aPoint The point to be added.

Returns: ReturnCode::rc_ok iff successful.

See also: newStroke()

ReturnCode addPoint	(	double	aX,
		double	aY
	)

inline

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

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

Parameters

[in]	aX	The X coordinate of the point.
[in]	aY	The Y coordinate of the point.

Returns: ReturnCode::rc_ok iff successful.

See also: newStroke()

ReturnCode getBoundingBox ( Rect & aOutput ) const

inline

Get the bounding box of the annotation.

The bounding box is available for objects returned by SignDocDocument::getAnnotation() only.

Parameters

[out] aOutput The bounding box (using document coordinates, see Coordinate Systems) will be stored here.

Returns: ReturnCode::rc_ok iff successful.

const char * getErrorMessage ( Encoding aEncoding ) const

inline

Get an error message for the last function call.

Parameters

[in] aEncoding The encoding to be used for the error message.

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 this object is destroyed or a member function of this object is called.

See also: getErrorMessageW()

const wchar_t * getErrorMessageW ( ) const

inline

Get an error message for the last function call.

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 this object is destroyed or a member function of this object is called.

See also: getErrorMessage()

ReturnCode getFont	(	Encoding	aEncoding,
		std::string &	aFont,
		double &	aFontSize
	)

inline

Get the font of a text annotation.

Parameters

[in]	aEncoding	The encoding to be used for the font name returned in aFont.
[out]	aFont	The font name will be stored here.
[out]	aFontSize	The font size in user space units will be stored here.

Returns: ReturnCode::rc_ok iff successful.

See also: getPlainText(), setPlainText()

SIGNDOC_Annotation* getImpl ( )

inline

Internal function.

const SIGNDOC_Annotation* getImpl ( ) const

inline

Internal function.

std::string getName ( Encoding aEncoding ) const

inline

Get the name of the annotation.

Parameters

[in] aEncoding The encoding to be used for the return value.

Returns: The name of the annotation or an empty string if the name is not available. If flag SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

int getPage ( ) const

inline

Get the page number of the annotation.

The page number is available for objects returned by SignDocDocument::getAnnotation() only.

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

ReturnCode getPlainText	(	Encoding	aEncoding,
		std::string &	aText
	)

inline

Get the text of a text annotation.

Parameters

[in]	aEncoding	The encoding to be used for the text returned in aText.
[out]	aText	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 SignDocDocument::f_keep_escape_sequences is set, the string may contain escape sequences for selecting natural languages.

Returns: ReturnCode::rc_ok iff successful.

See also: getFont(), setPlainText()

SignDocAnnotation::Type getType ( ) const

inline

Get the type of the annotation.

Returns: The type of the annotation.

ReturnCode newStroke ( )

inline

Start a new stroke in a scribble annotation.

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

Returns: ReturnCode::rc_ok iff successful.

See also: addPoint()

ReturnCode setBackgroundColor ( const SignDocColor & aColor )

inline

Set the background color of the annotation.

This function can be used for annotations of type t_freetext.

The default background color is white.

Parameters

[in] aColor The background color of the annotation.

Returns: ReturnCode::rc_ok iff successful.

ReturnCode setBorderColor ( const SignDocColor & aColor )

inline

Set the border color of the annotation.

This function can be used for annotations of type t_freetext.

The default border color is black.

Parameters

[in] aColor The border color of the annotation.

Returns: ReturnCode::rc_ok iff successful.

See also: setBorderLineWidthInPoints()

ReturnCode setBorderLineWidthInPoints ( double aWidth )

inline

Set border line width in points.

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

Parameters

[in] aWidth The border line width in points (1/72 inch). If this value is negative, no border lines will be drawn.

Returns: ReturnCode::rc_ok iff successful.

See also: setBorderColor()

ReturnCode setColor ( const SignDocColor & aColor )

inline

Set the foreground color of the annotation.

This function can be used for annotations of types t_line, t_scribble, and t_freetext.

The default foreground color is black.

Parameters

[in] aColor The foreground color of the annotation.

Returns: ReturnCode::rc_ok iff successful.

ReturnCode setFlags ( int aFlags )

inline

Set flags.

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

Parameters

[in] aFlags See enum Flags.

Returns: ReturnCode::rc_ok iff successful.

See also: setPlainText()

void setImpl ( SIGNDOC_Annotation * aP )

inline

Internal function.

ReturnCode setLineEnding	(	LineEnding	aStart,
		LineEnding	aEnd
	)

inline

Set line ending styles.

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

Parameters

[in]	aStart	Line ending style for start point.
[in]	aEnd	Line ending style for end point.

Returns: ReturnCode::rc_ok iff successful.

ReturnCode setLineWidthInPoints ( double aWidth )

inline

Set line width in points.

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

Parameters

[in] aWidth The line width in points (1/72 inch).

Returns: ReturnCode::rc_ok iff successful.

ReturnCode setName	(	Encoding	aEncoding,
		const std::string &	aName
	)

inline

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

[in]	aEncoding	The encoding of aName.
[in]	aName	The name of the annotation.

Returns: ReturnCode::rc_ok iff successful.

ReturnCode setName ( const wchar_t * aName )

inline

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

[in] aName The name of the annotation.

Returns: ReturnCode::rc_ok iff successful.

ReturnCode setOpacity ( double aOpacity )

inline

Set the opacity of the annotation.

This function can be used for annotations of types t_line, t_scribble, and t_freetext.

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

Parameters

[in] aOpacity The opacity, 0.0 (transparent) through 1.0 (opaque).

Returns: ReturnCode::rc_ok iff successful.

ReturnCode setPlainText	(	Encoding	aEncoding,
		const std::string &	aText,
		const std::string &	aFont,
		double	aFontSize,
		HAlignment	aHAlignment
	)

inline

Set the text of a text annotation.

This function can be used for annotations of type t_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 setFlags() if you need to set a different paragraph direction.

Parameters

[in]	aEncoding	The encoding of aText and aFont.
[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.

Returns: ReturnCode::rc_ok iff successful.

See also: getFont(), getPlainText(), setFlags(), SignDocDocumentLoader::loadFontConfigBlob(), SignDocDocumentLoader::loadFontConfigEnvironment(), SignDocDocumentLoader::loadFontConfigFile(), SignDocDocumentLoader::loadFontConfigStream()

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

SignDocSDK-cpp.h

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation