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