mirror of
https://github.com/lvgl/lvgl.git
synced 2025-02-04 07:13:00 +08:00
191 lines
4.8 KiB
ReStructuredText
191 lines
4.8 KiB
ReStructuredText
.. _lv_spangroup:
|
|
|
|
========================
|
|
Spangroup (lv_spangroup)
|
|
========================
|
|
|
|
|
|
Overview
|
|
********
|
|
|
|
The Spangroup Widget is used to display rich text. Different
|
|
from the Label Widget, Spangroups can render text styled with
|
|
different fonts, colors, and sizes into the Spangroup Widget.
|
|
See example below.
|
|
|
|
A Spangroup contains 0 or more Span Descriptors ("Spans"). Each Span contains its
|
|
own text and style properties for that text. You add 1 Span (as a child) to the
|
|
Spangroup for each "span" of uniquely-styled text needed. Each Span so added is
|
|
appended to the end of the list. The list sequence determines the order in which the
|
|
Spans are displayed. Spans can be added to, and removed from, the Spangroup
|
|
throughout its life. The number of Spans that can be added is limited only by
|
|
available RAM.
|
|
|
|
|
|
|
|
.. _lv_spangroup_parts_and_styles:
|
|
|
|
Parts and Styles
|
|
****************
|
|
|
|
- :cpp:enumerator:`LV_PART_MAIN` Spangroup has only one part.
|
|
|
|
|
|
|
|
.. _lv_spangroup_usage:
|
|
|
|
Usage
|
|
*****
|
|
|
|
Set text and style
|
|
------------------
|
|
|
|
Add each needed Span to a Spangroup like this:
|
|
|
|
.. code-block:: c
|
|
|
|
lv_span_t * span = lv_spangroup_new_span(spangroup);
|
|
|
|
After a Span is created, use the following functions to set its text
|
|
and style properties:
|
|
|
|
- :cpp:expr:`lv_span_set_text(span, "text")`
|
|
- :cpp:expr:`lv_style_set_<property_name>(&span->style, value)`
|
|
|
|
Example of the latter: :cpp:expr:`lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED))`.
|
|
|
|
If the Spangroup Widget's ``mode != LV_SPAN_MODE_FIXED`` call
|
|
:cpp:expr:`lv_spangroup_refr_mode(spangroup)` after you have modifying any of its
|
|
Spans to ensure it is redrawn appropriately.
|
|
|
|
|
|
Retrieving a Span child
|
|
-----------------------
|
|
|
|
Spangroups store their children differently from normal Widgets, so
|
|
normal functions for getting children won't work.
|
|
|
|
:cpp:expr:`lv_spangroup_get_child(spangroup, id)` will return a pointer to the
|
|
child Span at index ``id``. In addition, ``id`` can be negative to index
|
|
from the end of the Spangroup where ``-1`` is the youngest child, ``-2``
|
|
is second youngest, etc.
|
|
|
|
E.g. ``lv_span_t * span = lv_spangroup_get_child(spangroup, 0)`` will
|
|
return the first child of the Spangroup.
|
|
``lv_span_t * span = lv_spangroup_get_child(spangroup, -1)`` will return
|
|
the last (or most recent) child.
|
|
|
|
|
|
Child count
|
|
-----------
|
|
|
|
Use :cpp:expr:`lv_spangroup_get_span_count(spangroup)` to get
|
|
the number of contained Spans.
|
|
|
|
E.g. ``uint32_t size = lv_spangroup_get_span_count(spangroup)``
|
|
|
|
|
|
Removing a Span
|
|
---------------
|
|
You can remove a Span at any time during the Spangroup's life using the function
|
|
:cpp:expr:`lv_spangroup_delete_span(spangroup, span)`.
|
|
|
|
|
|
Text align
|
|
----------
|
|
|
|
Like the Label Widget, a Spangroup can be set to one the following text-alignment modes:
|
|
|
|
- :cpp:enumerator:`LV_TEXT_ALIGN_LEFT` Align text to left.
|
|
- :cpp:enumerator:`LV_TEXT_ALIGN_CENTER` Center text.
|
|
- :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` Align text to right edge.
|
|
- :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` Align auto.
|
|
|
|
Use function :cpp:expr:`lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_...)`
|
|
to set text alignment.
|
|
|
|
|
|
Modes
|
|
-----
|
|
|
|
A Spangroup can be set to one the following modes:
|
|
|
|
- :cpp:enumerator:`LV_SPAN_MODE_FIXED` Fixes its size.
|
|
- :cpp:enumerator:`LV_SPAN_MODE_EXPAND` Expand size to text size but stay on one line.
|
|
- :cpp:enumerator:`LV_SPAN_MODE_BREAK` Keep width; break lines that are too long and auto-expand height.
|
|
|
|
Use :cpp:expr:`lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set its mode.
|
|
|
|
|
|
Overflow
|
|
--------
|
|
|
|
A Spangroup can be set to handle text overflow in one of the following ways:
|
|
|
|
- :cpp:enumerator:`LV_SPAN_OVERFLOW_CLIP` truncates text at the limit of the area.
|
|
- :cpp:enumerator:`LV_SPAN_OVERFLOW_ELLIPSIS` display an ellipsis (``...``) when text overflows the area.
|
|
|
|
Use :cpp:expr:`lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set
|
|
the Spangroup's overflow mode.
|
|
|
|
|
|
First line indent
|
|
-----------------
|
|
|
|
Use :cpp:expr:`lv_spangroup_set_indent(spangroup, 20)` to set the indent of the
|
|
first line. All modes support pixel units. In addition, :cpp:enumerator:`LV_SPAN_MODE_FIXED`
|
|
and :cpp:enumerator:`LV_SPAN_MODE_BREAK` modes support :ref:`percentage units <coord_units>`.
|
|
as well.
|
|
|
|
|
|
Lines
|
|
-----
|
|
|
|
Use :cpp:expr:`lv_spangroup_set_max_lines(spangroup, 10)` to set the maximum number
|
|
of lines to be displayed in :cpp:enumerator:`LV_SPAN_MODE_BREAK` mode. A negative
|
|
value indicates no limit.
|
|
|
|
|
|
|
|
.. _lv_spangroup_events:
|
|
|
|
Events
|
|
******
|
|
|
|
No special events are sent by Span Widgets.
|
|
|
|
.. admonition:: Further Reading
|
|
|
|
Learn more about :ref:`lv_obj_events` emitted by all Widgets.
|
|
|
|
Learn more about :ref:`events`.
|
|
|
|
|
|
|
|
.. _lv_spangroup_keys:
|
|
|
|
Keys
|
|
****
|
|
|
|
No *Keys* are processed by Span Widgets.
|
|
|
|
.. admonition:: Further Reading
|
|
|
|
Learn more about :ref:`indev_keys`.
|
|
|
|
|
|
|
|
.. _lv_spangroup_example:
|
|
|
|
Example
|
|
*******
|
|
|
|
.. include:: ../../examples/widgets/span/index.rst
|
|
|
|
|
|
|
|
.. _lv_spangroup_api:
|
|
|
|
API
|
|
***
|