Overview

The Labels are the basic objects to display text. There is no limitation in the text size because it's stored dynamically. You can modify the text in run time at any time with lv_label_set_text().

You can use \n to make line break. For example: "line1\nline2\n\nline4"

The size of the label object can be automatically expanded to the text size or the text can be manipulated according to several long mode policies:

  • LV_LABEL_LONG_EXPAND: Expand the object size to the text size
  • LV_LABEL_LONG_BREAK: Keep the object width, break (wrap) the too long lines and expand the object height
  • LV_LABEL_LONG_DOTS: Keep the object size, break the text and write dots in the last line
  • LV_LABEL_LONG_SCROLL: Expand the object size and scroll the text on the parent (move the label object)
  • LV_LABEL_LONG_ROLL: Keep the size and roll just the text (not the object)

You can specify the long mode with: lv_label_set_long_mode(label, long_mode)

Labels are able to show text from a static array. Use: lv_label_set_static_text(label, char_array). In this case the text is not stored in the dynamic memory but the given array is used instead. Keep in my the array can't be a local variable which destroys when the function exits.

You can also use a raw character array as label text. The array don't has to be \0 terminated. In this case the text will be saved to the dynamic memory. To set a raw character array use the lv_label_set_array_text(label, char_array) function.

The label's text can be aligned to the left or middle with: lv_label_set_align(label, LV_LABEL_ALIGN_LEFT/CENTER)

You can enable to draw a background for the label with lv_label_set_body_draw(label, draw)

In the text you can use commands to re-color 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.

The labels can display symbols besides letters. Learn more about symbols here.

Instead of full screen anti-aliasing Font anti-aliasing can be enabled in lv_conf.h by LV_FONT_ANTIALIAS. It needs much less CPU resources compared to full screen anti-aliasing. Keep in mind it will reduce the size of the letters to half so you need to use double sized fonts.

The labels' default style is NULL so they inherit the parent's style.

Style usage

  • Use all properties from style.text
  • For background drawing style.body properties are used

Notes

  • The label's click enable attribute is disabled by default. You can enable clicking with lv_obj_set_click(label, true)
Example of Label in Littlev Graphics Library

						/*Create label on the screen. By default it will inherit the style of the screen*/
lv_obj_t * title = lv_label_create(lv_scr_act(), NULL);
lv_label_set_text(title, "Title Label");
lv_obj_align(title, NULL, LV_ALIGN_IN_TOP_MID, 0, 20);  /*Align to the top*/

/*Create anew style*/
static lv_style_t style_txt;
lv_style_copy(&style_txt, &lv_style_plain);
style_txt.text.font = &lv_font_dejavu_40;
style_txt.text.letter_space = 2;
style_txt.text.line_space = 1;
style_txt.text.color = LV_COLOR_HEX(0x606060);

/*Create a new label*/
lv_obj_t * txt = lv_label_create(lv_scr_act(), NULL);
lv_obj_set_style(txt, &style_txt);                    /*Set the created style*/
lv_label_set_long_mode(txt, LV_LABEL_LONG_BREAK);     /*Break the long lines*/
lv_label_set_recolor(txt, true);                      /*Enable re-coloring by commands in the text*/
lv_label_set_align(txt, LV_LABEL_ALIGN_CENTER);       /*Center aligned lines*/
lv_label_set_text(txt, "Align lines to the middle\n\n"
                       "#000080 Re-color# #0000ff words of# #6666ff the text#\n\n"
                       "If a line become too long it can be automatically broken into multiple lines");
lv_obj_set_width(txt, 300);                           /*Set a width*/
lv_obj_align(txt, NULL, LV_ALIGN_CENTER, 0, 20);      /*Align to center*/

lv_obj_t *

lv_label_create

(lv_obj_t * par, lv_obj_t * copy);

Create a label objects

par pointer to an object, it will be the parent of the new label

copy pointer to a button object, if not NULL then the new object will be copied from it

return pointer to the created button

void

lv_label_set_text

(lv_obj_t * label, const char * text);

Set a new text for a label. Memory will be allocated to store the text by the label.

label pointer to a label object

text '\0' terminated character string. NULL to refresh with the current text.

void

lv_label_set_array_text

(lv_obj_t * label, const char * array, uint16_t size);

Set a new text for a label from a character array. The array don't has to be '\0' terminated.
Memory will be allocated to store the array by the label.

label pointer to a label object

array array of characters or NULL to refresh the label

size the size of 'array' in bytes

void

lv_label_set_static_text

(lv_obj_t * label, 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 exist.

label 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 * label, lv_label_long_mode_t long_mode);

Set the behavior of the label with longer text then the object size

label pointer to a label object

long_mode the new mode from 'lv_label_long_mode' enum.

void

lv_label_set_align

(lv_obj_t *label, lv_label_align_t align);

Set the align of the label (left or center)

label pointer to a label object

align 'LV_LABEL_ALIGN_LEFT' or 'LV_LABEL_ALIGN_LEFT'

void

lv_label_set_recolor

(lv_obj_t * label, bool recolor_en);

Enable the recoloring by in-line commands

label pointer to a label object

recolor_en true: enable recoloring, false: disable

void

lv_label_set_no_break

(lv_obj_t * label, bool no_break_en);

Set the label to ignore (or accept) line breaks on '\n'

label pointer to a label object

no_break_en true: ignore line breaks, false: make line breaks on '\n'

void

lv_label_set_body_draw

(lv_obj_t *label, bool body_en);

Set the label to draw (or not draw) background specified in its style's body

label pointer to a label object

body_en true: draw body; false: don't draw body

void

lv_label_set_anim_speed

(lv_obj_t *label, uint16_t anim_speed);

Set the label's animation speed in LV_LABEL_LONG_ROLL and SCROLL modes

label pointer to a label object

anim_speed speed of animation in px/sec unit

void

lv_label_set_style

(lv_obj_t *label, lv_style_t *style);

Set the style of an label

label pointer to an label object

style pointer to a style

char *

lv_label_get_text

(lv_obj_t * label);

Get the text of a label

label pointer to a label object

return the text of the label

lv_label_long_mode_t

lv_label_get_long_mode

(lv_obj_t * label);

Get the long mode of a label

label pointer to a label object

return the long mode

lv_label_align_t

lv_label_get_align

(lv_obj_t * label);

Get the align attribute

label pointer to a label object

return LV_LABEL_ALIGN_LEFT or LV_LABEL_ALIGN_CENTER

bool

lv_label_get_recolor

(lv_obj_t * label);

Get the recoloring attribute

label pointer to a label object

return true: recoloring is enabled, false: disable

bool

lv_label_get_no_break

(lv_obj_t * label);

Get the no break attribute

label pointer to a label object

return true: no_break_enabled (ignore '\n' line breaks); false: make line breaks on '\n'

bool

lv_label_get_body_draw

(lv_obj_t *label);

Get the body draw attribute

label pointer to a label object

return true: draw body; false: don't draw body

uint16_t

lv_label_get_anim_speed

(lv_obj_t *label);

Get the label's animation speed in LV_LABEL_LONG_ROLL and SCROLL modes

label pointer to a label object

return speed of animation in px/sec unit

void

lv_label_get_letter_pos

(lv_obj_t * label, uint16_t index, lv_point_t * pos);

Get the relative x and y coordinates of a letter

label pointer to a label object

index index of the letter [0 ... text length]. Expressed in character index, not byte index (different in UTF-8)

pos store the result here (E.g. index = 0 gives 0;0 coordinates)

uint16_t

lv_label_get_letter_on

(lv_obj_t * label, lv_point_t * pos);

Get the index of letter on a relative point of a label

label pointer to label object

pos pointer to point with coordinates on a the label

return the index of the letter on the 'pos_p' point (E.g. on 0;0 is the 0. letter)
Expressed in character index and not byte index (different in UTF-8)

lv_style_t*

lv_label_get_style

(lv_obj_t *label);

Get the style of an label object

label pointer to an label object

return pointer to the label's style

void

lv_label_ins_text

(lv_obj_t * label, uint32_t pos, const char * txt);

Insert a text to the label. The label text can not be static.

label pointer to a label object

pos character index to insert. Expressed in character index and not byte index (Different in UTF-8)
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 * label, uint32_t pos, uint32_t cnt);

Delete characters from a label. The label text can not be static.

label pointer to a label object

pos character index to insert. Expressed in character index and not byte index (Different in UTF-8)
0: before first char.

cnt number of characters to cut

LittlevGL - Open-source Embedded GUI Library

LittlevGL is a free and open-source graphics library providing everything you need to create embedded GUI with easy-to-use graphical elements, beautiful visual effects and low memory footprint.

If you like LittlevGL, please
support its deveopment!


The founder of Littlev Graphics Library (LittlevGL) and related software modules is:
Gábor Kiss-Vámosi
All Rights Reserved ©  2018 Hungary