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