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. 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, "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 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.

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

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() Note that it 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

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.

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

Symbols

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

Events

No special events are sent by the Label.

See the events of the Base object too.

Learn more about Events.

Keys

No Keys are processed by the object type.

Learn more about 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"
//TODO
#if LV_USE_LABEL && LV_USE_CANVAS && LV_BUILD_EXAMPLES && LV_DRAW_SW_COMPLEX && 0

#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_color_t mask_map[MASK_WIDTH * MASK_HEIGHT];

    /*Create a "8 bit alpha" canvas and clear it*/
    lv_obj_t * canvas = lv_canvas_create(lv_screen_active());
    lv_canvas_set_buffer(canvas, mask_map, MASK_WIDTH, MASK_HEIGHT, LV_COLOR_FORMAT_NATIVE);
    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;
    label_dsc.text = "Text with gradient";
    lv_canvas_draw_text(canvas, 5, 5, MASK_WIDTH, &label_dsc);

    /*The mask is reads the canvas is not required anymore*/
    lv_obj_delete(canvas);

    /*Convert the mask to A8*/
    uint32_t i;
    uint8_t * mask8 = (uint8_t *) mask_map;
    lv_color_t * mask_c = mask_map;
    for(i = 0; i < MASK_WIDTH * MASK_HEIGHT; i++) {
        mask8[i] = lv_color_brightness(mask_c[i]);
    }

    /* 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_add_event_cb(grad, add_mask_event_cb, LV_EVENT_ALL, mask_map);
}

#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