Spangroup (lv_spangroup)

Display rich text where each part (Span) has its own font, color, and size.

Overview

A Spangroup displays rich text. Unlike a Label, each Span inside the group has its own text, font, color, and size. Spans can be added or removed at any time.

Create spans

Add each needed Span to a Spangroup like this:

lv_span_t * span = lv_spangroup_new_span(spangroup);

Set text

After a Span is created, use the following functions to set its text and style properties:

• lv_span_set_text(span, "text")
• lv_style_set_<property_name>(&span->style, value)

Example of the latter: lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED)).

If the Spangroup Widget's mode != LV_SPAN_MODE_FIXED call 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.

lv_spangroup_get_child(spangroup, id) returns the Span at index id. Negative indices count from the end (-1 = last, -2 = second to last).

To resolve a span from a screen coordinate — for example the point where the Spangroup was clicked — use lv_spangroup_get_span_by_point(spangroup, &point). The example below makes the group clickable and logs the text of whichever span was hit.

Child count

Use lv_spangroup_get_span_count(spangroup) to get the number of contained Spans.

Removing a Span

You can remove a Span at any time during the Spangroup's life using the function lv_spangroup_delete_span(spangroup, span).

Text align

Like the Label Widget, a Spangroup can be set to one the following text-alignment modes:

• LV_TEXT_ALIGN_LEFT Align text to left.
• LV_TEXT_ALIGN_CENTER Center text.
• LV_TEXT_ALIGN_RIGHT Align text to right edge.
• LV_TEXT_ALIGN_AUTO Align auto.

Use function lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_...) to set text alignment.

Modes

DEPRECATED, set the width to LV_SIZE_CONTENT or fixed value to control expanding/wrapping.

A Spangroup can be set to one the following modes:

• LV_SPAN_MODE_FIXED Fixes its size.
• LV_SPAN_MODE_EXPAND Expand size to text size but stay on one line.
• LV_SPAN_MODE_BREAK Keep width; break lines that are too long and auto-expand height.

Use 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:

• LV_SPAN_OVERFLOW_CLIP truncates text at the limit of the area.
• LV_SPAN_OVERFLOW_ELLIPSIS display an ellipsis (...) when text overflows the area.

Use lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP) to set the Spangroup's overflow mode.

First line indent

Use lv_spangroup_set_indent(spangroup, 20) to set the indent of the first line. All modes support pixel units. In addition, LV_SPAN_MODE_FIXED and LV_SPAN_MODE_BREAK modes support percentage units as well (e.g. lv_pct(10)).

Lines

Use lv_spangroup_set_max_lines(spangroup, 10) to set the maximum number of lines to be displayed in LV_SPAN_MODE_BREAK mode. A negative value indicates no limit.

Styling

LV_PART_MAIN Spangroup has only one part.

Data binding

A Span binds its text to a Subject. The link is one-way (Subject → Widget) — the binding works like Label-text binding, except both the Spangroup and the Span need to be specified in the bind call:

Note that before calling lv_spangroup_delete_span, lv_observer_delete needs to be called manually as LVGL can't remove the binding automatically.

Events

By default, Spangroup Widgets are created without the LV_OBJ_FLAG_CLICKABLE flag, but you can add it to make the Widget detect and send events LV_EVENT_CLICKED.

Learn more about Events emitted by all Widgets.