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