1 /** 2 * @file lv_obj_tree.h 3 * 4 */ 5 6 #ifndef LV_OBJ_TREE_H 7 #define LV_OBJ_TREE_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 /********************* 14 * INCLUDES 15 *********************/ 16 #include "../misc/lv_types.h" 17 #include "../misc/lv_anim.h" 18 #include "../display/lv_display.h" 19 20 /********************* 21 * DEFINES 22 *********************/ 23 24 /********************** 25 * TYPEDEFS 26 **********************/ 27 28 typedef enum { 29 LV_OBJ_TREE_WALK_NEXT, 30 LV_OBJ_TREE_WALK_SKIP_CHILDREN, 31 LV_OBJ_TREE_WALK_END, 32 } lv_obj_tree_walk_res_t; 33 34 typedef lv_obj_tree_walk_res_t (*lv_obj_tree_walk_cb_t)(lv_obj_t *, void *); 35 36 /********************** 37 * GLOBAL PROTOTYPES 38 **********************/ 39 40 /** 41 * Delete an object and all of its children. 42 * Also remove the objects from their group and remove all animations (if any). 43 * Send `LV_EVENT_DELETED` to deleted objects. 44 * @param obj pointer to an object 45 */ 46 void lv_obj_delete(lv_obj_t * obj); 47 48 /** 49 * Delete all children of an object. 50 * Also remove the objects from their group and remove all animations (if any). 51 * Send `LV_EVENT_DELETED` to deleted objects. 52 * @param obj pointer to an object 53 */ 54 void lv_obj_clean(lv_obj_t * obj); 55 56 /** 57 * Delete an object after some delay 58 * @param obj pointer to an object 59 * @param delay_ms time to wait before delete in milliseconds 60 */ 61 void lv_obj_delete_delayed(lv_obj_t * obj, uint32_t delay_ms); 62 63 /** 64 * A function to be easily used in animation ready callback to delete an object when the animation is ready 65 * @param a pointer to the animation 66 */ 67 void lv_obj_delete_anim_completed_cb(lv_anim_t * a); 68 69 /** 70 * Helper function for asynchronously deleting objects. 71 * Useful for cases where you can't delete an object directly in an `LV_EVENT_DELETE` handler (i.e. parent). 72 * @param obj object to delete 73 * @see lv_async_call 74 */ 75 void lv_obj_delete_async(lv_obj_t * obj); 76 77 /** 78 * Move the parent of an object. The relative coordinates will be kept. 79 * 80 * @param obj pointer to an object whose parent needs to be changed 81 * @param parent pointer to the new parent 82 */ 83 void lv_obj_set_parent(lv_obj_t * obj, lv_obj_t * parent); 84 85 /** 86 * Swap the positions of two objects. 87 * When used in listboxes, it can be used to sort the listbox items. 88 * @param obj1 pointer to the first object 89 * @param obj2 pointer to the second object 90 */ 91 void lv_obj_swap(lv_obj_t * obj1, lv_obj_t * obj2); 92 93 /** 94 * moves the object to the given index in its parent. 95 * When used in listboxes, it can be used to sort the listbox items. 96 * @param obj pointer to the object to be moved. 97 * @param index new index in parent. -1 to count from the back 98 * @note to move to the background: lv_obj_move_to_index(obj, 0) 99 * @note to move forward (up): lv_obj_move_to_index(obj, lv_obj_get_index(obj) - 1) 100 */ 101 void lv_obj_move_to_index(lv_obj_t * obj, int32_t index); 102 103 /** 104 * Get the screen of an object 105 * @param obj pointer to an object 106 * @return pointer to the object's screen 107 */ 108 lv_obj_t * lv_obj_get_screen(const lv_obj_t * obj); 109 110 /** 111 * Get the display of the object 112 * @param obj pointer to an object 113 * @return pointer to the object's display 114 */ 115 lv_display_t * lv_obj_get_display(const lv_obj_t * obj); 116 117 /** 118 * Get the parent of an object 119 * @param obj pointer to an object 120 * @return the parent of the object. (NULL if `obj` was a screen) 121 */ 122 lv_obj_t * lv_obj_get_parent(const lv_obj_t * obj); 123 124 /** 125 * Get the child of an object by the child's index. 126 * @param obj pointer to an object whose child should be get 127 * @param idx the index of the child. 128 * 0: the oldest (firstly created) child 129 * 1: the second oldest 130 * child count-1: the youngest 131 * -1: the youngest 132 * -2: the second youngest 133 * @return pointer to the child or NULL if the index was invalid 134 */ 135 lv_obj_t * lv_obj_get_child(const lv_obj_t * obj, int32_t idx); 136 137 /** 138 * Get the child of an object by the child's index. Consider the children only with a given type. 139 * @param obj pointer to an object whose child should be get 140 * @param idx the index of the child. 141 * 0: the oldest (firstly created) child 142 * 1: the second oldest 143 * child count-1: the youngest 144 * -1: the youngest 145 * -2: the second youngest 146 * @param class_p the type of the children to check 147 * @return pointer to the child or NULL if the index was invalid 148 */ 149 lv_obj_t * lv_obj_get_child_by_type(const lv_obj_t * obj, int32_t idx, 150 const lv_obj_class_t * class_p); 151 152 /** 153 * Return a sibling of an object 154 * @param obj pointer to an object whose sibling should be get 155 * @param idx 0: `obj` itself 156 * -1: the first older sibling 157 * -2: the next older sibling 158 * 1: the first younger sibling 159 * 2: the next younger sibling 160 * etc 161 * @return pointer to the requested sibling or NULL if there is no such sibling 162 */ 163 lv_obj_t * lv_obj_get_sibling(const lv_obj_t * obj, int32_t idx); 164 165 /** 166 * Return a sibling of an object. Consider the siblings only with a given type. 167 * @param obj pointer to an object whose sibling should be get 168 * @param idx 0: `obj` itself 169 * -1: the first older sibling 170 * -2: the next older sibling 171 * 1: the first younger sibling 172 * 2: the next younger sibling 173 * etc 174 * @param class_p the type of the children to check 175 * @return pointer to the requested sibling or NULL if there is no such sibling 176 */ 177 lv_obj_t * lv_obj_get_sibling_by_type(const lv_obj_t * obj, int32_t idx, 178 const lv_obj_class_t * class_p); 179 180 /** 181 * Get the number of children 182 * @param obj pointer to an object 183 * @return the number of children 184 */ 185 uint32_t lv_obj_get_child_count(const lv_obj_t * obj); 186 187 /** 188 * Get the number of children having a given type. 189 * @param obj pointer to an object 190 * @param class_p the type of the children to check 191 * @return the number of children 192 */ 193 194 uint32_t lv_obj_get_child_count_by_type(const lv_obj_t * obj, const lv_obj_class_t * class_p); 195 196 /** 197 * Get the index of a child. 198 * @param obj pointer to an object 199 * @return the child index of the object. 200 * E.g. 0: the oldest (firstly created child). 201 * (-1 if child could not be found or no parent exists) 202 */ 203 int32_t lv_obj_get_index(const lv_obj_t * obj); 204 205 /** 206 * Get the index of a child. Consider the children only with a given type. 207 * @param obj pointer to an object 208 * @param class_p the type of the children to check 209 * @return the child index of the object. 210 * E.g. 0: the oldest (firstly created child with the given class). 211 * (-1 if child could not be found or no parent exists) 212 */ 213 int32_t lv_obj_get_index_by_type(const lv_obj_t * obj, const lv_obj_class_t * class_p); 214 215 /** 216 * Iterate through all children of any object. 217 * @param start_obj start integrating from this object 218 * @param cb call this callback on the objects 219 * @param user_data pointer to any user related data (will be passed to `cb`) 220 */ 221 void lv_obj_tree_walk(lv_obj_t * start_obj, lv_obj_tree_walk_cb_t cb, void * user_data); 222 223 /** 224 * Iterate through all children of any object and print their ID. 225 * @param start_obj start integrating from this object 226 */ 227 void lv_obj_dump_tree(lv_obj_t * start_obj); 228 229 /********************** 230 * MACROS 231 **********************/ 232 233 #ifdef __cplusplus 234 } /*extern "C"*/ 235 #endif 236 237 #endif /*LV_OBJ_TREE_H*/ 238
