Label (lv_label)¶
Overview¶
A label is the basic object type that is used to display text.
Parts and Styles¶
LV_PART_MAIN
Uses all the typical background properties and the text properties. The padding values can be used to add space between the text and the 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, "Value: %d", 15)
printf formatting can be used to set the text.
Labels are able to show text from a static character buffer. To do so, use lv_label_set_text_static(label, "Text")
.
In this case, the text is not stored in the dynamic memory and the given buffer is used directly instead.
This means that the array can't be a local variable which goes out of scope when the function exits.
Constant strings are safe to use with lv_label_set_text_static
(except when used with LV_LABEL_LONG_DOT
, as it modifies the buffer in-place), as they are stored in ROM memory, which is always accessible.
Newline¶
Newline characters are handled automatically by the label object. 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 is set to LV_SIZE_CONTENT
. Therefore, the size of the label is automatically expanded to the text size.
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 too long lines. 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 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()
function.
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 a 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 manual text selection with
lv_label_get_text_selection_start(label, start_char_index)
and lv_label_get_text_selection_start(label, end_char_index)
.
Very long texts¶
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 1
in lv_conf.h
.
Events¶
No special events are sent by the Label.
See the events of the Base object too.
Learn more about Events.
Example¶
Line wrap, recoloring and scrolling¶
C code
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_scr_act());
lv_label_set_long_mode(label1, LV_LABEL_LONG_WRAP); /*Break the long lines*/
lv_label_set_recolor(label1, true); /*Enable re-coloring by commands in the text*/
lv_label_set_text(label1, "#0000ff Re-color# #ff00ff words# #ff0000 of a# label, align the lines to the center "
"and wrap long text automatically.");
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_scr_act());
lv_label_set_long_mode(label2, LV_LABEL_LONG_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
#
# Show line wrap, re-color, line align and text scrolling.
#
label1 = lv.label(lv.scr_act())
label1.set_long_mode(lv.label.LONG.WRAP) # Break the long lines*/
label1.set_recolor(True) # Enable re-coloring by commands in the text
label1.set_text("#0000ff Re-color# #ff00ff words# #ff0000 of a# label, align the lines to the center"
"and wrap long text automatically.")
label1.set_width(150) # Set smaller width to make the lines wrap
label1.set_style_text_align(lv.ALIGN.CENTER, 0)
label1.align(lv.ALIGN.CENTER, 0, -40)
label2 = lv.label(lv.scr_act())
label2.set_long_mode(lv.label.LONG.SCROLL_CIRCULAR) # Circular scroll
label2.set_width(150)
label2.set_text("It is a circularly scrolling text. ")
label2.align(lv.ALIGN.CENTER, 0, 40)
Text shadow¶
C code
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_scr_act());
lv_obj_add_style(shadow_label, &style_shadow, 0);
/*Create the main label*/
lv_obj_t * main_label = lv_label_create(lv_scr_act());
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
#
# Create a fake text shadow
#
# Create a style for the shadow
style_shadow = lv.style_t()
style_shadow.init()
style_shadow.set_text_opa(lv.OPA._30)
style_shadow.set_text_color(lv.color_black())
# Create a label for the shadow first (it's in the background)
shadow_label = lv.label(lv.scr_act())
shadow_label.add_style(style_shadow, 0)
# Create the main label
main_label = lv.label(lv.scr_act())
main_label.set_text("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
shadow_label.set_text(lv.label.get_text(main_label))
# Position the main label
main_label.align(lv.ALIGN.CENTER, 0, 0)
# Shift the second label down and to the right by 2 pixel
shadow_label.align_to(main_label, lv.ALIGN.TOP_LEFT, 2, 2)
Show LTR, RTL and Chinese texts¶
C code
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_scr_act());
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_scr_act());
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_scr_act());
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
import fs_driver
#
# Show mixed LTR, RTL and Chinese label
#
ltr_label = lv.label(lv.scr_act())
ltr_label.set_text("In modern terminology, a microcontroller is similar to a system on a chip (SoC).")
# ltr_label.set_style_text_font(ltr_label, &lv_font_montserrat_16, 0);
fs_drv = lv.fs_drv_t()
fs_driver.fs_register(fs_drv, 'S')
try:
ltr_label.set_style_text_font(ltr_label, lv.font_montserrat_16, 0)
except:
font_montserrat_16 = lv.font_load("S:../../assets/font/montserrat-16.fnt")
ltr_label.set_style_text_font(font_montserrat_16, 0)
ltr_label.set_width(310)
ltr_label.align(lv.ALIGN.TOP_LEFT, 5, 5)
rtl_label = lv.label(lv.scr_act())
rtl_label.set_text("מעבד, או בשמו המלא יחידת עיבוד מרכזית (באנגלית: CPU - Central Processing Unit).")
rtl_label.set_style_base_dir(lv.BASE_DIR.RTL, 0)
rtl_label.set_style_text_font(lv.font_dejavu_16_persian_hebrew, 0)
rtl_label.set_width(310)
rtl_label.align(lv.ALIGN.LEFT_MID, 5, 0)
font_simsun_16_cjk = lv.font_load("S:../../assets/font/lv_font_simsun_16_cjk.fnt")
cz_label = lv.label(lv.scr_act())
cz_label.set_style_text_font(font_simsun_16_cjk, 0)
cz_label.set_text("嵌入式系统(Embedded System),\n是一种嵌入机械或电气系统内部、具有专一功能和实时计算性能的计算机系统。")
cz_label.set_width(310)
cz_label.align(lv.ALIGN.BOTTOM_LEFT, 5, -5)
Draw label with gradient color¶
C code
GitHub#include "../../lv_examples.h"
#if LV_USE_LABEL && LV_USE_CANVAS && LV_BUILD_EXAMPLES && LV_DRAW_COMPLEX
#define MASK_WIDTH 100
#define MASK_HEIGHT 45
static void add_mask_event_cb(lv_event_t * e)
{
static lv_draw_mask_map_param_t m;
static int16_t mask_id;
lv_event_code_t code = lv_event_get_code(e);
lv_obj_t * obj = lv_event_get_target(e);
lv_opa_t * mask_map = lv_event_get_user_data(e);
if(code == LV_EVENT_COVER_CHECK) {
lv_event_set_cover_res(e, LV_COVER_RES_MASKED);
}
else if(code == LV_EVENT_DRAW_MAIN_BEGIN) {
lv_draw_mask_map_init(&m, &obj->coords, mask_map);
mask_id = lv_draw_mask_add(&m, NULL);
}
else if(code == LV_EVENT_DRAW_MAIN_END) {
lv_draw_mask_free_param(&m);
lv_draw_mask_remove_id(mask_id);
}
}
/**
* Draw label with gradient color
*/
void lv_example_label_4(void)
{
/* Create the mask of a text by drawing it to a canvas*/
static lv_opa_t mask_map[MASK_WIDTH * MASK_HEIGHT];
/*Create a "8 bit alpha" canvas and clear it*/
lv_obj_t * canvas = lv_canvas_create(lv_scr_act());
lv_canvas_set_buffer(canvas, mask_map, MASK_WIDTH, MASK_HEIGHT, LV_IMG_CF_ALPHA_8BIT);
lv_canvas_fill_bg(canvas, lv_color_black(), LV_OPA_TRANSP);
/*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;
lv_canvas_draw_text(canvas, 5, 5, MASK_WIDTH, &label_dsc, "Text with gradient");
/*The mask is reads the canvas is not required anymore*/
lv_obj_del(canvas);
/* 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_scr_act());
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_add_event_cb(grad, add_mask_event_cb, LV_EVENT_ALL, mask_map);
}
#endif
Error encountered while trying to open /home/runner/work/lvgl/lvgl/examples/widgets/label/lv_example_label_4.py
API¶
Typedefs
-
typedef uint8_t lv_label_long_mode_t¶
Enums
-
enum [anonymous]¶
Long mode behaviors. Used in 'lv_label_ext_t'
Values:
-
enumerator LV_LABEL_LONG_WRAP¶
Keep the object width, wrap the too long lines and expand the object height
-
enumerator LV_LABEL_LONG_DOT¶
Keep the size and write dots at the end if the text is too long
-
enumerator LV_LABEL_LONG_SCROLL¶
Keep the size and roll the text back and forth
-
enumerator LV_LABEL_LONG_SCROLL_CIRCULAR¶
Keep the size and roll the text circularly
-
enumerator LV_LABEL_LONG_CLIP¶
Keep the size and clip the text out of it
-
enumerator LV_LABEL_LONG_WRAP¶
Functions
-
LV_EXPORT_CONST_INT(LV_LABEL_DOT_NUM)¶
-
LV_EXPORT_CONST_INT(LV_LABEL_POS_LAST)¶
-
LV_EXPORT_CONST_INT(LV_LABEL_TEXT_SELECTION_OFF)¶
-
lv_obj_t *lv_label_create(lv_obj_t *parent)¶
Create a label object
- Parameters
parent -- pointer to an object, it will be the parent of the new label.
- Returns
pointer to the created button
-
void lv_label_set_text(lv_obj_t *obj, const char *text)¶
Set a new text for a label. Memory will be allocated to store the text by the label.
- Parameters
obj -- pointer to a label object
text -- '\0' terminated character string. NULL to refresh with the current text.
- void lv_label_set_text_fmt (lv_obj_t *obj, const char *fmt,...) LV_FORMAT_ATTRIBUTE(2
- void void lv_label_set_text_static (lv_obj_t *obj, const char *text)
Set a static text. It will not be saved by the label so the 'text' variable has to be 'alive' while the label exists.
- Parameters
obj -- pointer to a label object
text -- pointer to a text. NULL to refresh with the current text.
-
void lv_label_set_long_mode(lv_obj_t *obj, lv_label_long_mode_t long_mode)¶
Set the behavior of the label with longer text then the object size
- Parameters
obj -- pointer to a label object
long_mode -- the new mode from 'lv_label_long_mode' enum. In LV_LONG_WRAP/DOT/SCROLL/SCROLL_CIRC the size of the label should be set AFTER this function
-
void lv_label_set_text_sel_start(lv_obj_t *obj, uint32_t index)¶
Set where text selection should start
- Parameters
obj -- pointer to a label object
index -- character index from where selection should start.
LV_LABEL_TEXT_SELECTION_OFF
for no selection
-
void lv_label_set_text_sel_end(lv_obj_t *obj, uint32_t index)¶
Set where text selection should end
- Parameters
obj -- pointer to a label object
index -- character index where selection should end.
LV_LABEL_TEXT_SELECTION_OFF
for no selection
-
char *lv_label_get_text(const lv_obj_t *obj)¶
Get the text of a label
- Parameters
obj -- pointer to a label object
- Returns
the text of the label
-
lv_label_long_mode_t lv_label_get_long_mode(const lv_obj_t *obj)¶
Get the long mode of a label
- Parameters
obj -- pointer to a label object
- Returns
the current long mode
-
bool lv_label_get_recolor(const lv_obj_t *obj)¶
Get the recoloring attribute
- Parameters
obj -- pointer to a label object
- Returns
true: recoloring is enabled, false: disable
-
void lv_label_get_letter_pos(const lv_obj_t *obj, uint32_t char_id, lv_point_t *pos)¶
Get the relative x and y coordinates of a letter
- Parameters
obj -- pointer to a label object
index -- index of the character [0 ... text length - 1]. Expressed in character index, not byte index (different in UTF-8)
pos -- store the result here (E.g. index = 0 gives 0;0 coordinates if the text if aligned to the left)
-
uint32_t lv_label_get_letter_on(const lv_obj_t *obj, lv_point_t *pos_in)¶
Get the index of letter on a relative point of a label.
- Parameters
obj -- pointer to label object
pos -- pointer to point with coordinates on a the label
- Returns
The index of the letter on the 'pos_p' point (E.g. on 0;0 is the 0. letter if aligned to the left) Expressed in character index and not byte index (different in UTF-8)
-
bool lv_label_is_char_under_pos(const lv_obj_t *obj, lv_point_t *pos)¶
Check if a character is drawn under a point.
- Parameters
obj -- pointer to a label object
pos -- Point to check for character under
- Returns
whether a character is drawn under the point
-
uint32_t lv_label_get_text_selection_start(const lv_obj_t *obj)¶
Get the selection start index.
- Parameters
obj -- pointer to a label object.
- Returns
selection start index.
LV_LABEL_TEXT_SELECTION_OFF
if nothing is selected.
-
uint32_t lv_label_get_text_selection_end(const lv_obj_t *obj)¶
Get the selection end index.
- Parameters
obj -- pointer to a label object.
- Returns
selection end index.
LV_LABEL_TXT_SEL_OFF
if nothing is selected.
-
void lv_label_ins_text(lv_obj_t *obj, uint32_t pos, const char *txt)¶
Insert a text to a label. The label text can not be static.
- Parameters
obj -- pointer to a label object
pos -- character index to insert. Expressed in character index and not byte index. 0: before first char. LV_LABEL_POS_LAST: after last char.
txt -- pointer to the text to insert
-
void lv_label_cut_text(lv_obj_t *obj, uint32_t pos, uint32_t cnt)¶
Delete characters from a label. The label text can not be static.
- Parameters
obj -- pointer to a label object
pos -- character index from where to cut. Expressed in character index and not byte index. 0: start in from of the first character
cnt -- number of characters to cut
Variables
-
const lv_obj_class_t lv_label_class¶
-
struct lv_label_t¶
Public Members
-
char *text¶
-
char *tmp_ptr¶
-
char tmp[LV_LABEL_DOT_NUM + 1]¶
-
union lv_label_t::[anonymous] dot¶
-
uint32_t dot_end¶
-
lv_draw_label_hint_t hint¶
-
uint32_t sel_start¶
-
uint32_t sel_end¶
-
lv_point_t offset¶
-
lv_label_long_mode_t long_mode¶
-
uint8_t static_txt¶
-
uint8_t recolor¶
-
uint8_t expand¶
-
uint8_t dot_tmp_alloc¶
-
char *text¶