Span (lv_span)

Overview

A spangroup is the object that is used to display rich text. Different from the label object, spangroup can render text styled with different fonts, colors, and sizes into the spangroup object.

Parts and Styles

Usage

Set text and style

The spangroup object uses span to describe text and text style. so, first we need to create span descriptor using lv_span_t * span = lv_spangroup_new_span(spangroup). Then use lv_span_set_text(span, "text") to set text. The style of the span is configured as with a normal style object by using its style member, eg:lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED)).

If spangroup object mode != LV_SPAN_MODE_FIXED you must call lv_spangroup_refr_mode() after you have modified span style(eg:set text, changed the font size, del span).

Retrieving a span child

Spangroups store their children differently from normal objects, 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 the function lv_spangroup_get_child_cnt(spangroup) to get back the number of spans the group is maintaining.

e.g. uint32_t size = lv_spangroup_get_child_cnt(spangroup)

Text align

like label object, the spangroup can be set to one the following modes:

use function lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER) to set text align.

Modes

The spangroup can be set to one the following modes:

Use lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK) to set object mode.

Overflow

The spangroup can be set to one the following modes:

Use lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP) to set object 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 to LV_SPAN_MODE_FIXED and LV_SPAN_MODE_BREAK mode supports percentage units too.

lines

Use lv_spangroup_set_lines(spangroup, 10) to set the maximum number of lines to be displayed in LV_SPAN_MODE_BREAK mode, negative values indicate no limit.

Events

No special events are sent by this widget.

Learn more about Events.

Keys

No Keys are processed by the object type.

Learn more about Keys.

Example

Span with custom styles

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

/**
 * Create span.
 */
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_scr_act());
    lv_obj_set_width(spans, 300);
    lv_obj_set_height(spans, 300);
    lv_obj_center(spans);
    lv_obj_add_style(spans, &style, 0);

    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(&span->style, lv_palette_main(LV_PALETTE_RED));
    lv_style_set_text_decor(&span->style, LV_TEXT_DECOR_UNDERLINE);
    lv_style_set_text_opa(&span->style, 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(&span->style,  &lv_font_montserrat_24);
#endif
    lv_style_set_text_color(&span->style, 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(&span->style, 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(&span->style, lv_palette_main(LV_PALETTE_GREEN));
#if LV_FONT_MONTSERRAT_20
    lv_style_set_text_font(&span->style, &lv_font_montserrat_20);
#endif
    lv_style_set_text_decor(&span->style, 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(&span->style, LV_TEXT_DECOR_STRIKETHROUGH);

    lv_spangroup_refr_mode(spans);
}

#endif
#!/opt/bin/lv_micropython -i

import lvgl as lv
import display_driver

import fs_driver
fs_drv = lv.fs_drv_t()
fs_driver.fs_register(fs_drv, 'S')

#
# Create span
#
style = lv.style_t()
style.init()
style.set_border_width(1)
style.set_border_color(lv.palette_main(lv.PALETTE.ORANGE))
style.set_pad_all(2)

spans = lv.spangroup(lv.scr_act())
spans.set_width(300)
spans.set_height(300)
spans.center()
spans.add_style(style, 0)

spans.set_align(lv.TEXT_ALIGN.LEFT)
spans.set_overflow(lv.SPAN_OVERFLOW.CLIP)
spans.set_indent(20)
spans.set_mode(lv.SPAN_MODE.BREAK)

span = spans.new_span()
span.set_text("china is a beautiful country.")
span.style.set_text_color(lv.palette_main(lv.PALETTE.RED))
span.style.set_text_decor(lv.TEXT_DECOR.STRIKETHROUGH | lv.TEXT_DECOR.UNDERLINE)
span.style.set_text_opa(lv.OPA._30)

span = spans.new_span()
span.set_text_static("good good study, day day up.")

#if LV_FONT_MONTSERRAT_24
#    lv_style_set_text_font(&span->style,  &lv_font_montserrat_24);
#endif

try:
    span.style.set_text_font(ltr_label, lv.font_montserrat_24)
except:
    fs_drv = lv.fs_drv_t()
    fs_driver.fs_register(fs_drv, 'S')
    print("montserrat-24 not enabled in lv_conf.h, dynamically loading the font")
    
    # get the directory in which the script is running
    try:
        script_path = __file__[:__file__.rfind('/')] if __file__.find('/') >= 0 else '.'
    except NameError:
        print("Could not find script path")
        script_path = ''
    if script_path != '':
        try:
            font_montserrat_24 = lv.font_load("S:" + script_path + "/../../assets/font/montserrat-24.fnt")
            span.style.set_text_font(font_montserrat_24)            
        except:
            print("Cannot load font file montserrat-24.fnt")

span.style.set_text_color(lv.palette_main(lv.PALETTE.GREEN))
span = spans.new_span()
span.set_text_static("LVGL is an open-source graphics library.")
span.style.set_text_color(lv.palette_main(lv.PALETTE.BLUE))

span = spans.new_span()
span.set_text_static("the boy no name.")
span.style.set_text_color(lv.palette_main(lv.PALETTE.GREEN))
#if LV_FONT_MONTSERRAT_20
#    lv_style_set_text_font(&span->style, &lv_font_montserrat_20);
#endif
try:
    span.style.set_text_font(ltr_label, lv.font_montserrat_20)
except:
    fs_drv = lv.fs_drv_t()
    fs_driver.fs_register(fs_drv, 'S')
    print("montserrat-20 not enabled in lv_conf.h, dynamically loading the font")
    
    # get the directory in which the script is running
    try:
        script_path = __file__[:__file__.rfind('/')] if __file__.find('/') >= 0 else '.'
    except NameError:
        print("Could not find script path")
        script_path = ''
    if script_path != '':
        try:
            font_montserrat_20 = lv.font_load("S:" + script_path + "/../../assets/font/montserrat-20.fnt")
            span.style.set_text_font(font_montserrat_20)            
        except:
            print("Cannot load font file montserrat-20.fnt")

span.style.set_text_decor(lv.TEXT_DECOR.UNDERLINE)

span = spans.new_span()
span.set_text("I have a dream that hope to come true.")
span.style.set_text_decor(lv.TEXT_DECOR.STRIKETHROUGH)
spans.refr_mode()



API

lv_span.h