From d041191ff3fc8e29c83f7bba6cab0f5b4d182d93 Mon Sep 17 00:00:00 2001
From: Drew Hoener <84148896+ahoenerBE@users.noreply.github.com>
Date: Sun, 18 Jul 2021 21:44:27 -0400
Subject: [PATCH] feat(span) Add missing spangroup functions  (#2379)

---
 docs/widgets/extra/span.md       | 12 ++++++
 src/extra/widgets/span/lv_span.c | 65 ++++++++++++++++++++++++++++++++
 src/extra/widgets/span/lv_span.h | 21 +++++++++++
 3 files changed, 98 insertions(+)

diff --git a/docs/widgets/extra/span.md b/docs/widgets/extra/span.md
index 70db66633..9258df62e 100644
--- a/docs/widgets/extra/span.md
+++ b/docs/widgets/extra/span.md
@@ -19,6 +19,18 @@ The spangroup object uses span to describe text and text style. so, first we nee
 
 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).
 
+### Retreiving 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.
diff --git a/src/extra/widgets/span/lv_span.c b/src/extra/widgets/span/lv_span.c
index 6eedc8638..4a4ffd7e6 100644
--- a/src/extra/widgets/span/lv_span.c
+++ b/src/extra/widgets/span/lv_span.c
@@ -254,6 +254,71 @@ void lv_spangroup_set_mode(lv_obj_t * obj, lv_span_mode_t mode)
  * Getter functions
  *====================*/
 
+/**
+ * Get a spangroup child by its index.
+ *
+ * @param obj   The spangroup object
+ * @param 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
+ * @return      The child span at index `id`, or NULL if the ID does not exist
+ */
+lv_span_t * lv_spangroup_get_child(const lv_obj_t * obj, int32_t id)
+{
+    if(obj == NULL) {
+        return NULL;
+    }
+
+    lv_spangroup_t * spans = (lv_spangroup_t *)obj;
+    lv_ll_t * linked_list = &spans->child_ll;
+
+    bool traverse_forwards = (id >= 0);
+    int32_t cur_idx = 0;
+    lv_ll_node_t * cur_node = linked_list->head;
+
+    /*If using a negative index, start from the tail and use cur -1 to indicate the end*/
+    if(!traverse_forwards) {
+        cur_idx = -1;
+        cur_node = linked_list->tail;
+    }
+
+    while(cur_node != NULL) {
+        if(cur_idx == id) {
+            return (lv_span_t *) cur_node;
+        }
+        if(traverse_forwards) {
+            cur_node = (lv_ll_node_t *) _lv_ll_get_next(linked_list, cur_node);
+            cur_idx++;
+        }
+        else {
+            cur_node = (lv_ll_node_t *) _lv_ll_get_prev(linked_list, cur_node);
+            cur_idx--;
+        }
+    }
+
+    return NULL;
+}
+
+/**
+ *
+ * @param obj   The spangroup object to get the child count of.
+ * @return      The span count of the spangroup.
+ */
+uint32_t lv_spangroup_get_child_cnt(const lv_obj_t * obj)
+{
+    LV_ASSERT_OBJ(obj, MY_CLASS);
+
+    if(obj == NULL) {
+        return 0;
+    }
+
+    lv_spangroup_t * spans = (lv_spangroup_t *)obj;
+    return _lv_ll_get_len(&(spans->child_ll));
+}
+
 /**
  * get the align of the spangroup.
  * @param obj pointer to a spangroup object.
diff --git a/src/extra/widgets/span/lv_span.h b/src/extra/widgets/span/lv_span.h
index 4f7613de3..c130465ea 100644
--- a/src/extra/widgets/span/lv_span.h
+++ b/src/extra/widgets/span/lv_span.h
@@ -137,6 +137,27 @@ void lv_spangroup_set_mode(lv_obj_t * obj, lv_span_mode_t mode);
  * Getter functions
  *====================*/
 
+/**
+ * Get a spangroup child by its index.
+ *
+ * @param obj   The spangroup object
+ * @param 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
+ * @return      The child span at index `id`, or NULL if the ID does not exist
+ */
+lv_span_t * lv_spangroup_get_child(const lv_obj_t * obj, int32_t id);
+
+/**
+ *
+ * @param obj   The spangroup object to get the child count of.
+ * @return      The span count of the spangroup.
+ */
+uint32_t lv_spangroup_get_child_cnt(const lv_obj_t * obj);
+
 /**
  * get the align of the spangroup.
  * @param obj pointer to a spangroup object.