1 /**
2  * Public header for Fragment
3  * @file lv_fragment.h
4  */
5 
6 #ifndef LV_FRAGMENT_H
7 #define LV_FRAGMENT_H
8 
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12 
13 /*********************
14  *      INCLUDES
15  *********************/
16 #include "../../../lv_conf_internal.h"
17 
18 #if LV_USE_FRAGMENT
19 
20 #include "../../../core/lv_obj.h"
21 
22 /*********************
23  *      DEFINES
24  *********************/
25 
26 /**********************
27  *      TYPEDEFS
28  **********************/
29 
30 typedef struct _lv_fragment_manager_t lv_fragment_manager_t;
31 
32 typedef struct _lv_fragment_t lv_fragment_t;
33 typedef struct _lv_fragment_class_t lv_fragment_class_t;
34 typedef struct _lv_fragment_managed_states_t lv_fragment_managed_states_t;
35 
36 struct _lv_fragment_t {
37     /**
38      * Class of this fragment
39      */
40     const lv_fragment_class_t * cls;
41     /**
42      * Managed fragment states. If not null, then this fragment is managed.
43      *
44      * @warning Don't modify values inside this struct!
45      */
46     lv_fragment_managed_states_t * managed;
47     /**
48      * Child fragment manager
49      */
50     lv_fragment_manager_t * child_manager;
51     /**
52      * lv_obj returned by create_obj_cb
53      */
54     lv_obj_t * obj;
55 
56 };
57 
58 struct _lv_fragment_class_t {
59     /**
60      * Constructor function for fragment class
61      * @param self Fragment instance
62      * @param args Arguments assigned by fragment manager
63      */
64     void (*constructor_cb)(lv_fragment_t * self, void * args);
65 
66     /**
67      * Destructor function for fragment class
68      * @param self Fragment instance, will be freed after this call
69      */
70     void (*destructor_cb)(lv_fragment_t * self);
71 
72     /**
73      * Fragment attached to manager
74      * @param self Fragment instance
75      */
76     void (*attached_cb)(lv_fragment_t * self);
77 
78     /**
79      * Fragment detached from manager
80      * @param self Fragment instance
81      */
82     void (*detached_cb)(lv_fragment_t * self);
83 
84     /**
85      * Create objects
86      * @param self Fragment instance
87      * @param container Container of the objects should be created upon
88      * @return Created object, NULL if multiple objects has been created
89      */
90     lv_obj_t * (*create_obj_cb)(lv_fragment_t * self, lv_obj_t * container);
91 
92     /**
93      *
94      * @param self Fragment instance
95      * @param obj lv_obj returned by create_obj_cb
96      */
97     void (*obj_created_cb)(lv_fragment_t * self, lv_obj_t * obj);
98 
99     /**
100      * Called before objects in the fragment will be deleted.
101      *
102      * @param self Fragment instance
103      * @param obj object with this fragment
104      */
105     void (*obj_will_delete_cb)(lv_fragment_t * self, lv_obj_t * obj);
106 
107     /**
108      * Called when the object created by fragment received `LV_EVENT_DELETE` event
109      * @param self Fragment instance
110      * @param obj object with this fragment
111      */
112     void (*obj_deleted_cb)(lv_fragment_t * self, lv_obj_t * obj);
113 
114     /**
115      * Handle event
116      * @param self Fragment instance
117      * @param which User-defined ID of event
118      * @param data1 User-defined data
119      * @param data2 User-defined data
120      */
121     bool (*event_cb)(lv_fragment_t * self, int code, void * userdata);
122 
123     /**
124      * *REQUIRED*: Allocation size of fragment
125      */
126     size_t instance_size;
127 };
128 
129 /**
130  * Fragment states
131  */
132 typedef struct _lv_fragment_managed_states_t  {
133     /**
134      * Class of the fragment
135      */
136     const lv_fragment_class_t * cls;
137     /**
138      * Manager the fragment attached to
139      */
140     lv_fragment_manager_t * manager;
141     /**
142      * Container object the fragment adding view to
143      */
144     lv_obj_t * const * container;
145     /**
146      * Fragment instance
147      */
148     lv_fragment_t * instance;
149     /**
150      * true between `create_obj_cb` and `obj_deleted_cb`
151      */
152     bool obj_created;
153     /**
154      * true before `lv_fragment_del_obj` is called. Don't touch any object if this is true
155      */
156     bool destroying_obj;
157     /**
158      * true if this fragment is in navigation stack that can be popped
159      */
160     bool in_stack;
161 } lv_fragment_managed_states_t;
162 
163 /**********************
164  * GLOBAL PROTOTYPES
165  **********************/
166 
167 /**
168  * Create fragment manager instance
169  * @param parent Parent fragment if this manager is placed inside another fragment, can be null.
170  * @return Fragment manager instance
171  */
172 lv_fragment_manager_t * lv_fragment_manager_create(lv_fragment_t * parent);
173 
174 /**
175  * Destroy fragment manager instance
176  * @param manager Fragment manager instance
177  */
178 void lv_fragment_manager_del(lv_fragment_manager_t * manager);
179 
180 /**
181  * Create object of all fragments managed by this manager.
182  * @param manager Fragment manager instance
183  */
184 void lv_fragment_manager_create_obj(lv_fragment_manager_t * manager);
185 
186 /**
187  * Delete object created by all fragments managed by this manager. Instance of fragments will not be deleted.
188  * @param manager Fragment manager instance
189  */
190 void lv_fragment_manager_del_obj(lv_fragment_manager_t * manager);
191 
192 /**
193  * Attach fragment to manager, and add to container.
194  * @param manager Fragment manager instance
195  * @param fragment Fragment instance
196  * @param container Pointer to container object for manager to add objects to
197  */
198 void lv_fragment_manager_add(lv_fragment_manager_t * manager, lv_fragment_t * fragment, lv_obj_t * const * container);
199 
200 /**
201  * Detach and destroy fragment. If fragment is in navigation stack, remove from it.
202  * @param manager Fragment manager instance
203  * @param fragment Fragment instance
204  */
205 void lv_fragment_manager_remove(lv_fragment_manager_t * manager, lv_fragment_t * fragment);
206 
207 /**
208  * Attach fragment to manager and add to navigation stack.
209  * @param manager Fragment manager instance
210  * @param fragment Fragment instance
211  * @param container Pointer to container object for manager to add objects to
212  */
213 void lv_fragment_manager_push(lv_fragment_manager_t * manager, lv_fragment_t * fragment, lv_obj_t * const * container);
214 
215 /**
216  * Remove the top-most fragment for stack
217  * @param manager Fragment manager instance
218  * @return true if there is fragment to pop
219  */
220 bool lv_fragment_manager_pop(lv_fragment_manager_t * manager);
221 
222 /**
223  * Replace fragment. Old item in the stack will be removed.
224  * @param manager Fragment manager instance
225  * @param fragment Fragment instance
226  * @param container Pointer to container object for manager to add objects to
227  */
228 void lv_fragment_manager_replace(lv_fragment_manager_t * manager, lv_fragment_t * fragment,
229                                  lv_obj_t * const * container);
230 
231 /**
232  * Send event to top-most fragment
233  * @param manager Fragment manager instance
234  * @param code User-defined ID of event
235  * @param userdata User-defined data
236  * @return true if fragment returned true
237  */
238 bool lv_fragment_manager_send_event(lv_fragment_manager_t * manager, int code, void * userdata);
239 
240 /**
241  * Get stack size of this fragment manager
242  * @param manager Fragment manager instance
243  * @return Stack size of this fragment manager
244  */
245 size_t lv_fragment_manager_get_stack_size(lv_fragment_manager_t * manager);
246 
247 /**
248  * Get top most fragment instance
249  * @param manager Fragment manager instance
250  * @return Top most fragment instance
251  */
252 lv_fragment_t * lv_fragment_manager_get_top(lv_fragment_manager_t * manager);
253 
254 /**
255  * Find first fragment instance in the container
256  * @param manager Fragment manager instance
257  * @param container Container which target fragment added to
258  * @return First fragment instance in the container
259  */
260 lv_fragment_t * lv_fragment_manager_find_by_container(lv_fragment_manager_t * manager, const lv_obj_t * container);
261 
262 /**
263  * Get parent fragment
264  * @param manager Fragment manager instance
265  * @return Parent fragment instance
266  */
267 lv_fragment_t * lv_fragment_manager_get_parent_fragment(lv_fragment_manager_t * manager);
268 
269 /**
270  * Create a fragment instance.
271  *
272  * @param cls Fragment class. This fragment must return non null object.
273  * @param args Arguments assigned by fragment manager
274  * @return Fragment instance
275  */
276 lv_fragment_t * lv_fragment_create(const lv_fragment_class_t * cls, void * args);
277 
278 /**
279  * Destroy a fragment.
280  * @param fragment Fragment instance.
281  */
282 void lv_fragment_del(lv_fragment_t * fragment);
283 
284 /**
285  * Get associated manager of this fragment
286  * @param fragment Fragment instance
287  * @return Fragment manager instance
288  */
289 lv_fragment_manager_t * lv_fragment_get_manager(lv_fragment_t * fragment);
290 
291 /**
292  * Get container object of this fragment
293  * @param fragment Fragment instance
294  * @return Reference to container object
295  */
296 lv_obj_t * const * lv_fragment_get_container(lv_fragment_t * fragment);
297 
298 /**
299  * Get parent fragment of this fragment
300  * @param fragment Fragment instance
301  * @return Parent fragment
302  */
303 lv_fragment_t * lv_fragment_get_parent(lv_fragment_t * fragment);
304 
305 /**
306  * Create object by fragment.
307  *
308  * @param fragment Fragment instance.
309  * @param container Container of the objects should be created upon.
310  * @return Created object
311  */
312 lv_obj_t * lv_fragment_create_obj(lv_fragment_t * fragment, lv_obj_t * container);
313 
314 /**
315  * Delete created object of a fragment
316  *
317  * @param fragment Fragment instance.
318  */
319 void lv_fragment_del_obj(lv_fragment_t * fragment);
320 
321 /**
322  * Destroy obj in fragment, and recreate them.
323  * @param fragment Fragment instance
324  */
325 void lv_fragment_recreate_obj(lv_fragment_t * fragment);
326 
327 /**********************
328  *      MACROS
329  **********************/
330 
331 #endif /*LV_USE_FRAGMENT*/
332 
333 #ifdef __cplusplus
334 } /*extern "C"*/
335 #endif
336 
337 #endif /*LV_FRAGMENT_H*/
338