.. _lv_label: ================ Label (lv_label) ================ Overview ******** A Label is the Widget used to display text. .. _lv_label_parts_and_styles: Parts and Styles **************** - :cpp:enumerator:`LV_PART_MAIN` Uses the :ref:`typical background ` and text properties. Padding values can be used to add space between the text and the edges of the Label's background. - :cpp:enumerator:`LV_PART_SCROLLBAR` The scrollbar that is shown when the text is larger than the Widget's size. - :cpp:enumerator:`LV_PART_SELECTED` Tells the style of the :ref:`selected text `. Only ``text_color`` and ``bg_color`` style properties can be used. .. _lv_label_usage: Usage ***** Set text -------- You can set the text on a Label at runtime with :cpp:expr:`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 :cpp:func:`lv_label_set_text` in scope after that function returns. With :cpp:expr:`lv_label_set_text_fmt(label, fmt, ...)` printf formatting can be used to set the text. Example: :cpp:expr:`lv_label_set_text_fmt(label, "Value: %d", 15)`. Labels are able to show text from a static character buffer as well. To do so, use :cpp:expr:`lv_label_set_text_static(label, "Text")`. In this case, the text is not stored in dynamic memory and the given buffer is used directly instead. This means that the contents of the character buffer *must* remain valid for the life of the label or until another buffer is set via one of the above functions. ``const`` strings are safe to use with :cpp:func:`lv_label_set_text_static` since they are stored in ROM memory, which is always accessible. .. warning:: Do not use ``const`` strings with :cpp:func:`lv_label_set_text_static` when the Label is being used in :cpp:enumerator:`LV_LABEL_LONG_DOT` mode since the Label will attempt to do an in-place edit of the string. This will cause an MCU exception by attempting to modify program memory (ROM). .. _label_rapidly_updating_text: .. caution:: If your Label is updated with new strings rapidly (e.g. > 30X / second, such as RPM in a dashboard, or an ADC value), and the length of those strings changes frequently, it is advisable to: - allocate a static string buffer large enough contain the largest possible string, - update that buffer with the new strings only when they will make a visible difference for the end user, and - update the Label with :cpp:expr:`lv_label_set_text_static(label, buffer)` using that buffer. Reason: if you use :cpp:expr:`lv_label_set_text(label, new_text)`, a memory realloc() will be forced every time the length of the string changes. That MCU overhead can be avoided by doing the above. .. _lv_label_newline: Newline ------- Newline characters are handled automatically by the Label Widget. You can use ``\n`` to make a line break. For example: ``"line1\nline2\n\nline4"`` .. _lv_label_long_modes: Long modes ---------- By default, the width and height of the Label are set to :c:macro:`LV_SIZE_CONTENT`. Thus, the size of the Label is automatically expanded to the text size + padding + border width. Otherwise, if the width or height are explicitly set (using e.g.\ :cpp:func:`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. - :cpp:enumerator:`LV_LABEL_LONG_WRAP` Wrap lines that are too long. If the height is :c:macro:`LV_SIZE_CONTENT` the Label's height will be expanded, otherwise the text will be clipped. (Default) - :cpp:enumerator:`LV_LABEL_LONG_DOT` Replaces the last 3 characters from bottom right corner of the Label with dots (``.``) - :cpp:enumerator:`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. - :cpp:enumerator:`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. - :cpp:enumerator:`LV_LABEL_LONG_CLIP` Simply clip the parts of the text outside the Label. You can specify the long mode with :cpp:expr:`lv_label_set_long_mode(label, LV_LABEL_LONG_...)` Note that :cpp:enumerator:`LV_LABEL_LONG_DOT` manipulates the text buffer in-place in order to add/remove the dots. When :cpp:func:`lv_label_set_text` or :cpp:func:`lv_label_set_array_text` are used, a separate buffer is allocated and this implementation detail is unnoticed. This is not the case with :cpp:func:`lv_label_set_text_static`. The buffer you pass to :cpp:func:`lv_label_set_text_static` must be writable if you plan to use :cpp:enumerator:`LV_LABEL_LONG_DOT`. .. _lv_label_text_recolor: Text recolor ------------ In the text, you can use commands to recolor parts of the text. For example: ``Write a #ff0000 red# word``. This feature can be enabled individually for each label by :cpp:expr:`lv_label_set_recolor(label, en)` function. In the context of word-wrapped text, any Recoloring started on a line will be terminated at the end of the line where the line is wrapped if it was not already terminated by an ending ``#`` in the text. .. _lv_label_text_selection: Text selection -------------- If enabled by :c:macro:`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 text. The whole mechanism (click and select the text as you drag your finger/mouse) is implemented in :ref:`lv_textarea` and the Label Widget only allows programmatic text selection with :cpp:expr:`lv_label_get_text_selection_start(label, start_char_index)` and :cpp:expr:`lv_label_get_text_selection_end(label, end_char_index)`. .. _lv_label_text_alignment: Text alignment -------------- To horizontally align the lines of a Label the `text_align` style property can be used with :cpp:func:`lv_obj_set_style_text_align` or :cpp:func:`lv_style_set_text_align`, passing one of the ``LV_TEXT_ALIGN_...`` enumeration values. Note that this has a visible effect only if: - the Label Widget's width is larger than the width of the longest line of text, and - the text has multiple lines with different line lengths. .. _lv_label_very_long_texts: Very long text -------------- 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`` to ``1`` in ``lv_conf.h``. .. _lv_label_custom_scrolling_animations: Custom scrolling animations --------------------------- Some aspects of the scrolling animations in long modes :cpp:enumerator:`LV_LABEL_LONG_SCROLL` and :cpp:enumerator:`LV_LABEL_LONG_SCROLL_CIRCULAR` can be customized by setting the Label's animation style property, using :cpp:func:`lv_style_set_anim`. It will be treated as a template which will be used to create the scroll animations. .. _lv_label_symbols: Symbols ------- The Labels can display symbols alongside letters (or on their own). Read the :ref:`font` section to learn more about symbols. .. _lv_label_events: Events ****** No special events are sent by Label Widgets. By default, Label Widgets are created without the LV_OBJ_FLAG_CLICKABLE flag, but you can add it to make a Label Widget emit LV_EVENT_CLICKED events if desired. .. admonition:: Further Reading Learn more about :ref:`lv_obj_events` emitted by all Widgets. Learn more about :ref:`events`. .. _lv_label_keys: Keys **** No *Keys* are processed by Label Widgets. .. admonition:: Further Reading Learn more about :ref:`indev_keys`. .. _lv_label_example: Example ******* .. include:: ../../examples/widgets/label/index.rst .. _lv_label_api: API ***