TextRender¶
- class
Text Render class to paint Text paragraphs on a DisplayController.
This is a Text glyph and paragraph render. It uses a bitmap based fonts and typesets the text to provide.
You need to provide the text render with either a DisplayPainter or IDisplayController that serves as a target for the text rendering.
The TextRender does not include any Font definitions. When you render your text, you need to provide a pointer to wither the MonoFont structure, or a Adafruit compatible GFXfont structure. One these is used as the rendered font.
Monospaced MonoFonts
Mono has its own monospace-only font format MonoFont
This renderer has a palette like DisplayPainter, and uses it the blend the semi-transparent pixels in the font anti-aliasing. The font bitmap defines pixel intensities, that are the foreground opacity.
The MonoFont defines the text size and the anti-aliasing quality. Some fonts has 2 bit pixels, others have 4 bit pixels.
Adafruit GFXfonts
TextRender can also work with Adafruits proportionally spaced fonts, that include many different styles: Sans, serif, plain, italic, bold and combinations of these.
This format is still bitmap based, but it does not used semi-transparent pixels to achieve anti-aliasing. The bitmaps are one bit per pixel.
Because coherent glyphs might overlap each others bounding rects, this format does not draw text backgrounds. Since this will overwrite overlapping areas of text glyphs.
Line Layouts
The text rendering has two modes: line layout or not. Line layout means a text line always has a fixed height: the line separation height. This is critically when rendering multiline text layouts. But single line text will appear off-centered in a vertically centered box. The reason is the line height is much higher than the visual center of the text glyphs.
If you need to render a single line of text at the center of a box, you want to not use line layout mode. In this mode, text dimension height are the distance from the texts hightest to lowest point.
Public Types
-
enum type
mono::display::TextRender::
HorizontalAlignment
¶ The horizontal text alignment, when rendering inside rects.
Values:
Left justify text inside containing Rect
Justify at center of containing Rect
Right justify text inside containing Rect
-
enum type
mono::display::TextRender::
VerticalAlignmentType
¶ The horizontal text alignment, when rendering inside rects.
Values:
Place text at the top of containing Rect
Place text at the vertical center of containing Rect
Place text at the bottom of containing Rect
- typedef
Function interface that for character drawing routines
Public Functions
-
TextRender::
TextRender
(IDisplayController *displayCtrl)¶ Construct a TextRender that renders to a DisplayController Text Colors default to View::Standard colors.
- Parameters
displayCtrl
-A pointer to the display controller that is the render target
-
TextRender::
TextRender
(IDisplayController *displayCtrl, Color foreground, Color background)¶ Construct a TextRender that renders to a DisplayController You provide explicit text colors.
- Parameters
displayCtrl
-A pointer to the display controller that is the render target
foreground
-The text color
background
-the background color
-
TextRender::
TextRender
(const DisplayPainter &painter)¶ Construct a TextRender that renders to the DisplayController provided by a DisplayPainter. The painter current pencil colors are used for the text color.
- Parameters
painter
-The display painter to copy DisplayController and color palette from
- template <typename Context>
-
void mono::display::TextRender::layoutInRect(geo::Rect rect, const String text, const GFXfont & fontFace, Context * self, void(Context::*)(const geo::Point &position, const GFXfont &font, const GFXglyph *gfxGlyph, geo::Rect const &boundingRect, const int lineHeight) memptr, bool lineLayout)
Layout the string in a rect, using af callback to handle characters.
This method will parse a text string and trigger a callback for each character, providing the position and allowed dimension of each character.
- Parameters
rect
-The rectangle to render in
text
-The text string to render
fontFace
-A pointer the Adafruit GFX font to use
self
-A pointer to the callback method context object
memptr
-A pointer to the callback method
lineLayout
-Default:
true
, Render text as a multiline layout
-
void
mono::display::TextRender::
drawInRect
(geo::Rect rect, String text, const MonoFont &fontFace)¶ Renders a text string in a provided Rectangle.
THis method paints / renders the text in bounding rectangle. The text is always rendered with origin in the rectangles top left corner. If the provided Rect is not large enough, the text is clipped!
- Parameters
rect
-The rectangle to render in
text
-The text string to render
fontFace
-A pointer the fontface to use
-
geo::Size
mono::display::TextRender::
renderDimension
(String text, const MonoFont &fontFace)¶ Return the resulting dimension / size of some rendered text.
The final width and height of a rendered text, with the defined font face.
- Parameters
text
-The text to calculate the dimensions of
fontFace
-The font to use
-
void
mono::display::TextRender::
drawChar
(const geo::Point &position, const GFXfont &font, const GFXglyph *gfxGlyph, geo::Rect const &boundingRect, const int lineHeight)¶ Render a single Adafruit GfxFont character.
- Parameters
position
-The point where the glyph is rendered
font
-The Adafruit GfxFont to use
gfxGlyph
-The specific glyph to render
boundingRect
-The Rect that limits the render canvas (no paints beyond this Rect)
lineHeight
-The glyph height offset, to align glyphs on the same baseline
-
void
mono::display::TextRender::
drawInRect
(const geo::Rect &rect, String text, const GFXfont &fontFace, bool lineLayout)¶ Renders a text string in a provided Rectangle.
THis method paints / renders the text in bounding rectangle. The text is always rendered with origin in the rectangles top left corner. If the provided Rect is not large enough, the text is clipped!
- Parameters
rect
-The rectangle to render in
text
-The text string to render
fontFace
-A pointer the Adafruit GFX font to use
lineLayout
-Default:
true
, Render text as a multiline layout
-
geo::Size
mono::display::TextRender::
renderDimension
(String text, const GFXfont &fontFace, bool lineLayout)¶ Return the resulting dimension / size of some rendered text.
The final width and height of a rendered text, with the defined font face.
- Parameters
text
-The text to calculate the dimensions of
fontFace
-The font to use
lineLayout
-Default:
true
, use line layout or not
-
mono::geo::Rect
TextRender::
renderInRect
(const geo::Rect &rect, String text, const GFXfont &fontFace, bool lineLayout)¶ Return the calculated offset of the text in the drawing Rect.
The offset is returned in absolute coords, not the relative coords inside the drawing rect. The offset matters for text that is aligned other than left and top.
- Parameters
rect
-The drawing Rect, that the text should be rendered inside
text
-The text
fontFace
-The GFXfont to use
lineLayout
-Default:
true
, sets if lineLayout is used
-
void
TextRender::
setForeground
(Color fg)¶ Set the text color.
-
void
TextRender::
setBackground
(Color bg)¶ Set the background color. Transparent pixels will be blended with this color.
-
void
TextRender::
setAlignment
(HorizontalAlignment align)¶ Sets the texts justification within the drawing rect.
- Parameters
align
-The alignment
-
void
TextRender::
setAlignment
(VerticalAlignmentType vAlign)¶ Set the texts vertical alignment withnin the drawing rect.
- Parameters
vAlign
-The vertical alignment
-
Color
TextRender::
Foreground
()¶
const Get the current text color.
-
Color
TextRender::
Background
()¶
const Get the current text background color.
-
TextRender::HorizontalAlignment
TextRender::
Alignment
()¶
const Get the horizontal text alignment.
-
TextRender::VerticalAlignmentType
TextRender::
VerticalAlignment
()¶
const Get the vertical text alignment.
Protected Functions
-
void
mono::display::TextRender::
drawChar
(geo::Point position, char character, const MonoFont &font, geo::Rect const &boundingRect)¶ Render a single MonoFont character.
-
int
TextRender::
calcUnderBaseline
(String text, const GFXfont &font)¶ Calculated the maximum offset under the text baseline.
This method returns the maximum offset under the baseline for some text. Some characters (glyphs) has parts under the baseline, examples are lower-case g, p, q and j.
To align all glyphs in a text line, the character with the largest undershoot is found and returned here.
- Return
- The maximum offset below the text baseline
- Parameters
text
-The text content to process font The font face to use
-
void
TextRender::
writePixel
(uint8_t intensity, bool bg)¶ Blend and emit a single pixel to the DisplayController.
-
uint32_t
TextRender::
remainingTextlineWidth
(const GFXfont &font, const char *text)¶ Returns the pixel width of the text provided.
This method is used in multiline text rendering, to get the width of a stand-alone line inside a multiline text blob. Unlike renderDimensions that gets the width of the longest line, this method get the length of the current line.
- Return
- The pixel width of the line
- Parameters
font
-The font face to use
The
-C string text to get the current line from (until newline or end)
-
enum type