TextLabelView

class

A Text Label displays text strings on the display.

Use this UI view whenever you need to display text on the screen.

A text label renders text strings on the display. As all views the label lives inside a defined rectangle (viewRect), where the text is rendered. If the rectangle is smaller than the length of the text content, the content will cropped. If the rectangle is larger, then you can align the text inside the rectangle (left, center or right).

Example

You can mix and match mono strings with standard C strings when constructing TextLabels.

Create a label using a C string: 

TextLabelView lbl("This is a contant string");

Also you can use C strings allocated on the stack: 

char text[4] = {'m', 'o', 'n', 'o'};
TextLabelView lbl(text);

Above the TextLabel will take a copy of the input string, to ensure it can be accessed asynchronously.

Content

The text view contains it content (a String object), and therefore has a state. You get and set the content to update the rendered text on the display.When you set new text content the label automatically re-renders itself. (By calling scheduleRepaint)

Because the view is rendered asynchronously, its text content must be allocated on the heap. Therefore it uses the String as text storage. You can provide it with C strings, but these must allocated inside the .rodata segment of your binary. (Meaning they are static const.)

Text Format

Currently there are only one font type. But the text color and font can changed. You change these for parameters:

  • Text font (including size)
  • Text color
  • Text background color (the color behind the characters)

Getting text dimensions

To help you layout your views, you can query the TextLabel of the current width and height of its contents. The methods TextPixelWidth and TextPixelHeight, will return the texts dimensions in pixels

  • regardless of view rectangle. Also, you can use these methods before the view has been rendered.

Public Types

enum type mono::ui::TextLabelView::TextAlignment

Three ways of justifing text inside the TextLabel.

Values:

Align text to the left

Align text in the center

Align text to the right

enum type mono::ui::TextLabelView::VerticalTextAlignment

The Vertical justification of the text, inside the labels Rect.

Values:

Align the text at the top of the label

Align the text at in the middle of the label

Align the text at the bottom of the label

Public Functions

mono::ui::TextLabelView::TextLabelView(String txt)

Construct a text label with defined content, but no dimensions.

Before you can render the label you still need to set the view dimensions. This constructor take the String object as defined in the mono framework.

Parameters
  • txt -

    The labels text content (as a mono lightweight string)

TextLabelView::TextLabelView(const char *txt)

Construct a text label with defined content, but no dimensions.

Before you can render the label you still need to set the view dimensions. This constructor takes a static const C string pointer that must not exist on the stack! (It must live inside the .rodata segment.

Parameters
  • txt -

    A pointer to the static const C string (.rodata based)

TextLabelView::TextLabelView(geo::Rect rct, String txt)

Construct a label in a defined rectangle and with a string.

You provide the position and size of the label, along with its text content. You can call this constructor using a mono type string or a stack based C string - and it is automatically converted to a mono string:

int celcius = 22;

// char array (string) on the stack
char strArray[50];

// format the string content
sprintf(strArray,"%i celcius", celcius);

// construct the label with our stack based string
TextLabelView lbl(geo::Rect(0,0,100,100), strArray);

TextLabelView::TextLabelView(geo::Rect rct, const char *txt)

Construct a label in a defined rectangle and with a string.

You provide the position and size of the label, along with its text content. You can call this constructor using static const C string:

// construct the label with our stack based string
TextLabelView lbl(geo::Rect(0,0,100,100), "I am a .rodata string!");

uint8_t TextLabelView::TextSize()
const

The text size will be phased out in coming releases. You control text by changing the font.

mono::display::Color TextLabelView::TextColor()
const

Get the current color of the text.

TextLabelView::TextAlignment TextLabelView::Alignment()
const

Get the current horizontal text alignment.

TextLabelView::VerticalTextAlignment TextLabelView::VerticalAlignment()
const

Get the current vertical text alignment.

uint16_t TextLabelView::TextPixelWidth()
const

Get the width of the current text dimension.

uint16_t TextLabelView::TextPixelHeight()
const

Get the height of the current text dimension.

const MonoFont *TextLabelView::Font()
const

If not NULL, then returns the current selected MonoFont.

const GFXfont *mono::ui::TextLabelView::GfxFont()
const

If not NULL, then returns the current selected GFXfont.

mono::geo::Rect TextLabelView::TextDimension()
const

Returns the dimensions ( Size and offset Point ) of the text.

void TextLabelView::setTextSize(uint8_t newSize)

We will phase out this attribute in the coming releases. To change the font size you should rely on the font face.

If you set this to 1 the old font (very bulky) font will be used. Any other value will load the new default font.

void TextLabelView::setTextColor(display::Color col)

void TextLabelView::setBackgroundColor(display::Color col)

void mono::ui::TextLabelView::setText(display::Color col)

Set the text color.

void mono::ui::TextLabelView::setBackground(display::Color col)

Set the color behind the text.

void TextLabelView::setAlignment(TextAlignment align)

Controls text justification: center, right, left.

void TextLabelView::setAlignment(VerticalTextAlignment vAlign)

Set the texts vertical alignment: top, middle or bottom.

void mono::ui::TextLabelView::setText(const char *text)

Change the text content of the Text label, and schedules repaint.

This method updates the text that is rendered by the textlabel. It automatically schedules an incremental (fast) repaint.

Parameters
  • text -

    The C string text to render

void mono::ui::TextLabelView::setText(String text)

Change the text content of the Text label, and schedules repaint.

This method updates the text that is rendered by the textlabel. It automatically schedules an incremental (fast) repaint.

Parameters
  • text -

    The Mono string text to render

void mono::ui::TextLabelView::setText(const char *txt, bool resizeViewWidth)

void mono::ui::TextLabelView::setText(String text, bool resizeViewWidth)

void mono::ui::TextLabelView::setFont(MonoFont const &newFont)

Set a new font face on the label.

You can pass any MonoFont to the label to change its appearence. Fonts are header files that you must include youself. Each header file defines a font in a specific size.

The header file defines a global const variable that you pass to to this method.

Parameters
  • newFont -

    The mono-spaced to use with the textlabel

void mono::ui::TextLabelView::setFont(GFXfont const &font)

Set a new font face on the label.

You can pass any Adafruit GfxFont to the label to change its appearence. Fonts are header files that you must include youself. Each header file defines a font in a specific size.

The header file defines a global const variable that you pass to to this method.

mono::String TextLabelView::Text()
const

Gets the content of the text label.

void mono::ui::TextLabelView::scheduleFastRepaint()

Repaints the view, using incremental repaints if possible.

This method might be faster than scheduleRepaint, since this repaint allows the text to be repainted incrementally. This means fast repaint of counters or fade animations.

If you experience rendering errors, you should use the normal scheduleRepaint method.

virtual void TextLabelView::scheduleRepaint()

Schedule this view for repaint at next display refresh.

This method add the view to the display systems re-paint queue. The queue is executed right after a display refresh. This helps prevent graphical artifacts, when running on a single display buffer system.

Because views have no state information, they do not know when to repaint themselves. You, or classes using views, must call this repaint method when the view is ready to be repainted.

virtual void TextLabelView::repaint()

Repaint the view content, using the View::painter.

Re-paint the view content. This method should be called when the view content has changed. You can call this method directly, but it might cause graphics artifacts because the display is not double buffered. Instead you should schedule a repaint by calling the scheduleRepaint() method. This method will schedule the repaint, right after the next display update.

The display system will not schedule any repaints automatically. The view does not contain any state information, so you or other classes utilizing view must schedule repaints.

In subclasses of View, this method must be overwritten.

Public Members

bool mono::ui::TextLabelView::incrementalRepaint

This indicate if the next repaint should only repaint differences

void TextLabelView::setBackground

Set the color behind the text

Public Static Functions

static const MonoFont* StandardTextFont mono::ui::TextLabelView::__DEPRECATED("use the similar variable of the GfxFontType", "StandardGfxFont")

This is the default font for all TextLabelView‘s.

This points to the default Textlabel font. You can overwrite this in your own code to change the default appearence of all TextLabels.

You can also overwrite it to use a less memory expensive (lower quality) font face.

Public Static Attributes

const GFXfont *mono::ui::TextLabelView::StandardGfxFont

This is the default font for all TextLabelView‘s.

This points to the default Textlabel font. You can overwrite this in your own code to change the default appearence of all TextLabels.

You can also overwrite it to use a less memory expensive (lower quality) font face.

Protected Functions

bool TextLabelView::isTextMultiline()
const

Check if the current text has newline characters.

This runs O(n)

Return
true is newlines are found