Label (标签)(lv_label)

Overview(概述)

显示原文

A Label is the Widget 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. Only text_color and bg_color style properties can be used.


  • LV_PART_MAIN 使用所有典型的背景属性和文本属性。 填充值可用于在文本和背景之间添加空间。

  • LV_PART_SCROLLBAR 当文本大于组件的大小时显示的滚动条。

  • LV_PART_SELECTED 告诉 selected text 的样式。 只能使用 text_colorbg_color 样式属性。

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.

警告

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

小心

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.


您可以在运行时使用 lv_label_set_text(label, "New text"). 设置标签上的文本。 这将动态分配一个缓冲区,并且提供的字符串将被复制到该缓冲区中。 因此,在该函数返回后,您不需要将传递给 lv_label_set_text() 的文本保留在作用域中。

通过 lv_label_set_text_fmt(label, fmt, ...) ,可以使用 printf 格式化的方式来设置文本。示例:lv_label_set_text_fmt(label, "Value: %d", 15)

标签(Labels)也能够显示来自静态字符缓冲区的文本。要实现这一点,可使用 lv_label_set_text_static(label, "Text") 。在这种情况下,文本不会存储在动态内存中,而是直接使用给定的缓冲区。这意味着字符缓冲区的内容在标签的整个生命周期内必须保持有效,或者直到通过上述函数之一设置了另一个缓冲区为止。

const 字符串可以安全地与 lv_label_set_text_static() 一起使用,因为它们存储在只读存储器(ROM)中,始终是可访问的。

警告

当标签(Label)处于 LV_LABEL_LONG_DOT 模式下时,不要将 const 字符串与 lv_label_set_text_static() 一起使用,因为标签会尝试对字符串进行原地编辑。这样做会因试图修改程序内存(只读存储器,即 ROM)而导致微控制器(MCU)出现异常。

小心

如果你的标签(Label)需要快速更新新的字符串(例如,每秒更新次数大于 30 次,比如仪表盘上的每分钟转数(RPM)或者模数转换器(ADC)的值),并且这些字符串的长度频繁变化,那么建议采取以下做法:

  • 分配一个足够大的静态字符串缓冲区,使其能够容纳可能出现的最长字符串;

  • 仅当新字符串对最终用户来说会产生可见差异时,才用新字符串更新该缓冲区;

  • 使用那个缓冲区,通过 lv_label_set_text_static(label, buffer) 来更新标签。

原因:如果你使用 lv_label_set_text(label, new_text) ,那么每当字符串长度发生变化时,就会强制进行内存重分配(realloc() )操作。通过上述做法可以避免微控制器(MCU)出现此类开销。

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"


换行符由标签对象自动处理。 您可以使用 \n 来换行。 例如: "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 is LV_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.


默认情况下,标签的宽度和高度设置为 LV_SIZE_CONTENT。因此标签的大小会自动扩展到文本大小。 否则,如果显式设置宽度或高度(使用例如:cpp:func: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() 的缓冲区必须是可写的。

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


如果通过 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)

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 the text

  • the text has multiple lines with non equal line length


要对标签(Label)中的文本行进行水平对齐,可以将 text_align 样式属性与 lv_obj_set_style_text_align()lv_style_set_text_align() 函数配合使用,并传入 LV_TEXT_ALIGN_... 枚举值中的某一个。 请注意,只有在以下情况下,这样做才会产生可见的效果:

  • 标签小组件的宽度大于文本最长行的宽度

  • 文本有多行行长度不相等

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.


LVGL 可以通过保存一些额外的数据(~12 字节)来有效地处理很长(例如 > 40k 个字符)的标签以加快绘图速度。 要启用此功能,请在 lv_conf.h 中设置 LV_LABEL_LONG_TXT_HINT   1

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 animation property of a style, using lv_style_set_anim(). It will be treated as a template which will be used to create the scroll animations.


滚动动画的某些方面在长模式下 LV_LABEL_LONG_SCROLLLV_LABEL_LONG_SCROLL_CIRCULAR 可以是通过设置样式的 animation 属性进行自定义,使用 lv_style_set_anim()

它将被视为一个模板,将用于创建滚动动画。

Symbols(符号)

显示原文

The labels can display symbols alongside letters (or on their own). Read the Fonts(字体) section to learn more about the symbols.


标签可以在字母旁边显示符号(或单独显示)。 阅读 Fonts(字体) 部分以了解有关符号的更多信息。

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(事件).


标签(Label)部件不会发送特殊事件。默认情况下,创建标签部件时不会带有 LV_OBJ_FLAG_CLICKABLE 标志,不过如果需要的话,你可以添加该标志,使标签部件能够发出 LV_EVENT_CLICKED 事件。

另请参阅 Base-Widget Events 的事件。

详细了解更多 Events(事件)

Keys(按键)

显示原文

No Keys are processed by Label Widgets.

Learn more about Keys(按键).


标签(Label)部件不处理任何 *按键*(Keys) 操作。

了解有关 Keys(按键) 的更多信息。

Example

Line wrap, recoloring and scrolling

#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_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_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

#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

#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

#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

#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_screen_active());
    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

API

lv_observer.h

lv_label.h

lv_types.h

lv_obj_property_names.h