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 in pixels from the top of the line. | |
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 float | getScaleFactor() const |
Returns the scale factor. | |
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. | |
virtual bool | isVectorBasedFont() const |
Returns true if this Font is vector based. | |
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 in pixels from the top of the line.
The baseline position.
Note
It is not sufficient to allocate text areas with this height. Use getHeight for this.
getBitsPerPixel
virtual FORCE_INLINE_FUNCTION uint8_t getBitsPerPixel | ( | ) | const |
Gets bits per pixel for this font.
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?
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.
c | The Unicode character. |
The width in pixels of the specified character.
getContextualFormsTable
virtual const FontContextualFormsTable * getContextualFormsTable | ( | ) | const |
Gets the contextual forms table used in arabic fonts.
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.
The ellipsis character for the typography.
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.
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.
unicode | The character to look up. |
A pointer to the glyph node or null if the glyph was not found.
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.
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. |
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.
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.
The font height.
getKerning
virtual int8_t getKerning | ( | Unicode::UnicodeChar | prevChar , | const | |
const GlyphNode * | glyph | const | |||
) | const |
Gets the kerning distance between two characters.
prevChar | The Unicode value of the previous character. |
glyph | the glyph object for the current character. |
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.
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.
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.
text | The text. |
... | Variable arguments providing additional information. |
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.
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.
The pixels below bottom.
getScaleFactor
virtual float getScaleFactor | ( | ) | const |
Returns the scale factor.
The scale factor
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.
text | A null-terminated Unicode string. |
... | Variable arguments providing additional information inserted at wildcard placeholders. |
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.
text | A null-terminated Unicode string with arguments to insert if the text contains wildcards. |
... | Variable arguments providing additional information inserted at wildcard placeholders. |
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.
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. |
The width in pixels of the longest line of the specified string.
isVectorBasedFont
virtual bool isVectorBasedFont | ( | ) | const |
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.
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.
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().
The font height.
Deprecated
Please use getHeight() instead.
~Font
isInvisibleZeroWidth
static FORCE_INLINE_FUNCTION bool isInvisibleZeroWidth | ( | Unicode::UnicodeChar | character | ) | |
Query if 'character' is invisible, zero width.
character | The character. |
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.
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.
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. |
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.
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. |
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.