富文本 (lv_span)¶

概述¶

spangroup 是用于显示富文本的对象。与标签对象不同，spangroup 可以在对象中渲染具有不同字体、颜色和大小的文本。

部件和样式¶

LV_PART_MAIN spangroup 只有一个部件。

用法¶

设置文本和样式¶

spangroup 对象使用 span 描述文本和文本样式。因此，首先需要使用 lv_span_t * span = lv_spangroup_new_span(spangroup) 创建 span 描述符。然后使用 lv_span_set_text(span, "text") 设置文本。span 的样式通过其 style 成员配置，例如：lv_style_set_text_color(&span->style, lv_palette_main(LV_PALETTE_RED))。

如果 spangroup 对象的 mode != LV_SPAN_MODE_FIXED，在修改 span 样式（例如设置文本、更改字体大小、删除 span）后，必须调用 lv_spangroup_refr_mode()。

获取子 span¶

spangroup 存储其子项的方式与普通对象不同，因此普通的获取子项函数不起作用。

lv_spangroup_get_child(spangroup, id) 将返回索引 id 处的子 span 指针。此外，id 可以为负数，从 spangroup 的末尾开始索引，其中 -1 是最新的子项，-2 是次新的子项，依此类推。

例如：lv_span_t* span = lv_spangroup_get_child(spangroup, 0) 将返回 spangroup 的第一个子项。lv_span_t* span = lv_spangroup_get_child(spangroup, -1) 将返回最后一个（或最新的）子项。

子项计数¶

使用函数 lv_spangroup_get_child_cnt(spangroup) 获取组中维护的 span 数量。

例如：uint32_t size = lv_spangroup_get_child_cnt(spangroup)。

文本对齐¶

与标签对象类似，spangroup 可以设置为以下模式之一：

LV_TEXT_ALIGN_LEFT 左对齐文本。
LV_TEXT_ALIGN_CENTER 居中对齐文本。
LV_TEXT_ALIGN_RIGHT 右对齐文本。
LV_TEXT_ALIGN_AUTO 自动对齐文本。

使用函数 lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER) 设置文本对齐。

模式¶

spangroup 可以设置为以下模式之一：

LV_SPAN_MODE_FIXED 固定对象大小。
LV_SPAN_MODE_EXPAND 将对象大小扩展到文本大小，但保持在单行。
LV_SPAN_MODE_BREAK 保持宽度，换行过长的行并自动扩展高度。

使用 lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK) 设置对象模式。

溢出¶

spangroup 可以设置为以下模式之一：

LV_SPAN_OVERFLOW_CLIP 在区域限制处截断文本。
LV_SPAN_OVERFLOW_ELLIPSIS 当文本溢出区域时显示省略号（...）。

使用 lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP) 设置对象溢出模式。

首行缩进¶

使用 lv_spangroup_set_indent(spangroup, 20) 设置首行缩进。所有模式支持像素单位，此外 LV_SPAN_MODE_FIXED 和 LV_SPAN_MODE_BREAK 模式还支持百分比单位。

行数¶

使用 lv_spangroup_set_lines(spangroup, 10) 设置 LV_SPAN_MODE_BREAK 模式下显示的最大行数，负值表示无限制。

事件¶

此小部件不发送特殊事件。

了解更多关于事件的信息。

按键¶

此对象类型不处理任何按键。

了解更多关于按键的信息。

示例¶

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

#
# 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
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
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.")

spans.refr_mode()

# lv_span_del(spans, span);
# lv_obj_del(spans);

API¶

Typedefs

typedef uint8_t lv_span_overflow_t¶

typedef uint8_t lv_span_mode_t¶

Enums

Values:

enumerator LV_SPAN_OVERFLOW_CLIP¶

enumerator LV_SPAN_OVERFLOW_ELLIPSIS¶

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 object

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.

void lv_spangroup_set_lines(lv_obj_t *obj, int32_t lines)¶

Set lines of the spangroup.

Parameters

obj -- pointer to a spangroup object.
lines -- max lines that can be displayed in LV_SPAN_MODE_BREAK mode. < 0 means no limit.

lv_span_t *lv_spangroup_get_child(const lv_obj_t *obj, int32_t id)¶

Get a spangroup child by its index.

Parameters

obj -- The spangroup object
id -- the index of the child. 0: the oldest (firstly created) child 1: the second oldest child count-1: the youngest -1: the youngest -2: the second youngest

Returns

The child span at index id, or NULL if the ID does not exist

uint32_t lv_spangroup_get_child_cnt(const lv_obj_t *obj)¶

Parameters: obj -- The spangroup object to get the child count of.
Returns: The span count of the spangroup.

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.

int32_t lv_spangroup_get_lines(lv_obj_t *obj)¶

get lines of the spangroup.

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

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.

uint32_t lv_spangroup_get_expand_width(lv_obj_t *obj, uint32_t max_width)¶

get the text content width when all span of spangroup on a line.

Parameters

obj -- pointer to a spangroup object.
max_width -- if text content width >= max_width, return max_width to reduce computation, if max_width == 0, returns the text content width.

Returns

text content width or max_width.

lv_coord_t lv_spangroup_get_expand_height(lv_obj_t *obj, lv_coord_t width)¶

get the text content height with width fixed.

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¶

int32_t lines¶

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¶