mirror of
https://github.com/lvgl/lvgl.git
synced 2025-01-28 07:03:00 +08:00
219 lines
7.5 KiB
ReStructuredText
219 lines
7.5 KiB
ReStructuredText
.. _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 all the 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 <lv_label_text_selection>`. 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_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:`Text area <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
|
|
***
|