1.. _lv_label: 2 3================ 4Label (lv_label) 5================ 6 7 8Overview 9******** 10 11A Label is the Widget used to display text. 12 13 14.. _lv_label_parts_and_styles: 15 16Parts and Styles 17**************** 18 19- :cpp:enumerator:`LV_PART_MAIN` Uses the :ref:`typical background <typical bg props>` and 20 text properties. Padding values can be used to add space between 21 the text and the edges of the Label's background. 22- :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is 23 larger than the Widget's size. 24- :cpp:enumerator:`LV_PART_SELECTED` Tells the style of the 25 :ref:`selected text <lv_label_text_selection>`. Only ``text_color`` and ``bg_color`` style 26 properties can be used. 27 28 29.. _lv_label_usage: 30 31Usage 32***** 33 34Set text 35-------- 36 37You can set the text on a Label at runtime with 38:cpp:expr:`lv_label_set_text(label, "New text")`. This will allocate a buffer 39dynamically, and the provided string will be copied into that buffer. 40Therefore, you don't need to keep the text you pass to 41:cpp:func:`lv_label_set_text` in scope after that function returns. 42 43With :cpp:expr:`lv_label_set_text_fmt(label, fmt, ...)` printf formatting 44can be used to set the text. Example: :cpp:expr:`lv_label_set_text_fmt(label, "Value: %d", 15)`. 45 46Labels are able to show text from a static character buffer as well. To do so, use 47:cpp:expr:`lv_label_set_text_static(label, "Text")`. In this case, the text is not 48stored in dynamic memory and the given buffer is used directly instead. This means 49that the contents of the character buffer *must* remain valid for the life of the 50label or until another buffer is set via one of the above functions. 51 52``const`` strings are safe to use with :cpp:func:`lv_label_set_text_static` since 53they are stored in ROM memory, which is always accessible. 54 55.. warning:: 56 57 Do not use ``const`` strings with :cpp:func:`lv_label_set_text_static` when the 58 Label is being used in :cpp:enumerator:`LV_LABEL_LONG_DOT` mode since the Label 59 will attempt to do an in-place edit of the string. This will cause an MCU 60 exception by attempting to modify program memory (ROM). 61 62.. _label_rapidly_updating_text: 63 64.. caution:: 65 66 If your Label is updated with new strings rapidly (e.g. > 30X / second, such as 67 RPM in a dashboard, or an ADC value), and the length of those strings changes 68 frequently, it is advisable to: 69 70 - allocate a static string buffer large enough contain the largest possible string, 71 - update that buffer with the new strings only when they will make a visible 72 difference for the end user, and 73 - update the Label with :cpp:expr:`lv_label_set_text_static(label, buffer)` using that buffer. 74 75 Reason: if you use :cpp:expr:`lv_label_set_text(label, new_text)`, a memory 76 realloc() will be forced every time the length of the string changes. That 77 MCU overhead can be avoided by doing the above. 78 79.. _lv_label_newline: 80 81Newline 82------- 83 84Newline characters are handled automatically by the Label Widget. You 85can use ``\n`` to make a line break. For example: 86``"line1\nline2\n\nline4"`` 87 88.. _lv_label_long_modes: 89 90Long modes 91---------- 92 93By default, the width and height of the Label are set to 94:c:macro:`LV_SIZE_CONTENT`. Thus, the size of the Label is automatically expanded 95to the text size + padding + border width. Otherwise, if the width or height are 96explicitly set (using e.g.\ :cpp:func:`lv_obj_set_width` or a layout), the lines 97wider than the Label's width can be manipulated according to several 98long mode policies. Similarly, the policies can be applied if the height 99of the text is greater than the height of the Label. 100 101- :cpp:enumerator:`LV_LABEL_LONG_WRAP` Wrap lines that are too long. If the height is :c:macro:`LV_SIZE_CONTENT` the Label's 102 height will be expanded, otherwise the text will be clipped. (Default) 103- :cpp:enumerator:`LV_LABEL_LONG_DOT` Replaces the last 3 characters from bottom right corner of the Label with dots (``.``) 104- :cpp:enumerator:`LV_LABEL_LONG_SCROLL` If the text is wider than the label, scroll it horizontally back and forth. If it's 105 higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence. 106- :cpp:enumerator:`LV_LABEL_LONG_SCROLL_CIRCULAR` If the text is wider than the Label, scroll it horizontally continuously. If it's 107 higher, scroll vertically. Only one direction is scrolled and horizontal scrolling has higher precedence. 108- :cpp:enumerator:`LV_LABEL_LONG_CLIP` Simply clip the parts of the text outside the Label. 109 110You can specify the long mode with :cpp:expr:`lv_label_set_long_mode(label, LV_LABEL_LONG_...)` 111 112Note that :cpp:enumerator:`LV_LABEL_LONG_DOT` manipulates the text buffer in-place in 113order to add/remove the dots. When :cpp:func:`lv_label_set_text` or 114:cpp:func:`lv_label_set_array_text` are used, a separate buffer is allocated and 115this implementation detail is unnoticed. This is not the case with 116:cpp:func:`lv_label_set_text_static`. The buffer you pass to 117:cpp:func:`lv_label_set_text_static` must be writable if you plan to use 118:cpp:enumerator:`LV_LABEL_LONG_DOT`. 119 120.. _lv_label_text_recolor: 121 122Text recolor 123------------ 124 125In the text, you can use commands to recolor parts of the text. 126For example: ``Write a #ff0000 red# word``. This feature can be enabled 127individually for each label by :cpp:expr:`lv_label_set_recolor(label, en)` 128function. In the context of word-wrapped text, any Recoloring started on a 129line will be terminated at the end of the line where the line is wrapped if it 130was not already terminated by an ending ``#`` in the text. 131 132.. _lv_label_text_selection: 133 134Text selection 135-------------- 136 137If enabled by :c:macro:`LV_LABEL_TEXT_SELECTION` part of the text can be 138selected. It's similar to when you use your mouse on a PC to select 139text. The whole mechanism (click and select the text as you drag your 140finger/mouse) is implemented in :ref:`lv_textarea` and 141the Label Widget only allows programmatic text selection with 142:cpp:expr:`lv_label_get_text_selection_start(label, start_char_index)` and 143:cpp:expr:`lv_label_get_text_selection_end(label, end_char_index)`. 144 145.. _lv_label_text_alignment: 146 147Text alignment 148-------------- 149 150To horizontally align the lines of a Label the `text_align` style property can be used with 151:cpp:func:`lv_obj_set_style_text_align` or :cpp:func:`lv_style_set_text_align`, 152passing one of the ``LV_TEXT_ALIGN_...`` enumeration values. 153Note that this has a visible effect only if: 154 155- the Label Widget's width is larger than the width of the longest line of text, and 156- the text has multiple lines with different line lengths. 157 158.. _lv_label_very_long_texts: 159 160Very long text 161-------------- 162 163LVGL can efficiently handle very long (e.g. > 40k characters) Labels by 164saving some extra data (~12 bytes) to speed up drawing. To enable this 165feature, set ``LV_LABEL_LONG_TXT_HINT`` to ``1`` in ``lv_conf.h``. 166 167.. _lv_label_custom_scrolling_animations: 168 169Custom scrolling animations 170--------------------------- 171 172Some aspects of the scrolling animations in long modes 173:cpp:enumerator:`LV_LABEL_LONG_SCROLL` and :cpp:enumerator:`LV_LABEL_LONG_SCROLL_CIRCULAR` can be 174customized by setting the Label's animation style property, using 175:cpp:func:`lv_style_set_anim`. 176It will be treated as a template which will be used to create the scroll animations. 177 178.. _lv_label_symbols: 179 180Symbols 181------- 182 183The Labels can display symbols alongside letters (or on their own). Read 184the :ref:`font` section to learn more about symbols. 185 186 187 188.. _lv_label_events: 189 190Events 191****** 192 193No special events are sent by Label Widgets. By default, Label Widgets are created 194without the LV_OBJ_FLAG_CLICKABLE flag, but you can add it to make a Label Widget 195emit LV_EVENT_CLICKED events if desired. 196 197.. admonition:: Further Reading 198 199 Learn more about :ref:`lv_obj_events` emitted by all Widgets. 200 201 Learn more about :ref:`events`. 202 203 204 205.. _lv_label_keys: 206 207Keys 208**** 209 210No *Keys* are processed by Label Widgets. 211 212.. admonition:: Further Reading 213 214 Learn more about :ref:`indev_keys`. 215 216 217 218.. _lv_label_example: 219 220Example 221******* 222 223.. include:: ../../examples/widgets/label/index.rst 224 225 226 227.. _lv_label_api: 228 229API 230*** 231