TextRender

class mono::display::TextRender

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 HorizontalAlignment

The horizontal text alignment, when rendering inside rects.

Values:

ALIGN_LEFT

Left justify text inside containing Rect

ALIGN_CENTER

Justify at center of containing Rect

ALIGN_RIGHT

Right justify text inside containing Rect

enum VerticalAlignmentType

The horizontal text alignment, when rendering inside rects.

Values:

ALIGN_TOP

Place text at the top of containing Rect

ALIGN_MIDDLE

Place text at the vertical center of containing Rect

ALIGN_BOTTOM

Place text at the bottom of containing Rect

typedef void (*charDrawFunction)(geo::Point &position, char character, const GFXfont &font, geo::Rect const &boundRect, int lineHeight)

Function interface that for character drawing routines

Public Functions

TextRender(IDisplayController *displayCtrl = 0)

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(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(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 = true)

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 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 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 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 drawInRect(const geo::Rect &rect, String text, const GFXfont &fontFace, bool lineLayout = true)

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 renderDimension(String text, const GFXfont &fontFace, bool lineLayout = true)

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 renderInRect(const geo::Rect &rect, String text, const GFXfont &fontFace, bool lineLayout = true)

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 setForeground(Color fg)

Set the text color.

void setBackground(Color bg)

Set the background color. Transparent pixels will be blended with this color.

void setAlignment(HorizontalAlignment align)

Sets the texts justification within the drawing rect.

Parameters
  • align: The alignment

void setAlignment(VerticalAlignmentType vAlign)

Set the texts vertical alignment withnin the drawing rect.

Parameters
  • vAlign: The vertical alignment

Color Foreground() const

Get the current text color.

Color Background() const

Get the current text background color.

TextRender::HorizontalAlignment Alignment() const

Get the horizontal text alignment.

TextRender::VerticalAlignmentType VerticalAlignment() const

Get the vertical text alignment.

Protected Functions

void drawChar(geo::Point position, char character, const MonoFont &font, geo::Rect const &boundingRect)

Render a single MonoFont character.

int 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 writePixel(uint8_t intensity, bool bg = false)

Blend and emit a single pixel to the DisplayController.

uint32_t 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)