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.

Parts and Styles

LV_PART_MAIN Spangroup has only one part.

Usage

Set text and style

Add each needed Span to a Spangroup like this:

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:

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) 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 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 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

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.

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.

Events

No special events are sent by Span Widgets.

Keys

No Keys are processed by Span Widgets.

Example

Span with custom styles

#include "../../lv_examples.h"
#if LV_USE_SPAN && LV_BUILD_EXAMPLES

static void click_event_cb(lv_event_t * e)
{
    lv_obj_t * spans = lv_event_get_target(e);
    lv_indev_t * indev = lv_event_get_indev(e);
    lv_point_t point;
    lv_indev_get_point(indev, &point);
    lv_span_t * span = lv_spangroup_get_span_by_point(spans, &point);

    LV_LOG_USER("%s", span ? lv_span_get_text(span) : "NULL");
}

/**
 * Create spans and get clicked one
 */
void lv_example_span_1(void)
{
    static lv_style_t style;
    lv_style_init(&style);
    lv_style_set_border_width(&style, 1);
    lv_style_set_border_color(&style, lv_palette_main(LV_PALETTE_ORANGE));
    lv_style_set_pad_all(&style, 2);

    lv_obj_t * spans = lv_spangroup_create(lv_screen_active());
    lv_obj_set_width(spans, 300);
    lv_obj_set_height(spans, 300);
    lv_obj_center(spans);
    lv_obj_add_style(spans, &style, 0);
    lv_obj_add_flag(spans, LV_OBJ_FLAG_CLICKABLE);

    lv_spangroup_set_align(spans, LV_TEXT_ALIGN_LEFT);
    lv_spangroup_set_overflow(spans, LV_SPAN_OVERFLOW_CLIP);
    lv_spangroup_set_indent(spans, 20);
    lv_spangroup_set_mode(spans, LV_SPAN_MODE_BREAK);

    lv_span_t * span = lv_spangroup_new_span(spans);
    lv_span_set_text(span, "China is a beautiful country.");
    lv_style_set_text_color(lv_span_get_style(span), lv_palette_main(LV_PALETTE_RED));
    lv_style_set_text_decor(lv_span_get_style(span), LV_TEXT_DECOR_UNDERLINE);
    lv_style_set_text_opa(lv_span_get_style(span), LV_OPA_50);

    span = lv_spangroup_new_span(spans);
    lv_span_set_text_static(span, "good good study, day day up.");
#if LV_FONT_MONTSERRAT_24
    lv_style_set_text_font(lv_span_get_style(span),  &lv_font_montserrat_24);
#endif
    lv_style_set_text_color(lv_span_get_style(span), lv_palette_main(LV_PALETTE_GREEN));

    span = lv_spangroup_new_span(spans);
    lv_span_set_text_static(span, "LVGL is an open-source graphics library.");
    lv_style_set_text_color(lv_span_get_style(span), lv_palette_main(LV_PALETTE_BLUE));

    span = lv_spangroup_new_span(spans);
    lv_span_set_text_static(span, "the boy no name.");
    lv_style_set_text_color(lv_span_get_style(span), lv_palette_main(LV_PALETTE_GREEN));
#if LV_FONT_MONTSERRAT_20
    lv_style_set_text_font(lv_span_get_style(span), &lv_font_montserrat_20);
#endif
    lv_style_set_text_decor(lv_span_get_style(span), LV_TEXT_DECOR_UNDERLINE);

    span = lv_spangroup_new_span(spans);
    lv_span_set_text(span, "I have a dream that hope to come true.");
    lv_style_set_text_decor(lv_span_get_style(span), LV_TEXT_DECOR_STRIKETHROUGH);

    lv_spangroup_refr_mode(spans);

    lv_obj_add_event_cb(spans, click_event_cb, LV_EVENT_CLICKED, NULL);
}

#endif

API

lv_types.h

lv_span.h