1.. _lv_spangroup:
2
3========================
4Spangroup (lv_spangroup)
5========================
6
7
8Overview
9********
10
11The Spangroup Widget is used to display rich text.  Different
12from the Label Widget, Spangroups can render text styled with
13different fonts, colors, and sizes into the Spangroup Widget.
14See example below.
15
16A Spangroup contains 0 or more Span Descriptors ("Spans").  Each Span contains its
17own text and style properties for that text.  You add 1 Span (as a child) to the
18Spangroup for each "span" of uniquely-styled text needed.  Each Span so added is
19appended to the end of the list.  The list sequence determines the order in which the
20Spans are displayed.  Spans can be added to, and removed from, the Spangroup
21throughout its life.  The number of Spans that can be added is limited only by
22available RAM.
23
24
25
26.. _lv_spangroup_parts_and_styles:
27
28Parts and Styles
29****************
30
31-  :cpp:enumerator:`LV_PART_MAIN` Spangroup has only one part.
32
33
34
35.. _lv_spangroup_usage:
36
37Usage
38*****
39
40Set text and style
41------------------
42
43Add each needed Span to a Spangroup like this:
44
45.. code-block:: c
46
47    lv_span_t * span = lv_spangroup_new_span(spangroup);
48
49After a Span is created, use the following functions to set its text
50and style properties:
51
52- :cpp:expr:`lv_span_set_text(span, "text")`
53- :cpp:expr:`lv_style_set_<property_name>(&span->style, value)`
54
55Example of the latter:  :cpp:expr:`lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED))`.
56
57If the Spangroup Widget's ``mode != LV_SPAN_MODE_FIXED`` call
58:cpp:expr:`lv_spangroup_refr_mode(spangroup)` after you have modifying any of its
59Spans to ensure it is redrawn appropriately.
60
61
62Retrieving a Span child
63-----------------------
64
65Spangroups store their children differently from normal Widgets, so
66normal functions for getting children won't work.
67
68:cpp:expr:`lv_spangroup_get_child(spangroup, id)` will return a pointer to the
69child Span at index ``id``. In addition, ``id`` can be negative to index
70from the end of the Spangroup where ``-1`` is the youngest child, ``-2``
71is second youngest, etc.
72
73E.g. ``lv_span_t * span = lv_spangroup_get_child(spangroup, 0)`` will
74return the first child of the Spangroup.
75``lv_span_t * span = lv_spangroup_get_child(spangroup, -1)`` will return
76the last (or most recent) child.
77
78
79Child count
80-----------
81
82Use :cpp:expr:`lv_spangroup_get_span_count(spangroup)` to get
83the number of contained Spans.
84
85E.g. ``uint32_t size = lv_spangroup_get_span_count(spangroup)``
86
87
88Removing a Span
89---------------
90You can remove a Span at any time during the Spangroup's life using the function
91:cpp:expr:`lv_spangroup_delete_span(spangroup, span)`.
92
93
94Text align
95----------
96
97Like the Label Widget, a Spangroup can be set to one the following text-alignment modes:
98
99- :cpp:enumerator:`LV_TEXT_ALIGN_LEFT` Align text to left.
100- :cpp:enumerator:`LV_TEXT_ALIGN_CENTER` Center text.
101- :cpp:enumerator:`LV_TEXT_ALIGN_RIGHT` Align text to right edge.
102- :cpp:enumerator:`LV_TEXT_ALIGN_AUTO` Align auto.
103
104Use function :cpp:expr:`lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_...)`
105to set text alignment.
106
107
108Modes
109-----
110
111A Spangroup can be set to one the following modes:
112
113- :cpp:enumerator:`LV_SPAN_MODE_FIXED` Fixes its size.
114- :cpp:enumerator:`LV_SPAN_MODE_EXPAND` Expand size to text size but stay on one line.
115- :cpp:enumerator:`LV_SPAN_MODE_BREAK` Keep width; break lines that are too long and auto-expand height.
116
117Use :cpp:expr:`lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set its mode.
118
119
120Overflow
121--------
122
123A Spangroup can be set to handle text overflow in one of the following ways:
124
125- :cpp:enumerator:`LV_SPAN_OVERFLOW_CLIP` truncates text at the limit of the area.
126- :cpp:enumerator:`LV_SPAN_OVERFLOW_ELLIPSIS` display an ellipsis (``...``) when text overflows the area.
127
128Use :cpp:expr:`lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set
129the Spangroup's overflow mode.
130
131
132First line indent
133-----------------
134
135Use :cpp:expr:`lv_spangroup_set_indent(spangroup, 20)` to set the indent of the
136first line.  All modes support pixel units.  In addition, :cpp:enumerator:`LV_SPAN_MODE_FIXED`
137and :cpp:enumerator:`LV_SPAN_MODE_BREAK` modes support :ref:`percentage units <coord_units>`.
138as well.
139
140
141Lines
142-----
143
144Use :cpp:expr:`lv_spangroup_set_max_lines(spangroup, 10)` to set the maximum number
145of lines to be displayed in :cpp:enumerator:`LV_SPAN_MODE_BREAK` mode.  A negative
146value indicates no limit.
147
148
149
150.. _lv_spangroup_events:
151
152Events
153******
154
155No special events are sent by Span Widgets.
156
157.. admonition::  Further Reading
158
159    Learn more about :ref:`lv_obj_events` emitted by all Widgets.
160
161    Learn more about :ref:`events`.
162
163
164
165.. _lv_spangroup_keys:
166
167Keys
168****
169
170No *Keys* are processed by Span Widgets.
171
172.. admonition::  Further Reading
173
174    Learn more about :ref:`indev_keys`.
175
176
177
178.. _lv_spangroup_example:
179
180Example
181*******
182
183.. include:: ../../examples/widgets/span/index.rst
184
185
186
187.. _lv_spangroup_api:
188
189API
190***
191