Span (lv_span)¶

Overview¶

A spangroup is the object that is used to display rich text. Different from the label object, spangroup can automatically organize text of different fonts, colors, and sizes into the spangroup obj.

Parts and Styles¶

LV_PART_MAIN The spangroup has only one part.

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 modified text is the same as the normal style used, 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).

Text align¶

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

LV_TEXT_ALIGN_LEFT Align text to left.
LV_TEXT_ALIGN_CENTER Align text to center.
LV_TEXT_ALIGN_RIGHT Align text to right.
LV_TEXT_ALIGN_AUTO Align text auto.

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:

LV_SPAN_MODE_FIXED fixes the object size.
LV_SPAN_MODE_EXPAND Expand the object size to the text size but stay on a single line.
LV_SPAN_MODE_BREAK Keep width, break the too long lines and auto expand height.

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:

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

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, in pixels.

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¶

C¶

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_STRIKETHROUGH | LV_TEXT_DECOR_UNDERLINE);
    lv_style_set_text_opa(&span->style, LV_OPA_30);

    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_spangroup_refr_mode(spans);
}

#endif

MicroPython¶

No examples yet.

API¶

Typedefs

typedef uint8_t lv_span_overflow_t¶

typedef uint8_t lv_span_mode_t¶

Enums

enum [anonymous]¶

Values:

enumerator LV_SPAN_OVERFLOW_CLIP¶

enumerator LV_SPAN_OVERFLOW_ELLIPSIS¶

enum [anonymous]¶

Values:

enumerator LV_SPAN_MODE_FIXED¶: fixed the obj size

enumerator LV_SPAN_MODE_EXPAND¶: Expand the object size to the text size

enumerator LV_SPAN_MODE_BREAK¶: Keep width, break the too long lines and expand height

Functions

lv_obj_t *lv_spangroup_create(lv_obj_t *par)¶

Create a spangroup objects

Parameters: par -- pointer to an object, it will be the parent of the new spangroup
Returns: pointer to the created spangroup

lv_span_t *lv_spangroup_new_span(lv_obj_t *obj)¶

Create a span string descriptor and add to spangroup.

Parameters: obj -- pointer to a spangroup object.
Returns: pointer to the created span.

void lv_spangroup_del_span(lv_obj_t *obj, lv_span_t *span)¶

Remove the span from the spangroup and free memory.

Parameters

obj -- pointer to a spangroup object.
span -- pointer to a span.

void lv_span_set_text(lv_span_t *span, const char *text)¶

Set a new text for a span. Memory will be allocated to store the text by the span.

Parameters

span -- pointer to a span.
text -- pointer to a text.

void lv_span_set_text_static(lv_span_t *span, const char *text)¶

Set a static text. It will not be saved by the span so the 'text' variable has to be 'alive' while the span exist.

Parameters

span -- pointer to a span.
text -- pointer to a text.

void lv_spangroup_set_align(lv_obj_t *obj, lv_text_align_t align)¶

Set the align of the spangroup.

Parameters

obj -- pointer to a spangroup object.
align -- see lv_text_align_t for details.

void lv_spangroup_set_overflow(lv_obj_t *obj, lv_span_overflow_t overflow)¶

Set the overflow of the spangroup.

Parameters

obj -- pointer to a spangroup object.
overflow -- see lv_span_overflow_t for details.

void lv_spangroup_set_indent(lv_obj_t *obj, lv_coord_t indent)¶

Set the indent of the spangroup.

Parameters

obj -- pointer to a spangroup object.
indent -- The first line indentation

void lv_spangroup_set_mode(lv_obj_t *obj, lv_span_mode_t mode)¶

Set the mode of the spangroup.

Parameters

obj -- pointer to a spangroup object.
mode -- see lv_span_mode_t for details.

lv_text_align_t lv_spangroup_get_align(lv_obj_t *obj)¶

get the align of the spangroup.

Parameters: obj -- pointer to a spangroup object.
Returns: the align value.

lv_span_overflow_t lv_spangroup_get_overflow(lv_obj_t *obj)¶

get the overflow of the spangroup.

Parameters: obj -- pointer to a spangroup object.
Returns: the overflow value.

lv_coord_t lv_spangroup_get_indent(lv_obj_t *obj)¶

get the indent of the spangroup.

Parameters: obj -- pointer to a spangroup object.
Returns: the indent value.

lv_span_mode_t lv_spangroup_get_mode(lv_obj_t *obj)¶

get the mode of the spangroup.

Parameters: obj -- pointer to a spangroup object.

lv_coord_t lv_spangroup_get_max_line_h(lv_obj_t *obj)¶

get max line height of all span in the spangroup.

Parameters: obj -- pointer to a spangroup object.

lv_coord_t lv_spangroup_get_expand_width(lv_obj_t *obj)¶

get the width when all span of spangroup on a line. include spangroup pad.

Parameters: obj -- pointer to a spangroup object.

lv_coord_t lv_spangroup_get_expand_height(lv_obj_t *obj, lv_coord_t width)¶

get the height with width fixed. the height include spangroup pad.

Parameters: obj -- pointer to a spangroup object.

void lv_spangroup_refr_mode(lv_obj_t *obj)¶

update the mode of the spangroup.

Parameters: obj -- pointer to a spangroup object.

Variables

const lv_obj_class_t lv_spangroup_class¶

struct lv_span_t¶

Public Members

char *txt¶

lv_obj_t *spangroup¶

lv_style_t style¶

uint8_t static_flag¶

struct lv_spangroup_t¶

#include <lv_span.h>

Data of label

Public Members

lv_obj_t obj¶

lv_coord_t indent¶

lv_coord_t cache_w¶

lv_coord_t cache_h¶

lv_ll_t child_ll¶

uint8_t mode¶

uint8_t overflow¶

uint8_t refresh¶