minor refactoring, commenting

src/core/lv_indev.c

@@ -449,7 +449,7 @@ static void indev_keypad_proc(lv_indev_t * i, lv_indev_data_t * data)
         }
         /*Long press repeated time has elapsed?*/
         else if(i->proc.long_pr_sent != 0 &&
-                lv_tick_elaps(i->proc.longpr_rep_timestamp) > i->driver->long_press_rep_time) {
+                lv_tick_elaps(i->proc.longpr_rep_timestamp) > i->driver->long_press_repeat_time) {
 
             i->proc.longpr_rep_timestamp = lv_tick_get();
 
@@ -602,7 +602,7 @@ static void indev_encoder_proc(lv_indev_t * i, lv_indev_data_t * data)
             i->proc.long_pr_sent = 1;
         }
         /*Long press repeated time has elapsed?*/
-        else if(i->proc.long_pr_sent != 0 && lv_tick_elaps(i->proc.longpr_rep_timestamp) > i->driver->long_press_rep_time) {
+        else if(i->proc.long_pr_sent != 0 && lv_tick_elaps(i->proc.longpr_rep_timestamp) > i->driver->long_press_repeat_time) {
 
             i->proc.longpr_rep_timestamp = lv_tick_get();
 
@@ -879,7 +879,7 @@ static void indev_proc_press(lv_indev_proc_t * proc)
         /*Send long press repeated Call the ancestor's event handler*/
         if(proc->types.pointer.scroll_obj == NULL && proc->long_pr_sent == 1) {
             /*Call the ancestor's event handler about the long press repeat if enough time elapsed*/
-            if(lv_tick_elaps(proc->longpr_rep_timestamp) > indev_act->driver->long_press_rep_time) {
+            if(lv_tick_elaps(proc->longpr_rep_timestamp) > indev_act->driver->long_press_repeat_time) {
                 lv_event_send(indev_obj_act, LV_EVENT_LONG_PRESSED_REPEAT, NULL);
                 if(indev_reset_check(proc)) return;
                 proc->longpr_rep_timestamp = lv_tick_get();

src/core/lv_obj.c

@@ -71,6 +71,7 @@ static void lv_obj_event_cb(lv_obj_t * obj, lv_event_t e);
 static void draw_scrollbar(lv_obj_t * obj, const lv_area_t * clip_area);
 static lv_res_t scrollbar_init_draw_dsc(lv_obj_t * obj, lv_draw_rect_dsc_t * dsc);
 static bool obj_valid_child(const lv_obj_t * parent, const lv_obj_t * obj_to_find);
+static lv_res_t event_send_core(lv_obj_t * obj, lv_event_t event, void * param);
 static void lv_obj_set_state(lv_obj_t * obj, lv_state_t new_state);
 static void base_dir_refr_children(lv_obj_t * obj);
 static bool event_is_bubbled(lv_event_t e);
@@ -82,6 +83,7 @@ static bool lv_initialized = false;
 static lv_event_temp_data_t * event_temp_data_head;
 static void * event_act_param;
 static void * event_act_user_data_cb;
+static lv_obj_t * event_original_target;
 const lv_obj_class_t lv_obj_class = {
     .constructor_cb = lv_obj_constructor,
     .destructor_cb = lv_obj_destructor,
@@ -204,69 +206,15 @@ lv_res_t lv_event_send(lv_obj_t * obj, lv_event_t event, void * param)
 
     LV_ASSERT_OBJ(obj, MY_CLASS);
 
-    EVENT_TRACE("Sending event %d to %p with %p param", event, obj, param);
+    /*Save the original target first in tmp variable because nested `lv_event_send` calls can overwrite it*/
+    lv_obj_t * event_original_target_tmp = event_original_target;
+    event_original_target = obj;
 
-    /*Build a simple linked list from the objects used in the events
+    /*Send the event*/
-     *It's important to know if an this object was deleted by a nested event
+    lv_res_t res = event_send_core(obj, event, param);
-     *called from this `event_cb`.*/
-    lv_event_temp_data_t event_temp_data;
-    event_temp_data.obj     = obj;
-    event_temp_data.deleted = false;
-    event_temp_data.prev    = NULL;
 
-    if(event_temp_data_head) {
+    /*Restore the original target*/
-        event_temp_data.prev = event_temp_data_head;
+    event_original_target = event_original_target_tmp;
-    }
-    event_temp_data_head = &event_temp_data;
-
-    /*There could be nested event sending with different param.
-     *It needs to be saved for the current event context because `lv_event_get_data` returns a global param.*/
-    void * event_act_param_save = event_act_param;
-    event_act_param = param;
-
-    /*Call the input device's feedback callback if set*/
-    lv_indev_t * indev_act = lv_indev_get_act();
-    if(indev_act) {
-        if(indev_act->driver->feedback_cb) indev_act->driver->feedback_cb(indev_act->driver, event);
-    }
-
-    lv_event_dsc_t * event_dsc = lv_obj_get_event_dsc(obj, 0);
-    lv_res_t res = LV_RES_OK;
-    res = lv_obj_event_base(NULL, obj, event);
-
-    uint32_t i = 0;
-    while(event_dsc && res == LV_RES_OK) {
-        if(event_dsc->cb) {
-            void * event_act_user_data_cb_save = event_act_user_data_cb;
-            event_act_user_data_cb = event_dsc->user_data;
-
-            event_dsc->cb(obj, event);
-
-            event_act_user_data_cb = event_act_user_data_cb_save;
-
-            /*Stop if the object is deleted*/
-            if(event_temp_data.deleted) {
-                res = LV_RES_INV;
-                break;
-            }
-        }
-
-        i++;
-        event_dsc = lv_obj_get_event_dsc(obj, i);
-    }
-
-    /*Restore the event param*/
-    event_act_param = event_act_param_save;
-
-    /*Remove this element from the list*/
-    event_temp_data_head = event_temp_data_head->prev;
-
-    if(res == LV_RES_OK && event_is_bubbled(event)) {
-        if(lv_obj_has_flag(obj, LV_OBJ_FLAG_EVENT_BUBBLE) && obj->parent) {
-            res = lv_event_send(obj->parent, event, param);
-            if(res != LV_RES_OK) return LV_RES_INV;
-        }
-    }
 
     return res;
 }
@@ -322,6 +270,11 @@ void * lv_event_get_user_data(void)
     return event_act_user_data_cb;
 }
 
+lv_obj_t * lv_event_get_original_target(void)
+{
+    return event_original_target;
+}
+
 uint32_t lv_event_register_id(void)
 {
     static uint32_t last_id = _LV_EVENT_LAST;
@@ -691,7 +644,7 @@ static void lv_obj_draw(lv_obj_t * obj, lv_event_t e)
         coords.y1 -= h;
         coords.y2 += h;
 
-        if(_lv_area_is_in(info->clip_area, &coords, r) == false) {
+        if(_lv_area_is_in(info->area, &coords, r) == false) {
             info->res = LV_DRAW_RES_NOT_COVER;
            return;
         }
@@ -1078,6 +1031,75 @@ static bool obj_valid_child(const lv_obj_t * parent, const lv_obj_t * obj_to_fin
     return false;
 }
 
+static lv_res_t event_send_core(lv_obj_t * obj, lv_event_t event, void * param)
+{
+    EVENT_TRACE("Sending event %d to %p with %p param", event, obj, param);
+
+    /*Build a simple linked list from the objects used in the events
+     *It's important to know if an this object was deleted by a nested event
+     *called from this `event_cb`.*/
+    lv_event_temp_data_t event_temp_data;
+    event_temp_data.obj     = obj;
+    event_temp_data.deleted = false;
+    event_temp_data.prev    = NULL;
+
+    if(event_temp_data_head) {
+        event_temp_data.prev = event_temp_data_head;
+    }
+    event_temp_data_head = &event_temp_data;
+
+    /*There could be nested event sending with different param.
+     *It needs to be saved for the current event context because `lv_event_get_data` returns a global param.*/
+    void * event_act_param_save = event_act_param;
+    event_act_param = param;
+
+    /*Call the input device's feedback callback if set*/
+    lv_indev_t * indev_act = lv_indev_get_act();
+    if(indev_act) {
+        if(indev_act->driver->feedback_cb) indev_act->driver->feedback_cb(indev_act->driver, event);
+    }
+
+    lv_event_dsc_t * event_dsc = lv_obj_get_event_dsc(obj, 0);
+    lv_res_t res = LV_RES_OK;
+    res = lv_obj_event_base(NULL, obj, event);
+
+    uint32_t i = 0;
+    while(event_dsc && res == LV_RES_OK) {
+        if(event_dsc->cb) {
+            void * event_act_user_data_cb_save = event_act_user_data_cb;
+            event_act_user_data_cb = event_dsc->user_data;
+
+            event_dsc->cb(obj, event);
+
+            event_act_user_data_cb = event_act_user_data_cb_save;
+
+            /*Stop if the object is deleted*/
+            if(event_temp_data.deleted) {
+                res = LV_RES_INV;
+                break;
+            }
+        }
+
+        i++;
+        event_dsc = lv_obj_get_event_dsc(obj, i);
+    }
+
+    /*Restore the event param*/
+    event_act_param = event_act_param_save;
+
+    /*Remove this element from the list*/
+    event_temp_data_head = event_temp_data_head->prev;
+
+    if(res == LV_RES_OK && event_is_bubbled(event)) {
+        if(lv_obj_has_flag(obj, LV_OBJ_FLAG_EVENT_BUBBLE) && obj->parent) {
+            res = event_send_core(obj->parent, event, param);
+            if(res != LV_RES_OK) return LV_RES_INV;
+        }
+    }
+
+    return LV_RES_OK;
+}
+
 static bool event_is_bubbled(lv_event_t e)
 {
     switch(e) {

src/core/lv_obj.h

@@ -47,48 +47,50 @@ typedef enum {
     /** Input device events*/
     LV_EVENT_PRESSED,             /**< The object has been pressed*/
     LV_EVENT_PRESSING,            /**< The object is being pressed (called continuously while pressing)*/
-    LV_EVENT_PRESS_LOST,          /**< User is still being pressed but slid cursor/finger off of the object */
+    LV_EVENT_PRESS_LOST,          /**< The object is still being pressed but slid cursor/finger off of the object */
-    LV_EVENT_SHORT_CLICKED,       /**< User pressed object for a short period of time, then released it. Not called if scrolled.*/
+    LV_EVENT_SHORT_CLICKED,       /**< The object was pressed for a short period of time, then released it. Not called if scrolled.*/
-    LV_EVENT_LONG_PRESSED,        /**< Object has been pressed for at least `LV_INDEV_LONG_PRESS_TIME`.  Not called if scrolled.*/
+    LV_EVENT_LONG_PRESSED,        /**< Object has been pressed for at least `long_press_time`.  Not called if scrolled.*/
-    LV_EVENT_LONG_PRESSED_REPEAT, /**< Called after `LV_INDEV_LONG_PRESS_TIME` in every `LV_INDEV_LONG_PRESS_REP_TIME` ms.  Not called if scrolled.*/
+    LV_EVENT_LONG_PRESSED_REPEAT, /**< Called after `long_press_time` in every `long_press_repeat_time` ms.  Not called if scrolled.*/
     LV_EVENT_CLICKED,             /**< Called on release if not scrolled (regardless to long press)*/
     LV_EVENT_RELEASED,            /**< Called in every cases when the object has been released*/
     LV_EVENT_SCROLL_BEGIN,        /**< Scrolling begins*/
     LV_EVENT_SCROLL_END,          /**< Scrolling ends*/
     LV_EVENT_SCROLL,              /**< Scrolling*/
-    LV_EVENT_GESTURE,             /**< Gesture detected*/
+    LV_EVENT_GESTURE,             /**< A gesture is detected. Get the gesture with `lv_indev_get_gesture_dir(lv_indev_get_act());` */
-    LV_EVENT_KEY,                 /**< A key is sent to the object*/
+    LV_EVENT_KEY,                 /**< A key is sent to the object. Get the key with `lv_indev_get_key(lv_indev_get_act());`*/
-    LV_EVENT_FOCUSED,             /**< Focused */
+    LV_EVENT_FOCUSED,             /**< The object is focused*/
-    LV_EVENT_DEFOCUSED,           /**< Defocused*/
+    LV_EVENT_DEFOCUSED,           /**< The object is defocused*/
-    LV_EVENT_LEAVE,               /**< Defocused but still selected*/
+    LV_EVENT_LEAVE,               /**< The object is defocused but still selected*/
     LV_EVENT_HIT_TEST,            /**< Perform advanced hit-testing*/
 
     /** Drawing events*/
-    LV_EVENT_COVER_CHECK,        /**< Check if the object fully covers an area*/
+    LV_EVENT_COVER_CHECK,        /**< Check if the object fully covers an area. The event parameter is `lv_cover_check_info_t *`.*/
-    LV_EVENT_REFR_EXT_DRAW_SIZE, /**< Get the required extra draw area around the object (e.g. for shadow)*/
+    LV_EVENT_REFR_EXT_DRAW_SIZE, /**< Get the required extra draw area around the object (e.g. for shadow). The event parameter is `lv_coord_t *` to store the size.*/
     LV_EVENT_DRAW_MAIN_BEGIN,    /**< Starting the main drawing phase*/
     LV_EVENT_DRAW_MAIN,          /**< Perform the main drawing*/
     LV_EVENT_DRAW_MAIN_END,      /**< Finishing the main drawing phase*/
     LV_EVENT_DRAW_POST_BEGIN,    /**< Starting the post draw phase (when all children are drawn)*/
     LV_EVENT_DRAW_POST,          /**< Perform the post draw phase (when all children are drawn)*/
     LV_EVENT_DRAW_POST_END,      /**< Finishing the post draw phase (when all children are drawn)*/
-    LV_EVENT_DRAW_PART_BEGIN,    /**< Starting to draw a part*/
+    LV_EVENT_DRAW_PART_BEGIN,    /**< Starting to draw a part. The event parameter is `lv_obj_draw_dsc_t *`. */
-    LV_EVENT_DRAW_PART_END,      /**< Finishing to draw a part*/
+    LV_EVENT_DRAW_PART_END,      /**< Finishing to draw a part. The event parameter is `lv_obj_draw_dsc_t *`. */
 
-    /** General events*/
+    /** Special events*/
     LV_EVENT_VALUE_CHANGED,       /**< The object's value has changed (i.e. slider moved)*/
-    LV_EVENT_INSERT,              /**< A text is inserted to the object*/
+    LV_EVENT_INSERT,              /**< A text is inserted to the object. The event data is `char *` being inserted.*/
     LV_EVENT_REFRESH,             /**< Notify the object to refresh something on it (for the user)*/
-    LV_EVENT_DELETE,              /**< Object is being deleted*/
     LV_EVENT_READY,               /**< A process has finished*/
     LV_EVENT_CANCEL,              /**< A process has been cancelled */
+
+    /** Other events*/
+    LV_EVENT_DELETE,              /**< Object is being deleted*/
     LV_EVENT_CHILD_CHANGED,       /**< Child was removed/added*/
     LV_EVENT_SIZE_CHANGED,       /**< Object coordinates/size have changed*/
     LV_EVENT_STYLE_CHANGED,       /**< Object's style has changed*/
     LV_EVENT_BASE_DIR_CHANGED,    /**< The base dir has changed*/
     LV_EVENT_GET_SELF_SIZE,       /**< Get the internal size of a widget*/
 
-    _LV_EVENT_LAST /** Number of default events*/
+    _LV_EVENT_LAST                /** Number of default events*/
 }lv_event_t;
 
 /**
@@ -247,9 +249,17 @@ typedef struct {
     bool result;
 } lv_hit_test_info_t;
 
+/**
+ * Used as the event parameter of ::LV_EVENT_COVER_CHECK to check if an area is covered by the object or not.
+ * `res` should be set like this:
+ *   - If there is a draw mask on the object set to ::LV_DRAW_RES_MASKED
+ *   - If there is no draw mask but the object simply not covers the area and `res` is not set to ::LV_DRAW_RES_MASKED set to ::LV_DRAW_RES_NOT_COVER
+ *     E.g. `if(cover == false && info->res != LV_DRAW_RES_MASKED) info->res = LV_DRAW_RES_NOT_COVER;`
+ *   - If the area is fully covered by the object leave `res` unchanged.
+ */
 typedef struct {
-    lv_draw_res_t res;
+    lv_draw_res_t res;              /**< Set to ::LV_DRAW_RES_NOT_COVER or ::LV_DRAW_RES_MASKED. */
-    const lv_area_t * clip_area;
+    const lv_area_t * area;         /**< The area to check */
 } lv_cover_check_info_t;
 
 /**********************
@@ -307,6 +317,12 @@ void * lv_event_get_param(void);
  */
 void * lv_event_get_user_data(void);
 
+/**
+ * Get the original target of the event. It's different than the "normal" target if the event is bubbled.
+ * @return      pointer to the object the originally received the event before bubbling it to the parents
+ */
+lv_obj_t * lv_event_get_original_target(void);
+
 /**
  * Register a new, custom event ID.
  * It can be used the same way as e.g. `LV_EVENT_CLICKED` to send custom events
@@ -368,7 +384,7 @@ void lv_obj_clear_state(lv_obj_t * obj, lv_state_t state);
  * An object can have multiple event handler. They will be called in the same order as they were added.
  * @param obj       pointer to an object
  * @param event_cb  the new event function
- * @param user_data custom data data will be available in `event_cb`
+ * @param           user_data custom data data will be available in `event_cb`
  */
 void lv_obj_add_event_cb(lv_obj_t * obj, lv_event_cb_t event_cb, void * user_data);
 
@@ -379,7 +395,7 @@ void lv_obj_add_event_cb(lv_obj_t * obj, lv_event_cb_t event_cb, void * user_dat
  * @param obj       pointer to an object
  * @param event_cb  the event function to remove
  * @param user_data if NULL, remove the first event handler with the same cb, otherwise remove the first event handler with the same cb and user_data
- * @return true if any event handlers were removed
+ * @return          true if any event handlers were removed
  */
 bool lv_obj_remove_event_cb(lv_obj_t * obj, lv_event_cb_t event_cb, void * user_data);
 

src/core/lv_obj_draw.h

@@ -27,13 +27,11 @@ struct _lv_obj_t;
 
 /** Design results*/
 typedef enum {
-    LV_DRAW_RES_OK,          /**< Draw ready*/
     LV_DRAW_RES_COVER,       /**< Returned on `LV_DRAW_COVER_CHK` if the areas is fully covered*/
     LV_DRAW_RES_NOT_COVER,   /**< Returned on `LV_DRAW_COVER_CHK` if the areas is not covered*/
     LV_DRAW_RES_MASKED,      /**< Returned on `LV_DRAW_COVER_CHK` if the areas is masked out (children also not cover)*/
 }lv_draw_res_t;
 
-
 typedef struct
 {
     lv_area_t * draw_area;

src/core/lv_refr.c

@@ -576,7 +576,7 @@ static lv_obj_t * lv_refr_get_top_obj(const lv_area_t * area_p, lv_obj_t * obj)
     if(_lv_area_is_in(area_p, &obj->coords, 0) && lv_obj_has_flag(obj, LV_OBJ_FLAG_HIDDEN) == false) {
         lv_cover_check_info_t info;
         info.res = LV_DRAW_RES_COVER;
-        info.clip_area = area_p;
+        info.area = area_p;
         lv_event_send(obj, LV_EVENT_COVER_CHECK, &info);
         if(info.res == LV_DRAW_RES_MASKED) return NULL;
 

src/hal/lv_hal_indev.c

@@ -62,7 +62,7 @@ void lv_indev_drv_init(lv_indev_drv_t * driver)
     driver->scroll_limit         = LV_INDEV_DEF_SCROLL_LIMIT;
     driver->scroll_throw         = LV_INDEV_DEF_SCROLL_THROW;
     driver->long_press_time      = LV_INDEV_DEF_LONG_PRESS_TIME;
-    driver->long_press_rep_time  = LV_INDEV_DEF_LONG_PRESS_REP_TIME;
+    driver->long_press_repeat_time  = LV_INDEV_DEF_LONG_PRESS_REP_TIME;
     driver->gesture_limit        = LV_INDEV_DEF_GESTURE_LIMIT;
     driver->gesture_min_velocity = LV_INDEV_DEF_GESTURE_MIN_VELOCITY;
 }

src/hal/lv_hal_indev.h

@@ -139,7 +139,7 @@ typedef struct _lv_indev_drv_t {
     uint16_t long_press_time;
 
     /**< Repeated trigger period in long press [ms]*/
-    uint16_t long_press_rep_time;
+    uint16_t long_press_repeat_time;
 } lv_indev_drv_t;
 
 /** Run time data of input devices