add span widget (#2227)

Co-authored-by: guowei15 <guowei15@xiaomi.com>

Kconfig

@@ -698,6 +698,8 @@ menu "LVGL configuration"
             bool "Tileview"
         config LV_USE_WIN
             bool "Win"
+        config LV_USE_SPAN
+            bool "span"
     endmenu
 
     menu "Layouts"

docs/widgets/extra/span.md

@@ -0,0 +1,74 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/widgets/span.md
+```
+# 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 the part.
+ 
+## Usage
+
+### Set text and style
+
+spangroup object uses span to describe text and text style. so, first we need to create `span` descriptor use function `lv_span_t * span = lv_span_create(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_span_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 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_span_set_align(spangroup, LV_TEXT_ALIGN_CENTER)` to set text align.
+
+### Modes
+The spangroup can be one the following modes:
+- `LV_SPAN_MODE_FIXED` fixed the obj size.
+- `LV_SPAN_MODE_EXPAND` Expand the object size to the text size. only one line.
+- `LV_SPAN_MODE_BREAK` Keep width, break the too long lines and auto expand height.
+
+use function `lv_span_set_mode(spangroup, LV_SPAN_MODE_BREAK)` to set obj mode.
+
+### Overflow
+The spangroup can be one the following modes:
+- `LV_SPAN_OVERFLOW_CLIP` truncate the text at the limit of the area.
+- `LV_SPAN_OVERFLOW_ELLIPSIS` This mode value will display an ellipsis(`...`) when text overflow the area.
+
+use function `lv_span_set_overflow(spangroup, LV_SPAN_OVERFLOW_CLIP)` to set obj Overflow.
+
+### first line indent
+use function `lv_span_set_indent(spangroup, 20)` to set text indent of first line.
+
+## Events
+Only the [Generic events](../overview/event.html#generic-events) are sent by the object type.
+
+Learn more about [Events](/overview/event).
+
+## Keys
+No *Keys* are processed by the object type.
+
+Learn more about [Keys](/overview/indev).
+
+## Example
+
+```eval_rst
+
+.. include:: ../../../examples/widgets/span/index.rst
+
+```
+
+## API
+
+```eval_rst
+
+.. doxygenfile:: lv_span.h
+  :project: lvgl
+
+```

examples/widgets/lv_example_widgets.h

@@ -118,6 +118,8 @@ void lv_example_tileview_1(void);
 
 void lv_example_win_1(void);
 
+void lv_example_span_1(void);
+
 /**********************
  *      MACROS
  **********************/

examples/widgets/span/index.rst

@@ -0,0 +1,13 @@
+C
+^
+
+span with custom style
+"""""""""""""""""""""
+
+.. lv_example:: lv_ex_widgets/lv_ex_span/lv_ex_span_1
+  :language: c
+
+MicroPython
+^^^^^^^^^^^
+
+No examples yet.

examples/widgets/span/lv_example_span_1.c

@@ -0,0 +1,60 @@
+#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_span_set_align(spans, LV_TEXT_ALIGN_LEFT);
+    lv_span_set_overflow(spans, LV_SPAN_OVERFLOW_CLIP);
+    lv_span_set_indent(spans, 20);
+    lv_span_set_mode(spans, LV_SPAN_MODE_BREAK);
+
+    lv_span_t * span = lv_span_create(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_span_create(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_span_create(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_span_create(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_span_create(spans);
+    lv_span_set_text(span, "I have a dream that hope to come true.");
+
+    lv_span_refr_mode(spans);
+
+    //lv_span_del(spans, span);
+    //lv_obj_del(spans);
+}
+
+#endif

lv_conf_template.h

@@ -459,6 +459,12 @@ e.g. "stm32f769xx.h" or "stm32f429xx.h"*/
 
 #define LV_USE_WIN          1
 
+#define LV_USE_SPAN         1
+#if LV_USE_SPAN
+/*A line text can contain maximum num of span descriptor */
+#  define LV_SPAN_SNIPPET_STACK_SIZE   64
+#endif
+
 /*-----------
  * Themes
  *----------*/

src/draw/lv_draw_label.c

@@ -32,9 +32,6 @@ typedef uint8_t cmd_state_t;
 /**********************
  *  STATIC PROTOTYPES
  **********************/
-LV_ATTRIBUTE_FAST_MEM static void lv_draw_letter(const lv_point_t * pos_p, const lv_area_t * clip_area,
-                                                 const lv_font_t * font_p,
-                                                 uint32_t letter, lv_color_t color, lv_opa_t opa, lv_blend_mode_t blend_mode);
 LV_ATTRIBUTE_FAST_MEM static void draw_letter_normal(lv_coord_t pos_x, lv_coord_t pos_y, lv_font_glyph_dsc_t * g,
                                                      const lv_area_t * clip_area,
                                                      const uint8_t * map_p, lv_color_t color, lv_opa_t opa, lv_blend_mode_t blend_mode);
@@ -398,10 +395,10 @@ LV_ATTRIBUTE_FAST_MEM void lv_draw_label(const lv_area_t * coords, const lv_area
  * @param color color of letter
  * @param opa opacity of letter (0..255)
  */
-LV_ATTRIBUTE_FAST_MEM static void lv_draw_letter(const lv_point_t * pos_p, const lv_area_t * clip_area,
-                                                 const lv_font_t * font_p,
-                                                 uint32_t letter,
-                                                 lv_color_t color, lv_opa_t opa, lv_blend_mode_t blend_mode)
+LV_ATTRIBUTE_FAST_MEM void lv_draw_letter(const lv_point_t * pos_p, const lv_area_t * clip_area,
+                                          const lv_font_t * font_p,
+                                          uint32_t letter,
+                                          lv_color_t color, lv_opa_t opa, lv_blend_mode_t blend_mode)
 {
     if(opa < LV_OPA_MIN) return;
     if(opa > LV_OPA_MAX) opa = LV_OPA_COVER;

src/draw/lv_draw_label.h

@@ -84,6 +84,9 @@ LV_ATTRIBUTE_FAST_MEM void lv_draw_label(const lv_area_t * coords, const lv_area
                                          const lv_draw_label_dsc_t * dsc,
                                          const char * txt, lv_draw_label_hint_t * hint);
 
+LV_ATTRIBUTE_FAST_MEM void lv_draw_letter(const lv_point_t * pos_p, const lv_area_t * clip_area,
+                                          const lv_font_t * font_p,
+                                          uint32_t letter, lv_color_t color, lv_opa_t opa, lv_blend_mode_t blend_mode);
 //! @endcond
 /***********************
  * GLOBAL VARIABLES

src/extra/widgets/lv_widgets.h

@@ -30,7 +30,7 @@ extern "C" {
 #include "colorwheel/lv_colorwheel.h"
 #include "led/lv_led.h"
 #include "imgbtn/lv_imgbtn.h"
-
+#include "span/lv_span.h"
 
 /*********************
  *      DEFINES

src/extra/widgets/span/lv_span.h

@@ -0,0 +1,203 @@
+/**
+ * @file lv_span.h
+ *
+ */
+
+#ifndef LV_SPAN_H
+#define LV_SPAN_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*********************
+ *      INCLUDES
+ *********************/
+#include "../../../lvgl.h"
+
+#if LV_USE_SPAN != 0
+
+/*********************
+ *      DEFINES
+ *********************/
+#ifndef LV_SPAN_SNIPPET_STACK_SIZE
+#define LV_SPAN_SNIPPET_STACK_SIZE 64
+#endif
+
+/**********************
+ *      TYPEDEFS
+ **********************/
+enum {
+    LV_SPAN_OVERFLOW_CLIP,
+    LV_SPAN_OVERFLOW_ELLIPSIS,
+};
+typedef uint8_t lv_span_overflow_t;
+
+enum {
+    LV_SPAN_MODE_FIXED,     /**< fixed the obj size*/
+    LV_SPAN_MODE_EXPAND,    /**< Expand the object size to the text size*/
+    LV_SPAN_MODE_BREAK,     /**< Keep width, break the too long lines and expand height*/
+};
+typedef uint8_t lv_span_mode_t;
+
+typedef struct {
+    char * txt;
+    lv_style_t style;
+    uint8_t static_flag : 1;
+} lv_span_t;
+
+/** Data of label*/
+typedef struct {
+    lv_obj_t obj;
+    lv_coord_t indent;
+    lv_ll_t  child_ll;
+    uint8_t mode : 2;
+    uint8_t align : 2;
+    uint8_t overflow : 1;
+} lv_spangroup_t;
+
+extern const lv_obj_class_t lv_spangroup_class;
+
+/**********************
+ * GLOBAL PROTOTYPES
+ **********************/
+
+/**
+ * Create a spangroup objects
+ * @param par pointer to an object, it will be the parent of the new spangroup
+ * @return pointer to the created spangroup
+ */
+lv_obj_t * lv_spangroup_create(lv_obj_t * par);
+
+/**
+ * Create a span string descriptor and add to spangroup.
+ * @param obj pointer to a spangroup object.
+ * @return pointer to the created span.
+ */
+lv_span_t * lv_span_create(lv_obj_t * obj);
+
+/**
+ * Remove the span from the spangroup and free memory.
+ * @param obj pointer to a spangroup object.
+ * @param span pointer to a span.
+ */
+void lv_span_del(lv_obj_t * obj, lv_span_t * span);
+
+/*=====================
+ * Setter functions
+ *====================*/
+
+/**
+ * Set a new text for a span. Memory will be allocated to store the text by the span.
+ * @param span pointer to a span.
+ * @param text pointer to a text.
+ */
+void lv_span_set_text(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.
+ * @param span pointer to a span.
+ * @param text pointer to a text.
+ */
+void lv_span_set_text_static(lv_span_t * span, const char * text);
+
+/**
+ * Set the align of the spangroup.
+ * @param obj pointer to a spangroup object.
+ * @param align see lv_text_align_t for details.
+ */
+void lv_span_set_align(lv_obj_t * obj, lv_text_align_t align);
+
+/**
+ * Set the overflow of the spangroup.
+ * @param obj pointer to a spangroup object.
+ * @param overflow see lv_span_overflow_t for details.
+ */
+void lv_span_set_overflow(lv_obj_t * obj, lv_span_overflow_t overflow);
+
+/**
+ * Set the indent of the spangroup.
+ * @param obj pointer to a spangroup object.
+ * @param indent The first line indentation
+ */
+void lv_span_set_indent(lv_obj_t * obj, lv_coord_t indent);
+
+/**
+ * Set the mode of the spangroup.
+ * @param obj pointer to a spangroup object.
+ * @param mode see lv_span_mode_t for details.
+ */
+void lv_span_set_mode(lv_obj_t * obj, lv_span_mode_t mode);
+
+/*=====================
+ * Getter functions
+ *====================*/
+
+/**
+ * get the align of the spangroup.
+ * @param obj pointer to a spangroup object.
+ * @return the align value.
+ */
+lv_text_align_t lv_span_get_align(lv_obj_t * obj);
+
+/**
+ * get the overflow of the spangroup.
+ * @param obj pointer to a spangroup object.
+ * @return the overflow value.
+ */
+lv_span_overflow_t lv_span_get_overflow(lv_obj_t * obj);
+
+/**
+ * get the indent of the spangroup.
+ * @param obj pointer to a spangroup object.
+ * @return the indent value.
+ */
+lv_coord_t lv_span_get_indent(lv_obj_t * obj);
+
+/**
+ * get the mode of the spangroup.
+ * @param obj pointer to a spangroup object.
+ */
+lv_span_mode_t lv_span_get_mode(lv_obj_t * obj);
+
+/**
+ * get max line height of all span in the spangroup.
+ * @param obj pointer to a spangroup object.
+ */
+lv_coord_t lv_span_get_max_line_h(lv_obj_t * obj);
+
+/**
+ * get the width when all span of spangroup on a line. include spangroup pad.
+ * @param obj pointer to a spangroup object.
+ */
+lv_coord_t lv_span_get_expand_width(lv_obj_t * obj);
+
+/**
+ * get the height with width fixed. the height include spangroup pad.
+ * @param obj pointer to a spangroup object.
+ */
+lv_coord_t lv_span_get_expand_height(lv_obj_t * obj, lv_coord_t width);
+
+
+/*=====================
+ * Other functions
+ *====================*/
+
+/**
+ * update the mode of the spangroup.
+ * @param obj pointer to a spangroup object.
+ */
+void lv_span_refr_mode(lv_obj_t * obj);
+
+/**********************
+ *      MACROS
+ **********************/
+
+#endif /*LV_USE_SPAN*/
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /*LV_SPAN_H*/

src/lv_conf_internal.h

@@ -1393,6 +1393,14 @@ e.g. "stm32f769xx.h" or "stm32f429xx.h"*/
 #  endif
 #endif
 
+#ifndef LV_USE_SPAN
+#  ifdef CONFIG_LV_USE_SPAN
+#    define LV_USE_SPAN CONFIG_LV_USE_SPAN
+#  else
+#    define  LV_USE_SPAN          1
+#  endif
+#endif
+
 /*-----------
  * Themes
  *----------*/