# lv_label.h (/api/widgets/label/lv_label_h) Functions [#functions] lv_label_set_text [#lv_label_set_text] Set a new text for a label. Memory will be allocated to store the text by the label. ```c title=" " lineNumbers=1 void lv_label_set_text(lv_obj_t *obj, const char *text) ``` Parameters | Name | Type | Description | | ------ | ------------------------------------------------ | ------------------------------------------------------------------------ | | `obj` | | pointer to a label object | | `text` | `const char *` | '\0' terminated character string. NULL to refresh with the current text. | If `LV_USE_ARABIC_PERSIAN_CHARS` is enabled the text will be modified to have the correct Arabic characters in it. lv_label_set_text_fmt [#lv_label_set_text_fmt] Set a new formatted text for a label. Memory will be allocated to store the text by the label. ```c title=" " lineNumbers=1 void lv_label_set_text_fmt(lv_obj_t *obj, const char *fmt,...) ``` Parameters | Name | Type | Description | | ----- | ------------------------------------------------ | ------------------------------------------------------------------------------------------- | | `obj` | | pointer to a label object | | `fmt` | `const char *` | `printf`-like format string Example: `lv_label_set_text_fmt(label1, "%d user", user_num);` | | `...` | | | If `LV_USE_ARABIC_PERSIAN_CHARS` is enabled the text will be modified to have the correct Arabic characters in it. lv_label_set_text_vfmt [#lv_label_set_text_vfmt] Set a new formatted text for a label. Memory will be allocated to store the text by the label. Example: ```c title=" " lineNumbers=1 va_list args; va_start(args, fmt); lv_label_set_text_vfmt(label1, fmt, args); va_end(args); ``` ```c title=" " lineNumbers=1 void lv_label_set_text_vfmt(lv_obj_t *obj, const char *fmt, va_list args) ``` Parameters | Name | Type | Description | | ------ | ------------------------------------------------ | --------------------------- | | `obj` | | pointer to a label object | | `fmt` | `const char *` | `printf`-like format string | | `args` | `va_list` | variadic arguments list | It ignores `LV_USE_ARABIC_PERSIAN_CHARS` lv_label_set_text_static [#lv_label_set_text_static] Set a static text. It will not be saved by the label so the 'text' variable has to be 'alive' while the label exists. ```c title=" " lineNumbers=1 void lv_label_set_text_static(lv_obj_t *obj, const char *text) ``` Parameters | Name | Type | Description | | ------ | ------------------------------------------------ | --------------------------------------------------------- | | `obj` | | pointer to a label object | | `text` | `const char *` | pointer to a text. NULL to refresh with the current text. | It ignores `LV_USE_ARABIC_PERSIAN_CHARS` lv_label_set_long_mode [#lv_label_set_long_mode] Set the behavior of the label with text longer than the object size ```c title=" " lineNumbers=1 void lv_label_set_long_mode(lv_obj_t *obj, lv_label_long_mode_t long_mode) ``` Parameters | Name | Type | Description | | ----------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 | lv_label_set_text_selection_start [#lv_label_set_text_selection_start] Set where text selection should start ```c title=" " lineNumbers=1 void lv_label_set_text_selection_start(lv_obj_t *obj, uint32_t index) ``` Parameters | Name | Type | Description | | ------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- | | `obj` | | pointer to a label object | | `index` | | character index from where selection should start. `LV_LABEL_TEXT_SELECTION_OFF` for no selection | lv_label_set_text_selection_end [#lv_label_set_text_selection_end] Set where text selection should end ```c title=" " lineNumbers=1 void lv_label_set_text_selection_end(lv_obj_t *obj, uint32_t index) ``` Parameters | Name | Type | Description | | ------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------ | | `obj` | | pointer to a label object | | `index` | | character index where selection should end. `LV_LABEL_TEXT_SELECTION_OFF` for no selection | lv_label_set_recolor [#lv_label_set_recolor] Enable the recoloring by in-line commands ```c title=" " lineNumbers=1 void lv_label_set_recolor(lv_obj_t *obj, bool en) ``` Parameters | Name | Type | Description | | ----- | ------------------------------------------------ | ------------------------------------------------------------------------------ | | `obj` | | pointer to a label object | | `en` | | true: enable recoloring, false: disable Example: "This is a #ff0000 red# word" | lv_label_set_translation_tag [#lv_label_set_translation_tag] Assign a translation tag for this label. Memory will be allocated to store the tag by the label. The label text will automatically update when the language is changed via `lv_translation_set_language`. ```c title=" " lineNumbers=1 void lv_label_set_translation_tag(lv_obj_t *obj, const char *tag) ``` Parameters | Name | Type | Description | | ----- | ------------------------------------------------ | --------------------------------- | | `obj` | | pointer to a label object | | `tag` | `const char *` | '\0' terminated character string. | lv_label_get_text [#lv_label_get_text] Get the text of a label ```c title=" " lineNumbers=1 char * lv_label_get_text(const lv_obj_t *obj) ``` Parameters | Name | Type | Description | | ----- | ------------------------------------------------------ | ------------------------- | | `obj` | | pointer to a label object | **Returns:** `char *` — the text of the label lv_label_get_long_mode [#lv_label_get_long_mode] Get the long mode of a label ```c title=" " lineNumbers=1 lv_label_long_mode_t lv_label_get_long_mode(const lv_obj_t *obj) ``` Parameters | Name | Type | Description | | ----- | ------------------------------------------------------ | ------------------------- | | `obj` | | pointer to a label object | **Returns:** — the current long mode lv_label_get_letter_pos [#lv_label_get_letter_pos] Get the relative x and y coordinates of a letter ```c title=" " lineNumbers=1 void lv_label_get_letter_pos(const lv_obj_t *obj, uint32_t char_id, lv_point_t *pos) ``` Parameters | Name | Type | Description | | --------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | | `obj` | | pointer to a label object | | `char_id` | | 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) | lv_label_get_letter_on [#lv_label_get_letter_on] Get the index of letter on a relative point of a label. ```c title=" " lineNumbers=1 uint32_t lv_label_get_letter_on(const lv_obj_t *obj, lv_point_t *pos_in, bool bidi) ``` Parameters | Name | Type | Description | | -------- | ------------------------------------------------------ | ------------------------------------------------ | | `obj` | | pointer to label object | | `pos_in` | | pointer to point with coordinates on a the label | | `bidi` | | whether to use bidi processed | **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) lv_label_get_text_selection_start [#lv_label_get_text_selection_start] Get the selection start index. ```c title=" " lineNumbers=1 uint32_t lv_label_get_text_selection_start(const lv_obj_t *obj) ``` Parameters | Name | Type | Description | | ----- | ------------------------------------------------------ | -------------------------- | | `obj` | | pointer to a label object. | **Returns:** — selection start index. `LV_LABEL_TEXT_SELECTION_OFF` if nothing is selected. lv_label_get_text_selection_end [#lv_label_get_text_selection_end] Get the selection end index. ```c title=" " lineNumbers=1 uint32_t lv_label_get_text_selection_end(const lv_obj_t *obj) ``` Parameters | Name | Type | Description | | ----- | ------------------------------------------------------ | -------------------------- | | `obj` | | pointer to a label object. | **Returns:** — selection end index. `LV_LABEL_TXT_SEL_OFF` if nothing is selected. lv_label_get_recolor [#lv_label_get_recolor] Get the recoloring attribute. ```c title=" " lineNumbers=1 bool lv_label_get_recolor(const lv_obj_t *obj) ``` Parameters | Name | Type | Description | | ----- | ------------------------------------------------------ | -------------------------- | | `obj` | | pointer to a label object. | **Returns:** — true: recoloring is enabled, false: recoloring is disabled lv_label_create [#lv_label_create] Create a label object ```c title=" " lineNumbers=1 lv_obj_t * lv_label_create(lv_obj_t *parent) ``` Parameters | Name | Type | Description | | -------- | ------------------------------------------------ | ------------------------------------------------------------- | | `parent` | | pointer to an object, it will be the parent of the new label. | **Returns:** — pointer to the created button lv_label_is_char_under_pos [#lv_label_is_char_under_pos] Check if a character is drawn under a point. ```c title=" " lineNumbers=1 bool lv_label_is_char_under_pos(const lv_obj_t *obj, lv_point_t *pos) ``` Parameters | Name | Type | Description | | ----- | ------------------------------------------------------ | ---------------------------------- | | `obj` | | pointer to a label object | | `pos` | | Point to check for character under | **Returns:** — whether a character is drawn under the point lv_label_bind_text [#lv_label_bind_text] Bind an integer, string, or pointer Subject to a Label. ```c title=" " lineNumbers=1 lv_observer_t * lv_label_bind_text(lv_obj_t *obj, lv_subject_t *subject, const char *fmt) ``` Parameters | Name | Type | Description | | --------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `obj` | | pointer to Label | | `subject` | | pointer to Subject | | `fmt` | `const char *` | optional printf-like format string with 1 format specifier (e.g. "%d °C") or NULL to bind to the value directly. | **Returns:** — pointer to newly-created Observer If `fmt == NULL` strings and pointers (`\0` terminated string) will be shown as text as they are, integers as d, floats as %0.1f lv_label_ins_text [#lv_label_ins_text] Insert a text to a label. The label text cannot be static. ```c title=" " lineNumbers=1 void lv_label_ins_text(lv_obj_t *obj, uint32_t pos, const char *txt) ``` Parameters | Name | Type | Description | | ----- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | `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` | `const char *` | pointer to the text to insert | lv_label_cut_text [#lv_label_cut_text] Delete characters from a label. The label text cannot be static. ```c title=" " lineNumbers=1 void lv_label_cut_text(lv_obj_t *obj, uint32_t pos, uint32_t cnt) ``` Parameters | Name | Type | Description | | ----- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `obj` | | pointer to a label object | | `pos` | | character index from where to cut. Expressed in character index and not byte index. 0: start in front of the first character | | `cnt` | | number of characters to cut | Enums [#enums] lv_label_long_mode_t [#lv_label_long_mode_t] Long mode behaviors. Used in 'lv\_label\_ext\_t' | Name | Description | | ------------------------------------ | --------------------------------------------------------------------------------------- | | `LV_LABEL_LONG_MODE_WRAP` | Keep the object width, wrap lines longer than object width and expand the object height | | `LV_LABEL_LONG_MODE_DOTS` | Keep the size and write dots at the end if the text is too long | | `LV_LABEL_LONG_MODE_SCROLL` | Keep the size and roll the text back and forth | | `LV_LABEL_LONG_MODE_SCROLL_CIRCULAR` | Keep the size and roll the text circularly | | `LV_LABEL_LONG_MODE_CLIP` | Keep the size and clip the text out of it | * `lv_label_set_long_mode` — param `long_mode` \_lv_property_label_id_t [#_lv_property_label_id_t] | Name | Value | | ---------------------------------------- | -------------------------------------------------------------- | | `LV_PROPERTY_LABEL_TEXT` | `(LV_PROPERTY_LABEL_START + ((int) 0 )) \| (( 7 ) << 28 )` | | `LV_PROPERTY_LABEL_LONG_MODE` | `(LV_PROPERTY_LABEL_START + ((int) 1 )) \| (( 1 ) << 28 )` | | `LV_PROPERTY_LABEL_TEXT_SELECTION_START` | `(LV_PROPERTY_LABEL_START + ((int) 2 )) \| (( 1 ) << 28 )` | | `LV_PROPERTY_LABEL_TEXT_SELECTION_END` | `(LV_PROPERTY_LABEL_START + ((int) 3 )) \| (( 1 ) << 28 )` | | `LV_PROPERTY_LABEL_END` | | Macros [#macros] LV_LABEL_DOT_NUM [#lv_label_dot_num] ```c title=" " lineNumbers=1 #define LV_LABEL_DOT_NUM 3 ``` LV_LABEL_POS_LAST [#lv_label_pos_last] ```c title=" " lineNumbers=1 #define LV_LABEL_POS_LAST 0xFFFF ``` LV_LABEL_TEXT_SELECTION_OFF [#lv_label_text_selection_off] ```c title=" " lineNumbers=1 #define LV_LABEL_TEXT_SELECTION_OFF LV_DRAW_LABEL_NO_TXT_SEL ``` LV_LABEL_DEFAULT_TEXT [#lv_label_default_text] ```c title=" " lineNumbers=1 #define LV_LABEL_DEFAULT_TEXT "Text" ``` Variables [#variables] lv_label_class [#lv_label_class] ```c title=" " lineNumbers=1 const lv_obj_class_t lv_label_class ``` Dependencies [#dependencies]