SignDoc SDK (C)  5.0.0
SIGNDOC_TextCluster Class Reference

A cluster of Unicode code points and glyphs. More...

#include <SignDocSDK-c.h>

Public Member Functions

const struct SIGNDOC_TextClusterSIGNDOC_TextCluster_addReference (const struct SIGNDOC_TextCluster *aObj)
 Add a reference (increment the reference count). More...
 
void SIGNDOC_TextCluster_removeReference (const struct SIGNDOC_TextCluster *aObj)
 Remove a reference (decrement the reference count). More...
 
const char * SIGNDOC_TextCluster_getText (const struct SIGNDOC_TextCluster *aObj)
 Get the Unicode code points of the cluster (UTF-8). More...
 
const wchar_t * SIGNDOC_TextCluster_getTextW (const struct SIGNDOC_TextCluster *aObj)
 Get the Unicode code points of the cluster (wide string). More...
 
int SIGNDOC_TextCluster_getPage (const struct SIGNDOC_TextCluster *aObj)
 Get the page on which the glyphs of this object appear. More...
 
void SIGNDOC_TextCluster_getPages (struct SIGNDOC_Exception **aEx, const struct SIGNDOC_TextCluster *aObj, struct SIGNDOC_IntArray *aOutput)
 Get the pages on which the glyphs of this object appear. More...
 
int SIGNDOC_TextCluster_getUnicodeDirection (const struct SIGNDOC_TextCluster *aObj)
 Get the direction implied by the Unicode code points. More...
 
int SIGNDOC_TextCluster_getNumberOfGlyphs (const struct SIGNDOC_TextCluster *aObj)
 Get the number of glyphs in this cluster. More...
 
int SIGNDOC_TextCluster_getGlyphPage (const struct SIGNDOC_TextCluster *aObj, int aIndex)
 Get the page on which a glyph appears. More...
 
SIGNDOC_Boolean SIGNDOC_TextCluster_getGlyphReferencePoint (const struct SIGNDOC_TextCluster *aObj, int aIndex, double *aX, double *aY)
 Get the reference point of a glyph. More...
 
SIGNDOC_Boolean SIGNDOC_TextCluster_getGlyphBoundingBox (const struct SIGNDOC_TextCluster *aObj, int aIndex, struct SIGNDOC_Rect *aOutput)
 Get the bounding box of a glyph. More...
 
int SIGNDOC_TextCluster_getGlyphTextRenderingMode (const struct SIGNDOC_TextCluster *aObj, int aIndex)
 Get the text rendering mode for a glyph. More...
 
double SIGNDOC_TextCluster_getGlyphFontSize (const struct SIGNDOC_TextCluster *aObj, int aIndex)
 Get the font size for a glyph. More...
 
double SIGNDOC_TextCluster_getGlyphAdvanceWidth (const struct SIGNDOC_TextCluster *aObj, int aIndex)
 Get the advance width of a glyph. More...
 

Detailed Description

A cluster of Unicode code points and glyphs.

An object of this class contains a sequence of Unicode code points and a sequence of glyphs.

In the ideal case, each cluster contains exactly one Unicode code point and one glyph, making the relationship between the two unambiguous.

In the general case, the number of Unicode code points can be different from the number of glyphs and the relationship between the Unicode code points of the cluster and the glyphs of the cluster is unknown.

There can be more glyphs than Unicode code points, more Unicode code points than glyphs (e.g., for a ligature), or the same number of glyphs and Unicode code points.

The clusters returned by SIGNDOC_Document_findText() may contain more characters than have been searched for (as clusters cannot be broken up). If a cluster contains multiple instances of the search text, SIGNDOC_Document_findText() will return multiple instances of that cluster.

Member Function Documentation

const struct SIGNDOC_TextCluster * SIGNDOC_TextCluster_addReference ( const struct SIGNDOC_TextCluster aObj)

Add a reference (increment the reference count).

There must be a SIGNDOC_TextCluster_removeReference() call for each SIGNDOC_TextCluster_addReference() call.

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
Returns
aObj (for your convenience).
See also
SIGNDOC_TextCluster_removeReference()
double SIGNDOC_TextCluster_getGlyphAdvanceWidth ( const struct SIGNDOC_TextCluster aObj,
int  aIndex 
)

Get the advance width of a glyph.

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
[in]aIndexThe 0-based index of the glyph. The order of the glyphs is unspecified.
Returns
The advance width of the glyph in document coordinates (see Coordinate Systems) or 0.0 if aIndex is out of range.
See also
SIGNDOC_TextCluster_getNumberOfGlyphs()
SIGNDOC_Boolean SIGNDOC_TextCluster_getGlyphBoundingBox ( const struct SIGNDOC_TextCluster aObj,
int  aIndex,
struct SIGNDOC_Rect aOutput 
)

Get the bounding box of a glyph.

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
[in]aIndexThe 0-based index of the glyph. The order of the glyphs is unspecified.
[out]aOutputThe bounding box of the glyph in document coordinates will be stored to the object pointed by this argument. See Coordinate Systems.
Returns
SIGNDOC_TRUE on success, SIGNDOC_FALSE if aIndex is out of range.
See also
SIGNDOC_TextCluster_getGlyphReferencePoint(), SIGNDOC_TextCluster_getNumberOfGlyphs()
double SIGNDOC_TextCluster_getGlyphFontSize ( const struct SIGNDOC_TextCluster aObj,
int  aIndex 
)

Get the font size for a glyph.

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
[in]aIndexThe 0-based index of the glyph. The order of the glyphs is unspecified.
Returns
The font size of the glyph (in user space units) or 0.0 if aIndex is out of range.
See also
SIGNDOC_TextCluster_getNumberOfGlyphs()
int SIGNDOC_TextCluster_getGlyphPage ( const struct SIGNDOC_TextCluster aObj,
int  aIndex 
)

Get the page on which a glyph appears.

In extreme (theoretical) cases, the glyphs of a single cluster can appear on different pages, even on pages outside the range of pages passed to SIGNDOC_Document_findText() or SIGNDOC_Document_createTextIterator().

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
[in]aIndexThe 0-based index of the glyph. The order of the glyphs is unspecified.
Returns
The 1-based page number of the page on which the glyph appears or 0 if aIndex is out of range.
See also
SIGNDOC_TextCluster_getNumberOfGlyphs(), SIGNDOC_TextCluster_getPage(), SIGNDOC_TextCluster_getPages(), SIGNDOC_FindTextOccurrence_getPage(), SIGNDOC_FindTextOccurrence_getPages()
SIGNDOC_Boolean SIGNDOC_TextCluster_getGlyphReferencePoint ( const struct SIGNDOC_TextCluster aObj,
int  aIndex,
double *  aX,
double *  aY 
)

Get the reference point of a glyph.

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
[in]aIndexThe 0-based index of the glyph. The order of the glyphs is unspecified.
[out]aXThe X coordinate of the reference point of the glyph in document coordinates will be stored to the object pointed by this argument. See Coordinate Systems.
[out]aYThe Y coordinate of the reference point of the glyph in document coordinates will be stored to the object pointed by this argument.
Returns
SIGNDOC_TRUE on success, SIGNDOC_FALSE if aIndex is out of range.
See also
SIGNDOC_TextCluster_getGlyphBoundingBox(), SIGNDOC_TextCluster_getNumberOfGlyphs()
int SIGNDOC_TextCluster_getGlyphTextRenderingMode ( const struct SIGNDOC_TextCluster aObj,
int  aIndex 
)

Get the text rendering mode for a glyph.

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
[in]aIndexThe 0-based index of the glyph. The order of the glyphs is unspecified.
Returns
The text rendering mode for the glyph, as defined in the PDF specification. 0 if aIndex is out of range or if the text rendering mode is invalid.
See also
SIGNDOC_TextCluster_getNumberOfGlyphs()
int SIGNDOC_TextCluster_getNumberOfGlyphs ( const struct SIGNDOC_TextCluster aObj)

Get the number of glyphs in this cluster.

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
Returns
The number of glyphs in this clsuter.
int SIGNDOC_TextCluster_getPage ( const struct SIGNDOC_TextCluster aObj)

Get the page on which the glyphs of this object appear.

The glyphs of a cluster can appear on different pages, even on pages outside the range of pages passed to SIGNDOC_Document_findText() or SIGNDOC_Document_createTextIterator().

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
Returns
The 1-based page number of the page on which the glyphs appear or 0 if the glyphs appear on two or more different pages.
See also
SIGNDOC_TextCluster_getGlyphPage(), SIGNDOC_TextCluster_getPages(), SIGNDOC_FindTextOccurrence_getPage()
void SIGNDOC_TextCluster_getPages ( struct SIGNDOC_Exception **  aEx,
const struct SIGNDOC_TextCluster aObj,
struct SIGNDOC_IntArray aOutput 
)

Get the pages on which the glyphs of this object appear.

The glyphs of a cluster can appear on different pages, even on pages outside the range of pages passed to SIGNDOC_Document_findText() or SIGNDOC_Document_createTextIterator().

Parameters
[out]aExAny exception will be returned in the object pointed to by this parameter.
[in]aObjA pointer to the SIGNDOC_TextCluster object.
[in,out]aOutputThe 1-based page numbers of the pages on which the glyphs appear will be stored here.
See also
SIGNDOC_TextCluster_getGlyphPage(), SIGNDOC_TextCluster_getPage(), SIGNDOC_FindTextOccurrence_getPages()
const char * SIGNDOC_TextCluster_getText ( const struct SIGNDOC_TextCluster aObj)

Get the Unicode code points of the cluster (UTF-8).

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
Returns
A pointer to the UTF-8-encoded Unicode code points of the cluster, in logical order. The string must not be modifed and it must not be destroyed. The pointer will become invalid when this object is destroyed.
See also
SIGNDOC_TextCluster_getTextW()
const wchar_t * SIGNDOC_TextCluster_getTextW ( const struct SIGNDOC_TextCluster aObj)

Get the Unicode code points of the cluster (wide string).

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
Returns
A pointer to the UTF-16-encoded (Windows) or UTF-32-encoded (everywhere else) Unicode code points of the cluster, in logical order. The string must not be modifed and it must not be destroyed. The pointer will become invalid when this object is destroyed.
See also
SIGNDOC_TextCluster_getText()
int SIGNDOC_TextCluster_getUnicodeDirection ( const struct SIGNDOC_TextCluster aObj)

Get the direction implied by the Unicode code points.

A lot of characters (such as punctuation characters) do not imply a direction. Unless there is at least one character that defines a direction, 0 will be returned. 0 is also returned if there are conflicting directions.

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
Returns
-1 for RTL, 1 for LTR, 0 if the direction cannot be determined unambiguously.
void SIGNDOC_TextCluster_removeReference ( const struct SIGNDOC_TextCluster aObj)

Remove a reference (decrement the reference count).

If the reference count reaches zero, the object will be destroyed.

Parameters
[in]aObjA pointer to the SIGNDOC_TextCluster object.
See also
SIGNDOC_TextCluster_addReference()

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