feat(obj): add lv_obj_null_on_delete (#6599)HEADmaster

3 files changed, 43 insertions, 0 deletions

diff --git a/docs/overview/obj.rst b/docs/overview/obj.rst
index ef4726be1..d67631efd 100644
--- a/docs/overview/obj.rst
+++ b/docs/overview/obj.rst
@@ -167,6 +167,29 @@ using :cpp:expr:`lv_obj_clean(obj)`.
 You can use :cpp:expr:`lv_obj_delete_delayed(obj, 1000)` to delete an object after
 some time. The delay is expressed in milliseconds.
 
+Sometimes you're not sure whether an object was deleted and you need some way to
+check if it's still "alive". Anytime before the object is deleted, you can use
+cpp:expr:`lv_obj_null_on_delete(&obj)` to cause your object pointer to be set to ``NULL``
+when the object is deleted.
+
+Make sure the pointer variable itself stays valid until the object is deleted. Here
+is an example:
+
+.. code:: c
+
+   void some_timer_callback(lv_timer_t * t)
+   {
+      static lv_obj_t * my_label;
+      if(my_label == NULL) {
+         my_label = lv_label_create(lv_screen_active());
+         lv_obj_delete_delayed(my_label, 1000);
+         lv_obj_null_on_delete(&my_label);
+      }
+      else {
+         lv_obj_set_x(my_label, lv_obj_get_x(my_label) + 1);
+      }
+   }
+
 .. _objects_screens:
 
 Screens
diff --git a/src/core/lv_obj.c b/src/core/lv_obj.c
index ca2048e84..b5fd51f8d 100644
--- a/src/core/lv_obj.c
+++ b/src/core/lv_obj.c
@@ -50,6 +50,7 @@ static void draw_scrollbar(lv_obj_t * obj, lv_layer_t * layer);
 static lv_result_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 void update_obj_state(lv_obj_t * obj, lv_state_t new_state);
+static void null_on_delete_cb(lv_event_t * e);
 
 #if LV_USE_OBJ_PROPERTY
     static lv_result_t lv_obj_set_any(lv_obj_t *, lv_prop_id_t, const lv_property_t *);
@@ -426,6 +427,11 @@ bool lv_obj_is_valid(const lv_obj_t * obj)
     return false;
 }
 
+void lv_obj_null_on_delete(lv_obj_t ** obj_ptr)
+{
+    lv_obj_add_event_cb(*obj_ptr, null_on_delete_cb, LV_EVENT_DELETE, obj_ptr);
+}
+
 #if LV_USE_OBJ_ID
 void lv_obj_set_id(lv_obj_t * obj, void * id)
 {
@@ -988,6 +994,12 @@ static bool obj_valid_child(const lv_obj_t * parent, const lv_obj_t * obj_to_fin
     return false;
 }
 
+static void null_on_delete_cb(lv_event_t * e)
+{
+    lv_obj_t ** obj_ptr = lv_event_get_user_data(e);
+    *obj_ptr = NULL;
+}
+
 #if LV_USE_OBJ_PROPERTY
 static lv_result_t lv_obj_set_any(lv_obj_t * obj, lv_prop_id_t id, const lv_property_t * prop)
 {
diff --git a/src/core/lv_obj.h b/src/core/lv_obj.h
index 9d9eac9a0..3331d7570 100644
--- a/src/core/lv_obj.h
+++ b/src/core/lv_obj.h
@@ -375,6 +375,14 @@ const lv_obj_class_t * lv_obj_get_class(const lv_obj_t * obj);
  */
 bool lv_obj_is_valid(const lv_obj_t * obj);
 
+/**
+ * Utility to set an object reference to NULL when it gets deleted.
+ * The reference should be in a location that will not become invalid
+ * during the object's lifetime, i.e. static or allocated.
+ * @param obj_ptr   a pointer to a pointer to an object
+ */
+void lv_obj_null_on_delete(lv_obj_t ** obj_ptr);
+
 #if LV_USE_OBJ_ID
 /**
  * Set an id for an object.