1# Span (lv_span) 2 3## Overview 4 5A 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. 6 7## Parts and Styles 8- `LV_PART_MAIN` The spangroup has only one part. 9 10## Usage 11 12### Set text and style 13 14The 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))`. 15 16If 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). 17 18### Retrieving a span child 19Spangroups store their children differently from normal objects, so normal functions for getting children won't work. 20 21`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. 22 23e.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. 24 25### Child Count 26Use the function `lv_spangroup_get_child_cnt(spangroup)` to get back the number of spans the group is maintaining. 27 28e.g. `uint32_t size = lv_spangroup_get_child_cnt(spangroup)` 29 30### Text align 31like label object, the spangroup can be set to one the following modes: 32- `LV_TEXT_ALIGN_LEFT` Align text to left. 33- `LV_TEXT_ALIGN_CENTER` Align text to center. 34- `LV_TEXT_ALIGN_RIGHT` Align text to right. 35- `LV_TEXT_ALIGN_AUTO` Align text auto. 36 37use function `lv_spangroup_set_align(spangroup, LV_TEXT_ALIGN_CENTER)` to set text align. 38 39### Modes 40The spangroup can be set to one of the following modes: 41- `LV_SPAN_MODE_FIXED` fixes the object size. 42- `LV_SPAN_MODE_EXPAND` Expand the object size to the text size but stay on a single line. 43- `LV_SPAN_MODE_BREAK` Keep width, break the too long lines and auto expand height. 44 45Use `lv_spangroup_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set object mode. 46 47### Overflow 48The spangroup can be set to one of the following modes: 49- `LV_SPAN_OVERFLOW_CLIP` truncates the text at the limit of the area. 50- `LV_SPAN_OVERFLOW_ELLIPSIS` will display an ellipsis(`...`) when text overflows the area. 51 52Use `lv_spangroup_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set object overflow mode. 53 54### first line indent 55Use `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. 56 57### lines 58Use `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. 59 60## Events 61No special events are sent by this widget. 62 63Learn more about [Events](/overview/event). 64 65## Keys 66No *Keys* are processed by the object type. 67 68Learn more about [Keys](/overview/indev). 69 70## Example 71 72```eval_rst 73 74.. include:: ../../../examples/widgets/span/index.rst 75 76``` 77 78## API 79 80```eval_rst 81 82.. doxygenfile:: lv_span.h 83 :project: lvgl 84 85``` 86
