1 /**
2  * @file struct _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 <stddef.h>
17 #include <stdbool.h>
18 
19 /*********************
20  *      DEFINES
21  *********************/
22 
23 /**********************
24  *      TYPEDEFS
25  **********************/
26 
27 struct _lv_obj_t;
28 struct _lv_obj_class_t;
29 
30 typedef enum {
31     LV_OBJ_TREE_WALK_NEXT,
32     LV_OBJ_TREE_WALK_SKIP_CHILDREN,
33     LV_OBJ_TREE_WALK_END,
34 } lv_obj_tree_walk_res_t;
35 
36 typedef lv_obj_tree_walk_res_t (*lv_obj_tree_walk_cb_t)(struct _lv_obj_t *, void *);
37 
38 /**********************
39  * GLOBAL PROTOTYPES
40  **********************/
41 
42 /**
43  * Delete an object and all of its children.
44  * Also remove the objects from their group and remove all animations (if any).
45  * Send `LV_EVENT_DELETED` to deleted objects.
46  * @param obj       pointer to an object
47  */
48 void lv_obj_del(struct _lv_obj_t * obj);
49 
50 /**
51  * Delete all children of an object.
52  * Also remove the objects from their group and remove all animations (if any).
53  * Send `LV_EVENT_DELETED` to deleted objects.
54  * @param obj       pointer to an object
55  */
56 void lv_obj_clean(struct _lv_obj_t * obj);
57 
58 /**
59  * Delete an object after some delay
60  * @param obj       pointer to an object
61  * @param delay_ms  time to wait before delete in milliseconds
62  */
63 void lv_obj_del_delayed(struct _lv_obj_t * obj, uint32_t delay_ms);
64 
65 /**
66  * A function to be easily used in animation ready callback to delete an object when the animation is ready
67  * @param a         pointer to the animation
68  */
69 void lv_obj_del_anim_ready_cb(lv_anim_t * a);
70 
71 /**
72  * Helper function for asynchronously deleting objects.
73  * Useful for cases where you can't delete an object directly in an `LV_EVENT_DELETE` handler (i.e. parent).
74  * @param obj       object to delete
75  * @see lv_async_call
76  */
77 void lv_obj_del_async(struct _lv_obj_t * obj);
78 
79 /**
80  * Move the parent of an object. The relative coordinates will be kept.
81  *
82  * @param obj       pointer to an object whose parent needs to be changed
83  * @param parent pointer to the new parent
84  */
85 void lv_obj_set_parent(struct _lv_obj_t * obj, struct _lv_obj_t * parent);
86 
87 /**
88  * Swap the positions of two objects.
89  * When used in listboxes, it can be used to sort the listbox items.
90  * @param obj1  pointer to the first object
91  * @param obj2  pointer to the second object
92  */
93 void lv_obj_swap(struct _lv_obj_t * obj1, struct _lv_obj_t * obj2);
94 
95 /**
96  * moves the object to the given index in its parent.
97  * When used in listboxes, it can be used to sort the listbox items.
98  * @param obj  pointer to the object to be moved.
99  * @param index  new index in parent. -1 to count from the back
100  * @note to move to the background: lv_obj_move_to_index(obj, 0)
101  * @note to move forward (up): lv_obj_move_to_index(obj, lv_obj_get_index(obj) - 1)
102  */
103 void lv_obj_move_to_index(struct _lv_obj_t * obj, int32_t index);
104 
105 /**
106  * Get the screen of an object
107  * @param obj       pointer to an object
108  * @return          pointer to the object's screen
109  */
110 struct _lv_obj_t * lv_obj_get_screen(const struct _lv_obj_t * obj);
111 
112 /**
113  * Get the display of the object
114  * @param obj       pointer to an object
115  * @return          pointer to the object's display
116  */
117 lv_disp_t * lv_obj_get_disp(const struct _lv_obj_t * obj);
118 
119 /**
120  * Get the parent of an object
121  * @param obj       pointer to an object
122  * @return          the parent of the object. (NULL if `obj` was a screen)
123  */
124 struct _lv_obj_t * lv_obj_get_parent(const struct _lv_obj_t * obj);
125 
126 /**
127  * Get the child of an object by the child's index.
128  * @param obj       pointer to an object whose child should be get
129  * @param id        the index of the child.
130  *                  0: the oldest (firstly created) child
131  *                  1: the second oldest
132  *                  child count-1: the youngest
133  *                  -1: the youngest
134  *                  -2: the second youngest
135  * @return          pointer to the child or NULL if the index was invalid
136  */
137 struct _lv_obj_t * lv_obj_get_child(const struct _lv_obj_t * obj, int32_t id);
138 
139 /**
140  * Get the number of children
141  * @param obj       pointer to an object
142  * @return          the number of children
143  */
144 uint32_t lv_obj_get_child_cnt(const struct _lv_obj_t * obj);
145 
146 /**
147  * Get the index of a child.
148  * @param obj       pointer to an object
149  * @return          the child index of the object.
150  *                  E.g. 0: the oldest (firstly created child)
151  */
152 uint32_t lv_obj_get_index(const struct _lv_obj_t * obj);
153 
154 /**
155  * Iterate through all children of any object.
156  * @param start_obj     start integrating from this object
157  * @param cb            call this callback on the objects
158  * @param user_data     pointer to any user related data (will be passed to `cb`)
159  */
160 void lv_obj_tree_walk(struct _lv_obj_t * start_obj, lv_obj_tree_walk_cb_t cb, void * user_data);
161 
162 /**********************
163  *      MACROS
164  **********************/
165 
166 #ifdef __cplusplus
167 } /*extern "C"*/
168 #endif
169 
170 #endif /*LV_OBJ_TREE_H*/
171