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)