Label (lv_label)

---

Overview

A Label is the Widget used to display text.

Parts and Styles

• LV_PART_MAIN Uses the typical background and text properties. Padding values can be used to add space between the text and the edges of the Label's background.
• LV_PART_SCROLLBAR The scrollbar that is shown when the text is larger than the Widget's size.
• LV_PART_SELECTED Tells the style of the selected text. Only text_color and bg_color style properties can be used.

Usage

Set text

You can set the text on a Label at runtime with lv_label_set_text(label, "New text"). This will allocate a buffer dynamically, and the provided string will be copied into that buffer. Therefore, you don't need to keep the text you pass to lv_label_set_text in scope after that function returns.

With lv_label_set_text_fmt(label, fmt, ...) printf formatting can be used to set the text. Example: lv_label_set_text_fmt(label, "Value: %d", 15).

Labels are able to show text from a static character buffer as well. To do so, use lv_label_set_text_static(label, "Text"). In this case, the text is not stored in dynamic memory and the given buffer is used directly instead. This means that the contents of the character buffer must remain valid for the life of the label or until another buffer is set via one of the above functions.

const strings are safe to use with lv_label_set_text_static since they are stored in ROM memory, which is always accessible.

Set translation tag

When using LVGL's translation module, you can bind a translation tag to a label directly with lv_label_set_translation_tag(label, tag). After this function is called, future changes to the language will automatically update the label's text to display the corresponding translation for that tag in the new language.

Newline

Newline characters are handled automatically by the Label Widget. You can use \n to make a line break. For example: "line1\nline2\n\nline4"

Long modes

By default, the width and height of the Label are set to LV_SIZE_CONTENT. Thus, the size of the Label is automatically expanded to the text size + padding + border width. Otherwise, if the width or height are explicitly set (using e.g.lv_obj_set_width or a layout), the lines wider than the Label's width can be manipulated according to several long mode policies. Similarly, the policies can be applied if the height of the text is greater than the height of the Label.

• LV_LABEL_LONG_MODE_WRAP Wrap lines that are too long. If the height is LV_SIZE_CONTENT the Label's height will be expanded, otherwise the text will be clipped. (Default)
• LV_LABEL_LONG_MODE_DOTS Replaces the last 3 characters from bottom right corner of the Label with dots (.)
• LV_LABEL_LONG_MODE_SCROLL If the text is wider than the label, scroll it horizontally back and forth. If it's higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence.
• LV_LABEL_LONG_MODE_SCROLL_CIRCULAR If the text is wider than the Label, scroll it horizontally continuously. If it's higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence.
• LV_LABEL_LONG_MODE_CLIP Simply clip the parts of the text outside the Label.

You can specify the long mode with lv_label_set_long_mode(label, LV_LABEL_LONG_...)

Note that LV_LABEL_LONG_MODE_DOTS manipulates the text buffer in-place in order to add/remove the dots. When lv_label_set_text or lv_label_set_array_text are used, a separate buffer is allocated and this implementation detail is unnoticed. This is not the case with lv_label_set_text_static. The buffer you pass to lv_label_set_text_static must be writable if you plan to use LV_LABEL_LONG_MODE_DOTS.

Text recolor

In the text, you can use commands to recolor parts of the text. For example: Write a #ff0000 red# word. This feature can be enabled individually for each label by lv_label_set_recolor(label, en) function. In the context of word-wrapped text, any Recoloring started on a line will be terminated at the end of the line where the line is wrapped if it was not already terminated by an ending # in the text.

Text selection

If enabled by LV_LABEL_TEXT_SELECTION part of the text can be selected. It's similar to when you use your mouse on a PC to select text. The whole mechanism (click and select the text as you drag your finger/mouse) is implemented in Text Area (lv_textarea) and the Label Widget only allows programmatic text selection with lv_label_get_text_selection_start(label, start_char_index) and lv_label_get_text_selection_end(label, end_char_index).

Text alignment

To horizontally align the lines of a Label the text_align style property can be used with lv_obj_set_style_text_align or lv_style_set_text_align, passing one of the LV_TEXT_ALIGN_... enumeration values. Note that this has a visible effect only if:

• the Label Widget's width is larger than the width of the longest line of text, and
• the text has multiple lines with different line lengths.

Very long text

LVGL can efficiently handle very long (e.g. > 40k characters) Labels by saving some extra data (~12 bytes) to speed up drawing. To enable this feature, set LV_LABEL_LONG_TXT_HINT to 1 in lv_conf.h.

Custom scrolling animations

Some aspects of the scrolling animations in long modes LV_LABEL_LONG_SCROLL and LV_LABEL_LONG_SCROLL_CIRCULAR can be customized by setting the Label's animation style property, using lv_style_set_anim. It will be treated as a template which will be used to create the scroll animations.

Symbols

The Labels can display symbols alongside letters (or on their own). Read the Overview section to learn more about symbols.

Data binding

To get familiar with observers, subjects, and data bindings in general visit the Observer page.

This method of subscribing to a Subject affects a Label Widget's text. The Subject can be a STRING, POINTER, INTEGER, or FLOAT type.

When the subscription occurs, and each time the Subject's value is changed thereafter, the Subject's value is used to update the Label's text as follows:

Note that this is a one-way binding (Subject ===> Widget).

• lv_label_bind_text(label, &subject, format_string)

The format_string Argument

The format_string argument is optional and if provided, must contain exactly 1 printf-like format specifier and be one of the following:

If NULL is passed for the format_string argument:

Example: "%d °C"

As usual with format strings, %% is used to get %. For example %d%%

Events

No special events are sent by Label Widgets. By default, Label Widgets are created without the LV_OBJ_FLAG_CLICKABLE flag, but you can add it to make a Label Widget emit LV_EVENT_CLICKED events if desired.

Keys

No Keys are processed by Label Widgets.

Examples

Line wrap, recoloring and scrolling

Text shadow

Show LTR, RTL and Chinese texts

Draw label with gradient color

Customize circular scrolling animation

Monospace font

Assign a translation tag to a label

API