TextLabelView¶

class mono::ui::TextLabelView¶

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.

Inherits from mono::ui::View

Public Types

enum TextAlignment¶

Three ways of justifing text inside the TextLabel.

Values:

ALIGN_LEFT¶: Align text to the left

ALIGN_CENTER¶: Align text in the center

ALIGN_RIGHT¶: Align text to the right

enum VerticalTextAlignment¶

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

Values:

ALIGN_TOP¶: Align the text at the top of the label

ALIGN_MIDDLE¶: Align the text at in the middle of the label

ALIGN_BOTTOM¶: Align the text at the bottom of the label

Public Functions

TextLabelView(String txt = String ())¶

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(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(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(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 TextSize() const¶

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

mono::display::Color TextColor() const¶: Get the current color of the text.

TextLabelView::TextAlignment Alignment() const¶: Get the current horizontal text alignment.

TextLabelView::VerticalTextAlignment VerticalAlignment() const¶: Get the current vertical text alignment.

uint16_t TextPixelWidth() const¶: Get the width of the current text dimension.

uint16_t TextPixelHeight() const¶: Get the height of the current text dimension.

const MonoFont *Font() const¶: If not NULL, then returns the current selected MonoFont.

const GFXfont *GfxFont() const¶: If not NULL, then returns the current selected GFXfont.

mono::geo::Rect TextDimension() const¶: Returns the dimensions ( Size and offset Point ) of the text.

void 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 setTextColor(display::Color col)¶

void setBackgroundColor(display::Color col)¶

void setText(display::Color col)¶: Set the text color.

void setBackground(display::Color col)¶: Set the color behind the text.

void setAlignment(TextAlignment align)¶: Controls text justification: center, right, left.

void setAlignment(VerticalTextAlignment vAlign)¶: Set the texts vertical alignment: top, middle or bottom.

void 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 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 setText(const char *txt, bool resizeViewWidth)¶

void setText(String text, bool resizeViewWidth)¶

void 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 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 Text() const¶: Gets the content of the text label.

void 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.

void 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.

void 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 incrementalRepaint¶: This indicate if the next repaint should only repaint differences

void 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 *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 isTextMultiline() const¶

Check if the current text has newline characters.

This runs O(n)

Return: true is newlines are found