Font

touchgfx/Font.hpp

The font base class. This class is abstract and requires the implementation of getGlyph. It provides utility functions such as obtaining string width and font height.

Inherited by: ConstFont

Public Functions

virtual FORCE_INLINE_FUNCTION uint16_t	getBaseline() const
	Returns the position of the baseline of this font.
virtual FORCE_INLINE_FUNCTION uint8_t	getBitsPerPixel() const
	Gets bits per pixel for this font.
virtual FORCE_INLINE_FUNCTION uint8_t	getByteAlignRow() const
	Are the glyphs saved with each glyph row byte aligned?
virtual uint16_t	getCharWidth(const Unicode::UnicodeChar c) const
	Gets the width in pixels of the specified character.
virtual const FontContextualFormsTable *	getContextualFormsTable() const
	Gets the contextual forms table used in arabic fonts.
virtual Unicode::UnicodeChar	getEllipsisChar() const
	Gets ellipsis character for the given font.
virtual Unicode::UnicodeChar	getFallbackChar() const
	Gets fallback character for the given font.
virtual const GlyphNode *	getGlyph(Unicode::UnicodeChar unicode) const
	Gets the glyph data associated with the specified Unicode.
virtual const GlyphNode *	getGlyph(Unicode::UnicodeChar unicode, const uint8_t *& pixelData, uint8_t & bitsPerPixel) const =0
	Gets the glyph data associated with the specified Unicode.
virtual const uint16_t *	getGSUBTable() const
	Gets GSUB table.
virtual FORCE_INLINE_FUNCTION uint16_t	getHeight() const
	Returns the height of a font.
virtual int8_t	getKerning(Unicode::UnicodeChar prevChar, const GlyphNode * glyph) const
	Gets the kerning distance between two characters.
FORCE_INLINE_FUNCTION uint8_t	getMaxPixelsLeft() const
	Gets maximum pixels left of any glyph in the font.
FORCE_INLINE_FUNCTION uint8_t	getMaxPixelsRight() const
	Gets maximum pixels right of any glyph in the font.
virtual uint16_t	getNumberOfLines(const Unicode::UnicodeChar * text, ... ) const
	Count the number of lines in a given text.
FORCE_INLINE_FUNCTION uint16_t	getPixelsAboveTop() const
	Gets pixels above top of the normal text height.
FORCE_INLINE_FUNCTION uint16_t	getPixelsBelowBottom() const
	Gets number of pixel rows below the bottom of the font.
virtual int16_t	getSpacingAbove(const Unicode::UnicodeChar * text, ... ) const
	Gets the number of blank pixels at the top of the given text.
virtual uint16_t	getStringWidth(const Unicode::UnicodeChar * text, ... ) const
	Gets the width in pixels of the specified string.
virtual uint16_t	getStringWidth(TextDirection textDirection, const Unicode::UnicodeChar * text, ... ) const
	Gets the width in pixels of the specified string.
	TOUCHGFX_DEPRECATED("Please use getBaseline() instead." , virtual uint16_t getFontHeight() const )
	Returns the height in pixels of this font.
	TOUCHGFX_DEPRECATED("Please use getHeight() instead." , virtual uint16_t getMaxTextHeight(const Unicode::UnicodeChar *text,...) const )
	Gets the height of the highest character in a given string.
	TOUCHGFX_DEPRECATED("Please use getHeight() instead." , virtual uint16_t getMinimumTextHeight() const )
	Returns the height of a font.
virtual	~Font()
	Finalizes an instance of the Font class.
FORCE_INLINE_FUNCTION bool	isInvisibleZeroWidth(Unicode::UnicodeChar character)
	Query if 'character' is invisible, zero width.

Protected Functions

	Font(uint16_t height, uint16_t baseline, uint8_t pixAboveTop, uint8_t pixBelowBottom, uint8_t bitsPerPixel, uint8_t byteAlignRow, uint8_t maxLeft, uint8_t maxRight, const Unicode::UnicodeChar fallbackChar, const Unicode::UnicodeChar ellipsisChar)
	Initializes a new instance of the Font class.
uint16_t	getStringWidthLTR(TextDirection textDirection, const Unicode::UnicodeChar * text, va_list pArg) const
	Gets the width in pixels of the specified string.
uint16_t	getStringWidthRTL(TextDirection textDirection, const Unicode::UnicodeChar * text, va_list pArg) const
	Gets the width in pixels of the specified string.

Protected Attributes

uint8_t	bAlignRow
	The glyphs are saved with each row byte aligned.
uint16_t	baselineHeight
	The baseline.
uint8_t	bPerPixel
	The number of bits per pixel.
Unicode::UnicodeChar	ellipsisCharacter
	The ellipsis character used for truncating long texts.
Unicode::UnicodeChar	fallbackCharacter
	The fallback character to use when no glyph exists for the wanted character.
uint16_t	fontHeight
	The font height in pixels.
uint8_t	maxPixelsLeft
	The maximum number of pixels a glyph extends to the left.
uint8_t	maxPixelsRight
	The maximum number of pixels a glyph extends to the right.
uint8_t	pixelsAboveTop
	The number of pixels above the top.
uint8_t	pixelsBelowBottom
	The number of pixels below the bottom.

Public Functions Documentation

getBaseline

virtual FORCE_INLINE_FUNCTION uint16_t getBaseline	(			)	const

Returns the position of the baseline of this font.

The returned value corresponds to the maximum height occupied by a character in the font.

Returns:

The height in pixels of this font.

Note

It is not sufficient to allocate text areas with this height. Use getMinimumTextHeight for this.

getBitsPerPixel

virtual FORCE_INLINE_FUNCTION uint8_t getBitsPerPixel	(			)	const

Gets bits per pixel for this font.

Returns:

The number of bits used per pixel in this font.

getByteAlignRow

virtual FORCE_INLINE_FUNCTION uint8_t getByteAlignRow	(			)	const

Are the glyphs saved with each glyph row byte aligned?

Returns:

True if each glyph row is stored byte aligned, false otherwise.

getCharWidth

virtual uint16_t getCharWidth	(	const Unicode::UnicodeChar	c	)

Gets the width in pixels of the specified character.

Parameters:

c	The Unicode character.

Returns:

The width in pixels of the specified character.

getContextualFormsTable

virtual const FontContextualFormsTable * getContextualFormsTable	(			)	const

Gets the contextual forms table used in arabic fonts.

Returns:

The FontContextualFormsTable or null if the font has no table.

getEllipsisChar

virtual Unicode::UnicodeChar getEllipsisChar	(			)	const

Gets ellipsis character for the given font.

This is the character which is used when truncating long lines.

Returns:

The ellipsis character for the typography.

See also:

TextArea::setWideTextAction

getFallbackChar

virtual Unicode::UnicodeChar getFallbackChar	(			)	const

Gets fallback character for the given font.

The fallback character is the character used when no glyph is available for some character. If 0 (zero) is returned, there is no default character.

Returns:

The default character for the typography in case no glyph is available.

getGlyph

virtual const GlyphNode * getGlyph	(	Unicode::UnicodeChar	unicode	)

Gets the glyph data associated with the specified Unicode.

Please note that in case of Thai letters and Arabic letters where diacritics can be placed relative to the previous character(s), please use TextProvider::getNextLigature() instead as it will create a temporary GlyphNode that will be adjusted with respect to X/Y position.

Parameters:

unicode	The character to look up.

Returns:

A pointer to the glyph node or null if the glyph was not found.

See also:

TextProvider::getNextLigature

getGlyph

virtual const GlyphNode * getGlyph	(	Unicode::UnicodeChar	unicode ,		const =0
		const uint8_t *&	pixelData ,		const =0
		uint8_t &	bitsPerPixel		const =0
		)	const =0

Gets the glyph data associated with the specified Unicode.

Please note that in case of Thai letters and Arabic letters where diacritics can be placed relative to the previous character(s), please use TextProvider::getNextLigature() instead as it will create a temporary GlyphNode that will be adjusted with respect to X/Y position.

Parameters:

unicode	The character to look up.
pixelData	Pointer to the pixel data for the glyph if the glyph is found. This is set by this method.
bitsPerPixel	Reference where to place the number of bits per pixel.

Returns:

A pointer to the glyph node or null if the glyph was not found.

Reimplemented by: touchgfx::ConstFont::getGlyph

getGSUBTable

virtual const uint16_t * getGSUBTable	(			)	const

Gets GSUB table.

Currently only used for Devanagari fonts.

Returns:

The GSUB table or null if font has GSUB no table.

getHeight

virtual FORCE_INLINE_FUNCTION uint16_t getHeight	(			)	const

Returns the height of a font.

The font may exceed the top by getPixelsAboveTop() or the bottom by getPixelsBelowBottom.

Returns:

The font height.

getKerning

virtual int8_t getKerning	(	Unicode::UnicodeChar	prevChar ,		const
		const GlyphNode *	glyph		const
		)	const

Gets the kerning distance between two characters.

Parameters:

prevChar	The Unicode value of the previous character.
glyph	the glyph object for the current character.

Returns:

The kerning distance between prevChar and glyph char.

Reimplemented by: touchgfx::InternalFlashFont::getKerning, touchgfx::ConstFont::getKerning

getMaxPixelsLeft

FORCE_INLINE_FUNCTION uint8_t getMaxPixelsLeft	(			)	const

Gets maximum pixels left of any glyph in the font.

This is the max value of "left" for all glyphs. The value is negated so if a "g" has left=-6 maxPixelsLeft is 6. This value is calculated by the font converter.

Returns:

The maximum pixels left.

getMaxPixelsRight

FORCE_INLINE_FUNCTION uint8_t getMaxPixelsRight	(			)	const

Gets maximum pixels right of any glyph in the font.

This is the max value of "width+left-advance" for all glyphs. The is the number of pixels a glyph reaches to the right of its normal area. This value is calculated by the font converter.

Returns:

The maximum pixels right.

getNumberOfLines

virtual uint16_t getNumberOfLines	(	const Unicode::UnicodeChar *	text ,		const
		...			const
		)	const

Count the number of lines in a given text.

Parameters:

text	The text.
...	Variable arguments providing additional information.

Returns:

The number of lines.

getPixelsAboveTop

FORCE_INLINE_FUNCTION uint16_t getPixelsAboveTop	(			)	const

Gets pixels above top of the normal text height.

For most fonts this is 0, for some 'wedding' fonts the number may be positive.

Returns:

The pixels above top of normal text.

getPixelsBelowBottom

FORCE_INLINE_FUNCTION uint16_t getPixelsBelowBottom	(			)	const

Gets number of pixel rows below the bottom of the font.

Returns:

The pixels below bottom.

getSpacingAbove

virtual int16_t getSpacingAbove	(	const Unicode::UnicodeChar *	text ,		const
		...			const
		)	const

Gets the number of blank pixels at the top of the given text.

Parameters:

text	A null-terminated Unicode string.
...	Variable arguments providing additional information inserted at wildcard placeholders.

Returns:

The number of blank pixels above the text.

getStringWidth

virtual uint16_t getStringWidth	(	const Unicode::UnicodeChar *	text ,		const
		...			const
		)	const

Gets the width in pixels of the specified string.

If the string contains multiple lines, the width of the widest line is found. Please note that the correct number of arguments must be given if the text contains wildcards.

It is recommended to use the getStringWidth() implementation with the TextDirection parameter to ensure correct calculation of the width. Kerning could result in different results depending on the TextDirection. This method assumes TextDirection to be TEXT_DIRECTION_LTR.

Parameters:

text	A null-terminated Unicode string with arguments to insert if the text contains wildcards.
...	Variable arguments providing additional information inserted at wildcard placeholders.

Returns:

The width in pixels of the longest line of the specified string.

getStringWidth

virtual uint16_t getStringWidth	(	TextDirection	textDirection ,		const
		const Unicode::UnicodeChar *	text ,		const
		...			const
		)	const

Gets the width in pixels of the specified string.

If the string contains multiple lines, the width of the widest line is found. Please note that the correct number of arguments must be given if the text contains wildcards.

The TextDirection should be set correctly for the text supplied. For example the string "10 20 30" will be calculated differently depending on the TextDirection. If TextDirection is TEXT_DIRECTION_LTR the width is calculated as the with of "10 20 30" (with kerning between all characters) but for TEXT_DIRECTION_RTL it is calculated as "10"+" "+"20"+" "+"30" (with kerning only between characters in the substrings and not between substrings). For most fonts there might not be a difference between the two calculations, but some fonts might cause slightly different results.

Parameters:

textDirection	The text direction.
text	A null-terminated Unicode string with arguments to insert if the text contains wildcards.
...	Variable arguments providing additional information inserted at wildcard placeholders.

Returns:

The width in pixels of the longest line of the specified string.

TOUCHGFX_DEPRECATED

TOUCHGFX_DEPRECATED	(	"Please use getBaseline() instead."	,
		virtual uint16_t getFontHeight() const
		)

Returns the height in pixels of this font.

The returned value corresponds to the maximum height occupied by a character in the font.

Returns:

The height in pixels of this font.

Note

It is not sufficient to allocate text areas with this height. Use getMinimumTextHeight for this.

Deprecated

Please use getBaseline() instead.

TOUCHGFX_DEPRECATED

TOUCHGFX_DEPRECATED	(	"Please use getHeight() instead."	,
		virtual uint16_t getMaxTextHeight(const Unicode::UnicodeChar *text,...) const
		)

Gets the height of the highest character in a given string.

The height includes the spacing above the text which is included in the font.

Returns:

The height if the given text.

Deprecated

Please use getHeight instead.

TOUCHGFX_DEPRECATED

TOUCHGFX_DEPRECATED	(	"Please use getHeight() instead."	,
		virtual uint16_t getMinimumTextHeight() const
		)

Returns the height of a font.

The font may exceed the top by getPixelsAboveTop().

Returns:

The font height.

Deprecated

Please use getHeight() instead.

~Font

virtual ~Font	(			)

Finalizes an instance of the Font class.

isInvisibleZeroWidth

static FORCE_INLINE_FUNCTION bool isInvisibleZeroWidth	(	Unicode::UnicodeChar	character	)

Query if 'character' is invisible, zero width.

Parameters:

character	The character.

Returns:

True if invisible, zero width, false if not.

Protected Functions Documentation

Font

Font	(	uint16_t	height ,
		uint16_t	baseline ,
		uint8_t	pixAboveTop ,
		uint8_t	pixBelowBottom ,
		uint8_t	bitsPerPixel ,
		uint8_t	byteAlignRow ,
		uint8_t	maxLeft ,
		uint8_t	maxRight ,
		const Unicode::UnicodeChar	fallbackChar ,
		const Unicode::UnicodeChar	ellipsisChar
		)

Initializes a new instance of the Font class.

The protected constructor of a Font.

Parameters:

height	The font height in pixels.
baseline	The baseline.
pixAboveTop	The maximum number of pixels above the top of the text.
pixBelowBottom	The number of pixels below the base line.
bitsPerPixel	The number of bits per pixel.
byteAlignRow	The glyphs are saved with each row byte aligned.
maxLeft	The maximum left extend for a glyph in the font.
maxRight	The maximum right extend for a glyph in the font.
fallbackChar	The fallback character for the typography in case no glyph is available.
ellipsisChar	The ellipsis character used for truncating long texts.

getStringWidthLTR

uint16_t getStringWidthLTR	(	TextDirection	textDirection ,		const
		const Unicode::UnicodeChar *	text ,		const
		va_list	pArg		const
		)	const

Gets the width in pixels of the specified string.

If the string contains multiple lines, the width of the widest line is found. Please note that the correct number of arguments must be given if the text contains wildcards.

Parameters:

textDirection	The text direction.
text	A null-terminated Unicode string with arguments to insert if the text contains wildcards.
pArg	Variable arguments providing additional information inserted at wildcard placeholders.

Returns:

The width in pixels of the longest line of the specified string.

Note

The string is assumed to be purely left-to-right.

getStringWidthRTL

uint16_t getStringWidthRTL	(	TextDirection	textDirection ,		const
		const Unicode::UnicodeChar *	text ,		const
		va_list	pArg		const
		)	const

Gets the width in pixels of the specified string.

If the string contains multiple lines, the width of the widest line is found. Please note that the correct number of arguments must be given if the text contains wildcards.

The string is handled as a right-to-left string and subdivided into smaller text strings to correctly handle mixing of left-to-right and right-to-left strings.

Parameters:

textDirection	The text direction.
text	A null-terminated Unicode string with arguments to insert if the text contains wildcards.
pArg	Variable arguments providing additional information inserted at wildcard placeholders.

Returns:

The string width RTL.

Protected Attributes Documentation

bAlignRow

uint8_t bAlignRow

The glyphs are saved with each row byte aligned.

baselineHeight

uint16_t baselineHeight

The baseline.

bPerPixel

uint8_t bPerPixel

The number of bits per pixel.

ellipsisCharacter

Unicode::UnicodeChar ellipsisCharacter

The ellipsis character used for truncating long texts.

fallbackCharacter

Unicode::UnicodeChar fallbackCharacter

The fallback character to use when no glyph exists for the wanted character.

fontHeight

uint16_t fontHeight

The font height in pixels.

maxPixelsLeft

uint8_t maxPixelsLeft

The maximum number of pixels a glyph extends to the left.

maxPixelsRight

uint8_t maxPixelsRight

The maximum number of pixels a glyph extends to the right.

pixelsAboveTop

uint8_t pixelsAboveTop

The number of pixels above the top.

pixelsBelowBottom

uint8_t pixelsBelowBottom

The number of pixels below the bottom.