Label (lv_label)
Overview
A Label is the Widget used to display text.
Parts and Styles
LV_PART_MAIN
Uses all 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. Onlytext_color
andbg_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.
Warning
Do not use const
strings with lv_label_set_text_static()
when the
Label is being used in LV_LABEL_LONG_DOT
mode since the Label
will attempt to do an in-place edit of the string. This will cause an MCU
exception by attempting to modify program memory (ROM).
Caution
If your Label is updated with new strings rapidly (e.g. > 30X / second, such as RPM in a dashboard, or an ADC value), and the length of those strings changes frequently, it is advisable to:
allocate a static string buffer large enough contain the largest possible string,
update that buffer with the new strings only when they will make a visible difference for the end user, and
update the Label with lv_label_set_text_static(label, buffer) using that buffer.
Reason: if you use lv_label_set_text(label, new_text), a memory realloc() will be forced every time the length of the string changes. That MCU overhead can be avoided by doing the above.
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_WRAP
Wrap lines that are too long. If the height isLV_SIZE_CONTENT
the Label's height will be expanded, otherwise the text will be clipped. (Default)LV_LABEL_LONG_DOT
Replaces the last 3 characters from bottom right corner of the Label with dots (.
)LV_LABEL_LONG_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_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_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_DOT
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_DOT
.
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 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 Font (lv_font) section to learn more about symbols.
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.
Further Reading
Learn more about Base-Widget Events emitted by all Widgets.
Learn more about Events.
Keys
No Keys are processed by Label Widgets.
Further Reading
Learn more about Keys.
Example
Line wrap, recoloring and scrolling
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_LABEL && LV_BUILD_EXAMPLES
/**
* Show line wrap, re-color, line align and text scrolling.
*/
void lv_example_label_1(void)
{
lv_obj_t * label1 = lv_label_create(lv_screen_active());
lv_label_set_long_mode(label1, LV_LABEL_LONG_MODE_WRAP); /*Break the long lines*/
lv_label_set_text(label1, "Recolor is not supported for v9 now.");
lv_obj_set_width(label1, 150); /*Set smaller width to make the lines wrap*/
lv_obj_set_style_text_align(label1, LV_TEXT_ALIGN_CENTER, 0);
lv_obj_align(label1, LV_ALIGN_CENTER, 0, -40);
lv_obj_t * label2 = lv_label_create(lv_screen_active());
lv_label_set_long_mode(label2, LV_LABEL_LONG_MODE_SCROLL_CIRCULAR); /*Circular scroll*/
lv_obj_set_width(label2, 150);
lv_label_set_text(label2, "It is a circularly scrolling text. ");
lv_obj_align(label2, LV_ALIGN_CENTER, 0, 40);
}
#endif
Text shadow
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_LABEL && LV_BUILD_EXAMPLES
/**
* Create a fake text shadow
*/
void lv_example_label_2(void)
{
/*Create a style for the shadow*/
static lv_style_t style_shadow;
lv_style_init(&style_shadow);
lv_style_set_text_opa(&style_shadow, LV_OPA_30);
lv_style_set_text_color(&style_shadow, lv_color_black());
/*Create a label for the shadow first (it's in the background)*/
lv_obj_t * shadow_label = lv_label_create(lv_screen_active());
lv_obj_add_style(shadow_label, &style_shadow, 0);
/*Create the main label*/
lv_obj_t * main_label = lv_label_create(lv_screen_active());
lv_label_set_text(main_label, "A simple method to create\n"
"shadows on a text.\n"
"It even works with\n\n"
"newlines and spaces.");
/*Set the same text for the shadow label*/
lv_label_set_text(shadow_label, lv_label_get_text(main_label));
/*Position the main label*/
lv_obj_align(main_label, LV_ALIGN_CENTER, 0, 0);
/*Shift the second label down and to the right by 2 pixel*/
lv_obj_align_to(shadow_label, main_label, LV_ALIGN_TOP_LEFT, 2, 2);
}
#endif
Show LTR, RTL and Chinese texts
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_LABEL && LV_BUILD_EXAMPLES && LV_FONT_DEJAVU_16_PERSIAN_HEBREW && LV_FONT_SIMSUN_16_CJK && LV_USE_BIDI
/**
* Show mixed LTR, RTL and Chinese label
*/
void lv_example_label_3(void)
{
lv_obj_t * ltr_label = lv_label_create(lv_screen_active());
lv_label_set_text(ltr_label, "In modern terminology, a microcontroller is similar to a system on a chip (SoC).");
lv_obj_set_style_text_font(ltr_label, &lv_font_montserrat_16, 0);
lv_obj_set_width(ltr_label, 310);
lv_obj_align(ltr_label, LV_ALIGN_TOP_LEFT, 5, 5);
lv_obj_t * rtl_label = lv_label_create(lv_screen_active());
lv_label_set_text(rtl_label,
"מעבד, או בשמו המלא יחידת עיבוד מרכזית (באנגלית: CPU - Central Processing Unit).");
lv_obj_set_style_base_dir(rtl_label, LV_BASE_DIR_RTL, 0);
lv_obj_set_style_text_font(rtl_label, &lv_font_dejavu_16_persian_hebrew, 0);
lv_obj_set_width(rtl_label, 310);
lv_obj_align(rtl_label, LV_ALIGN_LEFT_MID, 5, 0);
lv_obj_t * cz_label = lv_label_create(lv_screen_active());
lv_label_set_text(cz_label,
"嵌入式系统(Embedded System),\n是一种嵌入机械或电气系统内部、具有专一功能和实时计算性能的计算机系统。");
lv_obj_set_style_text_font(cz_label, &lv_font_simsun_16_cjk, 0);
lv_obj_set_width(cz_label, 310);
lv_obj_align(cz_label, LV_ALIGN_BOTTOM_LEFT, 5, -5);
}
#endif
Draw label with gradient color
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_LABEL && LV_FONT_MONTSERRAT_24 && LV_USE_CANVAS && LV_BUILD_EXAMPLES && LV_DRAW_SW_COMPLEX
#define MASK_WIDTH 150
#define MASK_HEIGHT 60
static void generate_mask(lv_draw_buf_t * mask, int32_t w, int32_t h, const char * txt)
{
/*Create a "8 bit alpha" canvas and clear it*/
lv_obj_t * canvas = lv_canvas_create(lv_screen_active());
lv_canvas_set_draw_buf(canvas, mask);
lv_canvas_fill_bg(canvas, lv_color_black(), LV_OPA_TRANSP);
lv_layer_t layer;
lv_canvas_init_layer(canvas, &layer);
/*Draw a label to the canvas. The result "image" will be used as mask*/
lv_draw_label_dsc_t label_dsc;
lv_draw_label_dsc_init(&label_dsc);
label_dsc.color = lv_color_white();
label_dsc.align = LV_TEXT_ALIGN_CENTER;
label_dsc.text = txt;
label_dsc.font = &lv_font_montserrat_24;
lv_area_t a = {0, 0, w - 1, h - 1};
lv_draw_label(&layer, &label_dsc, &a);
lv_canvas_finish_layer(canvas, &layer);
lv_obj_delete(canvas);
}
/**
* Draw label with gradient color
*/
void lv_example_label_4(void)
{
/* Create the mask of a text by drawing it to a canvas*/
LV_DRAW_BUF_DEFINE_STATIC(mask, MASK_WIDTH, MASK_HEIGHT, LV_COLOR_FORMAT_L8);
LV_DRAW_BUF_INIT_STATIC(mask);
generate_mask(&mask, MASK_WIDTH, MASK_HEIGHT, "Text with gradient");
/* Create an object from where the text will be masked out.
* Now it's a rectangle with a gradient but it could be an image too*/
lv_obj_t * grad = lv_obj_create(lv_screen_active());
lv_obj_set_size(grad, MASK_WIDTH, MASK_HEIGHT);
lv_obj_center(grad);
lv_obj_set_style_bg_color(grad, lv_color_hex(0xff0000), 0);
lv_obj_set_style_bg_grad_color(grad, lv_color_hex(0x0000ff), 0);
lv_obj_set_style_bg_grad_dir(grad, LV_GRAD_DIR_HOR, 0);
lv_obj_set_style_bitmap_mask_src(grad, &mask, 0);
}
#endif
Customize circular scrolling animation
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_LABEL && LV_BUILD_EXAMPLES
/**
* Show customizing the circular scrolling animation of a label with `LV_LABEL_LONG_MODE_SCROLL_CIRCULAR`
* long mode.
*/
void lv_example_label_5(void)
{
static lv_anim_t animation_template;
static lv_style_t label_style;
lv_anim_init(&animation_template);
lv_anim_set_delay(&animation_template, 1000); /*Wait 1 second to start the first scroll*/
lv_anim_set_repeat_delay(&animation_template,
3000); /*Repeat the scroll 3 seconds after the label scrolls back to the initial position*/
/*Initialize the label style with the animation template*/
lv_style_init(&label_style);
lv_style_set_anim(&label_style, &animation_template);
lv_obj_t * label1 = lv_label_create(lv_screen_active());
lv_label_set_long_mode(label1, LV_LABEL_LONG_MODE_SCROLL_CIRCULAR); /*Circular scroll*/
lv_obj_set_width(label1, 150);
lv_label_set_text(label1, "It is a circularly scrolling text. ");
lv_obj_align(label1, LV_ALIGN_CENTER, 0, 40);
lv_obj_add_style(label1, &label_style, LV_STATE_DEFAULT); /*Add the style to the label*/
}
#endif