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...
enum	ReturnCode { rc_ok, rc_not_supported, rc_invalid_value, rc_not_available }
	Return codes. More...
Public Member Functions
	~SignDocAnnotation ()
	Destructor.
Type	getType () const
	Get the type of the annotation.
std::string	getName (Encoding aEncoding) const
	Get the name of the annotation.
int	getPage () const
	Get the page number of the annotation.
ReturnCode	getBoundingBox (Rect &aOutput) const
	Get the bounding box of the annotation.
ReturnCode	setName (Encoding aEncoding, const std::string &aName)
	Set the name of the annotation.
ReturnCode	setName (const wchar_t *aName)
	Set the name of the annotation.
ReturnCode	setLineEnding (LineEnding aStart, LineEnding aEnd)
	Set line ending styles.
ReturnCode	setColor (const SignDocColor &aColor)
	Set the foreground color of the annotation.
ReturnCode	setBackgroundColor (const SignDocColor &aColor)
	Set the background color of the annotation.
ReturnCode	setBorderColor (const SignDocColor &aColor)
	Set the border color of the annotation.
ReturnCode	setOpacity (double aOpacity)
	Set the opacity of the annotation.
ReturnCode	setLineWidthInPoints (double aWidth)
	Set line width in points.
ReturnCode	setBorderLineWidthInPoints (double aWidth)
	Set border line width in points.
ReturnCode	newStroke ()
	Start a new stroke in a scribble annotation.
ReturnCode	addPoint (const Point &aPoint)
	Add a point to the current stroke of a scribble annotation.
ReturnCode	addPoint (double aX, double aY)
	Add a point to the current stroke of a scribble annotation.
ReturnCode	setPlainText (Encoding aEncoding, const std::string &aText, const std::string &aFont, double aFontSize, HAlignment aHAlignment)
	Set the text of a text annotation.
ReturnCode	getPlainText (Encoding aEncoding, std::string &aText)
	Get the text of a text annotation.
ReturnCode	getFont (Encoding aEncoding, std::string &aFont, double &aFontSize)
	Get the font of a text annotation.
ReturnCode	setFlags (int aFlags)
	Set flags.
	SignDocAnnotation (SIGNDOC_Annotation *aP)
	Internal function.
SIGNDOC_Annotation *	getImpl ()
	Internal function.
const SIGNDOC_Annotation *	getImpl () const
	Internal function.
void	setImpl (SIGNDOC_Annotation *aP)
	Internal function.
Protected Member Functions
	SignDocAnnotation ()
	Constructor.

Detailed Description

An annotation.

Currently, annotations are supported for PDF documents only.

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

Member Enumeration Documentation

enum de::softpro::doc::SignDocAnnotation::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 de::softpro::doc::SignDocAnnotation::HAlignment

Horizontal alignment.

Enumerator:

ha_left	Align left.
ha_center	Center.
ha_right	Align right.

enum de::softpro::doc::SignDocAnnotation::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 de::softpro::doc::SignDocAnnotation::ReturnCode

Return codes.

Enumerator:

rc_ok	Parameter set successfully.
rc_not_supported	Setting the parameter is not supported.
rc_invalid_value	The value for the parameter is invalid.
rc_not_available	The value is not available.

enum de::softpro::doc::SignDocAnnotation::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

de::softpro::doc::SignDocAnnotation::SignDocAnnotation ( ) [inline, protected]

Constructor.

de::softpro::doc::SignDocAnnotation::~SignDocAnnotation ( ) [inline]

Destructor.

de::softpro::doc::SignDocAnnotation::SignDocAnnotation ( SIGNDOC_Annotation * aP ) [inline]

Internal function.

Member Function Documentation

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

See also:: newStroke()

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

See also:: newStroke()

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

See also:: getPlainText(), setPlainText()

Todo:: define behavior if there are multiple fonts

SIGNDOC_Annotation* de::softpro::doc::SignDocAnnotation::getImpl ( ) [inline]

Internal function.

const SIGNDOC_Annotation* de::softpro::doc::SignDocAnnotation::getImpl ( ) const [inline]

Internal function.

std::string de::softpro::doc::SignDocAnnotation::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 de::softpro::doc::SignDocAnnotation::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 de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

See also:: getFont(), setPlainText()

Type de::softpro::doc::SignDocAnnotation::getType ( ) const [inline]

Get the type of the annotation.

Returns:: The type of the annotation.

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

See also:: addPoint()

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

See also:: setBorderLineWidthInPoints()

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

See also:: setBorderColor()

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

See also:: setPlainText()

void de::softpro::doc::SignDocAnnotation::setImpl ( SIGNDOC_Annotation * aP ) [inline]

Internal function.

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

ReturnCode de::softpro::doc::SignDocAnnotation::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:: rc_ok iff successful.

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

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

SignDocSDK-cpp.h

de::softpro::doc::SignDocAnnotation Class Reference

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation