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¶
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 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:
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. all modes support pixel units, in addition to LV_SPAN_MODE_FIXED and LV_SPAN_MODE_BREAK mode supports percentage units too.
Example¶
Span with custom styles¶
C code
GitHub#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_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_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¶
Enums
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.
-
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.
-
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.
Variables
-
const lv_obj_class_t lv_spangroup_class¶
-
struct lv_span_t¶
-
struct lv_spangroup_t¶
- #include <lv_span.h>
Data of label