acid-drop

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