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

1 files changed, 23 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