TextProvider

touchgfx/TextProvider.hpp

The TextProvider is used in drawing basic strings and strings with one or two wildcards. The TextProvider enables wildcard expansion of the string at the time it is written to the LCD.

Wildcards specified as <placeholder> are converted to Unicode value 2 by the text converter tool, and the placeholders are automatically expanded with the specified wildcard buffers at runtime.

Public Functions

bool	endOfString()
	Tells if the end of the string has been reached.
Unicode::UnicodeChar	getNextChar()
	Gets the next character.
Unicode::UnicodeChar	getNextLigature(TextDirection direction)
	Gets the next ligature.
Unicode::UnicodeChar	getNextLigature(TextDirection direction, const Font font, const GlyphNode & glyph)
	Gets the next ligature.
Unicode::UnicodeChar	getNextLigature(TextDirection direction, const Font font, const GlyphNode & glyph, const uint8_t *& pixelData, uint8_t & bitsPerPixel)
	Gets the next ligature.
void	initialize(const Unicode::UnicodeChar stringFormat, const uint16_t gsubTable =0, const FontContextualFormsTable * formsTable =0, ... )
	Initializes the TextProvider.
void	initialize(const Unicode::UnicodeChar stringFormat, va_list pArg, const uint16_t gsubTable =0, const FontContextualFormsTable * formsTable =0)
	Initializes the TextProvider.
	TextProvider()
	Initializes a new instance of the TextProvider class.

Public Attributes

const uint32_t	MAX_32BIT_INTEGER_DIGITS
	Max number of digits used for the text representation of a 32 bit integer.

Public Functions Documentation

endOfString

bool endOfString	(			)

Tells if the end of the string has been reached.

Returns:

True if the end of the string has been reached, false if not.

See also:

TextProvider::getNextLigature()

getNextChar

Unicode::UnicodeChar getNextChar	(			)

Gets the next character.

For Arabic and Thai, it is important to use the getNextLigature instead.

Returns:

The next character of the expanded string or 0 if end of string is reached.

See also:

TextProvider::getNextLigature

getNextLigature

Unicode::UnicodeChar getNextLigature	(	TextDirection	direction	)

Gets the next ligature.

For most languages this is simply the next Unicode character from the buffer, but e.g. Arabic has different ligatures for each character. Thai character placement might also depend on previous characters. It is recommended to use getNextLigature with font and glyph parameters to ensure coming glyphs in a text are placed correctly.

Parameters:

direction	The direction.

Returns:

The next character of the expanded string or 0 if end of string is reached.

Note

Functions getNextLigature() and getNextChar() will advance through the same buffer and mixing the use of those functions is not recommended and may cause undesired results. Instead create two TextProviders and user getNextChar() on one and getNextLigature() on the other.

See also:

TextProvider::getNextChar

getNextLigature

Unicode::UnicodeChar getNextLigature	(	TextDirection	direction ,
		const Font *	font ,
		const GlyphNode *&	glyph
		)

Gets the next ligature.

For most languages this is simply the next Unicode character from the buffer, but e.g. Arabic has different ligatures for each character.

Also gets a glyph for the ligature in a font. For non-Thai Unicodes, this is identical to using Font::getGlyph(), but for Thai characters where diacritics glyphs are not always placed at the same relative position, an adjusted GlyphNode will be generated with correct relative X/Y coordinates.

Parameters:

direction	The direction.
font	The font.
glyph	The glyph.

Returns:

The next character of the expanded string or 0 if end of string i reached.

Note

Functions getNextLigature() and getNextChar() will advance through the same buffer and mixing the use of those functions is not recommended and may cause undesired results. Instead create two TextProviders and user getNextChar() on one and getNextLigature() on the other.

See also:

TextProvider::getNextChar, Font::getGlyph

getNextLigature

Unicode::UnicodeChar getNextLigature	(	TextDirection	direction ,
		const Font *	font ,
		const GlyphNode *&	glyph ,
		const uint8_t *&	pixelData ,
		uint8_t &	bitsPerPixel
		)

Gets the next ligature.

For most languages this is simply the next Unicode character from the buffer, but e.g. Arabic has different ligatures for each character.

Also gets a glyph for the ligature in a font. For non-Thai Unicodes, this is identical to using Font::getGlyph(), but for Thai characters where diacritics glyphs are not always placed at the same relative position, an adjusted GlyphNode will be generated with correct relative X/Y coordinates.

Furthermore a pointer to the glyph data and the bit depth of the font are returned in parameters.

Parameters:

direction	The direction.
font	The font.
glyph	The glyph.
pixelData	Information describing the pixel.
bitsPerPixel	The bits per pixel.

Returns:

The next character of the expanded string or 0 if end of string is reached.

Note

Functions getNextLigature() and getNextChar() will advance through the same buffer and mixing the use of those functions is not recommended and may cause undesired results. Instead create two TextProviders and user getNextChar() on one and getNextLigature() on the other.

See also:

TextProvider::getNextChar, Font::getGlyph

initialize

void initialize	(	const Unicode::UnicodeChar *	stringFormat ,
		const uint16_t *	gsubTable =0,
		const FontContextualFormsTable *	formsTable =0,
		...
		)

Initializes the TextProvider.

Each '\2' character in the format is replaced by one UnicodeChar* argument from pArg.

Parameters:

stringFormat	The string to format.
gsubTable	(Optional) Pointer to GSUB table with Unicode substitution rules.
formsTable	(Optional) Pointer to contextual forms table with Unicode substitution rules (for arabic).
...	Variable arguments providing additional information.

initialize

void initialize	(	const Unicode::UnicodeChar *	stringFormat ,
		va_list	pArg ,
		const uint16_t *	gsubTable =0,
		const FontContextualFormsTable *	formsTable =0
		)

Initializes the TextProvider.

Each '\2' character in the format is replaced by one UnicodeChar* argument from pArg.

Parameters:

stringFormat	The string to format.
pArg	Format arguments in the form of a va_list.
gsubTable	(Optional) Pointer to GSUB table with Unicode substitution rules.
formsTable	(Optional) Pointer to contextual forms table with Unicode substitution rules (for arabic).

TextProvider

TextProvider	(			)

Initializes a new instance of the TextProvider class.

Note

The user must call initialize() before characters can be provided.

Public Attributes Documentation

MAX_32BIT_INTEGER_DIGITS

const uint32_t MAX_32BIT_INTEGER_DIGITS = 33U

Max number of digits used for the text representation of a 32 bit integer.