标签 (lv_label)¶
概述¶
标签是用于显示文本的基本对象类型。
部件和样式¶
LV_PART_MAIN使用所有典型的背景属性和文本属性。可以使用填充值在文本和背景之间添加空间。LV_PART_SCROLLBAR当文本大于小部件的大小时显示的滚动条。LV_PART_SELECTED表示选中文本的样式。仅支持text_color和bg_color样式属性。
用法¶
设置文本¶
可以在运行时使用 lv_label_set_text(label, "新文本") 设置标签的文本。
这将动态分配一个缓冲区，并将提供的字符串复制到该缓冲区中。
因此，在函数返回后，无需保持传递给 lv_label_set_text 的文本在作用域内。
使用 lv_label_set_text_fmt(label, "值: %d", 15) 可以通过 printf 格式设置文本。
标签可以显示来自静态字符缓冲区的文本。为此，请使用 lv_label_set_text_static(label, "文本")。
在这种情况下，文本不会存储在动态内存中，而是直接使用给定的缓冲区。
这意味着数组不能是函数退出时超出作用域的局部变量。
常量字符串可以安全地与 lv_label_set_text_static 一起使用（除非与 LV_LABEL_LONG_DOT 一起使用，因为它会就地修改缓冲区），因为它们存储在始终可访问的 ROM 内存中。
换行符¶
标签对象会自动处理换行符。可以使用 \n 进行换行。例如："行1\n行2\n\n行4"
长模式¶
默认情况下，标签的宽度和高度设置为 LV_SIZE_CONTENT。因此，标签的大小会根据文本大小自动扩展。
否则，如果显式设置宽度或高度（例如使用 lv_obj_set_width 或布局），宽度超过标签宽度的行可以根据几种长模式策略进行操作。
类似地，如果文本的高度大于标签的高度，也可以应用这些策略。
LV_LABEL_LONG_WRAP换行过长的行。如果高度为LV_SIZE_CONTENT，标签的高度将扩展，否则文本将被裁剪。（默认）LV_LABEL_LONG_DOT用点（.）替换标签右下角的最后3个字符。LV_LABEL_LONG_SCROLL如果文本宽于标签，则水平来回滚动。如果文本高于标签，则垂直滚动。仅滚动一个方向，水平滚动优先。LV_LABEL_LONG_SCROLL_CIRCULAR如果文本宽于标签，则水平连续滚动。如果文本高于标签，则垂直滚动。仅滚动一个方向，水平滚动优先。LV_LABEL_LONG_CLIP简单地裁剪标签外的文本部分。
可以使用 lv_label_set_long_mode(label, LV_LABEL_LONG_...) 指定长模式。
注意，LV_LABEL_LONG_DOT 会就地操作文本缓冲区以添加/移除点。
当使用 lv_label_set_text 或 lv_label_set_array_text 时，会分配一个单独的缓冲区，因此这种实现细节不会被注意到。
但对于 lv_label_set_text_static，如果计划使用 LV_LABEL_LONG_DOT，传递给 lv_label_set_text_static 的缓冲区必须是可写的。
文本重着色¶
在文本中，可以使用命令对部分文本重新着色。例如："写一个 #ff0000 红色# 单词"。
可以通过 lv_label_set_recolor() 函数为每个标签单独启用此功能。
文本选择¶
如果通过 LV_LABEL_TEXT_SELECTION 启用，可以选择部分文本。这类似于在 PC 上使用鼠标选择文本。
整个机制（点击并拖动手指/鼠标选择文本）在文本区域中实现，而标签小部件仅允许通过 lv_label_get_text_selection_start(label, start_char_index) 和 lv_label_get_text_selection_start(label, end_char_index) 手动选择文本。
非常长的文本¶
LVGL 可以通过保存一些额外数据（约12字节）来高效处理非常长的（例如 > 40k 字符）标签，以加速绘制。要启用此功能，请在 lv_conf.h 中设置 LV_LABEL_LONG_TXT_HINT 1。
示例¶
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 D:\lv_port_pc_eclipse-release-v8.3\lvgl\examples\widgets\label\lv_example_label_4.py
Customize circular scrolling animation¶
C code
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_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_scr_act());
lv_label_set_long_mode(label1, LV_LABEL_LONG_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
#
# Show customizing the circular scrolling animation of a label with `LV_LABEL_LONG_SCROLL_CIRCULAR` long mode.
#
label1 = lv.label(lv.scr_act())
label1.set_long_mode(lv.label.LONG.SCROLL_CIRCULAR) # Circular scroll
label1.set_width(150)
label1.set_text("It is a circularly scrolling text. ")
label1.align(lv.ALIGN.CENTER, 0, 40)
API¶
Typedefs
-
typedef uint8_t
lv_label_long_mode_t¶
Enums
-
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
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_OFFfor 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_OFFfor 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_OFFif 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_OFFif 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
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 *