feat(fragment): add fragment manager (a UI Controller concept) (#2940)

* adding lv_obj_controller * adding examples for lv_obj_controller * added some docs * formatted code * updated controller docs * updated controller docs * updated sample controller field * changed lv_controller_manager_parent to lv_controller_manager_get_parent * updated unmanaged controller creation/deletion * renamed lv_controller_manager_t * rename: controller -> fragment * formatted code * Update examples/others/fragment/lv_example_fragment.h Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com> * Update src/extra/others/fragment/lv_fragment.c Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com> * Update src/extra/others/fragment/lv_fragment.c Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com> * Update src/extra/others/fragment/lv_fragment.c Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com> * code cleanup * fragment creation rework * (wip) fragment manager * (wip) fragment manager * refactoring fragment * lifecycle fixes * updated fragment event callback * exposed states of fragment * added some docs * updated lv_fragment_managed_states_t name * updated docs * updated docs * updated lv_fragment_manager_dispatch_event docs * removed msgbox fragment * updated fragment docs * updated fragment docs * updated docs * updating examples * fixed example * reformatted code * fixed obj_created set timing * simplified fragment * improved fragment view del assertion * fixed a typo * fixed event_cb check in lv_obj_remove_event_cb_with_user_data * fixing fragment obj assertion * regenerated config * fixed fragment examples * fixed fragment examples * added missing examples * updated docs * fragment api cleanup * rename fragment struct names * added missing param doc * enabled test for 32bit build * feat(porting): add a macro lv_run_timer_handler_in_period to simplify porting (#3063) * feat(porting): add a macro lv_run_timer_handler_in_period to simplify porting * feat: update helper function and doc * doc(porting): update function names * revise to the original os.md * fix: fix typo * fix: mitigate warnings * chore: fix code formatting * fix(fsdrv): replacing sprintf with lv_snprintf for safety (#3079) * fix(Kconfig) remove duplicate LV_BUILD_EXAMPLES configuration * feat(refr) add reset of FPS statistics * fix(conf) mismatched macro judgment * feat(fsdrv) replacing sprintf with lv_snprintf for safety * feat(fsdrv) update stdio and win32 Co-authored-by: pengyiqiang <pengyiqiang@xiaomi.com> * fix warnings Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com> Co-authored-by: Gabriel Wang <embedded_zhuoran@Hotmail.com> Co-authored-by: _VIFEXTech <1290176185@qq.com> Co-authored-by: pengyiqiang <pengyiqiang@xiaomi.com>
2022-02-11 20:43:08 +09:00
parent 9f90d82e91
commit e7736f2c32
17 changed files with 1066 additions and 3 deletions
--- a/docs/others/fragment.md
+++ b/docs/others/fragment.md
@@ -0,0 +1,81 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/others/fragment.md
+```
+
+# Fragment
+
+Fragment is a concept copied from [Android](https://developer.android.com/guide/fragments).
+
+It represents a reusable portion of your app's UI. A fragment defines and manages its own layout, has its own lifecycle,
+and can handle its own events. Like Android's Fragment that must be hosted by an activity or another fragment, Fragment
+in LVGL needs to be hosted by an object, or another fragment. The fragment’s view hierarchy becomes part of, or attaches
+to, the host’s view hierarchy.
+
+Such concept also has some similarities
+to [UiViewController on iOS](https://developer.apple.com/documentation/uikit/uiviewcontroller).
+
+Fragment Manager is a manager holding references to fragments attached to it, and has an internal stack to achieve 
+navigation. You can use fragment manager to build navigation stack, or multi pane application easily.
+
+## Usage
+
+Enable `LV_USE_FRAGMENT` in `lv_conf.h`.
+
+### Create Fragment Class
+
+```c
+struct sample_fragment_t {
+    /* IMPORTANT: don't miss this part */
+    lv_fragment_t base;
+    /* States, object references and data fields for this fragment */
+    const char *title;
+};
+
+const lv_fragment_class_t sample_cls = {
+        /* Initialize something needed */
+        .constructor_cb = sample_fragment_ctor,
+        /* Create view objects */
+        .create_obj_cb = sample_fragment_create_obj,
+        /* IMPORTANT: size of your fragment struct */
+        .instance_size = sizeof(struct sample_fragment_t)
+};
+```
+
+### Use `lv_fragment_manager`
+
+```c
+/* Create fragment instance, and objects will be added to container */
+lv_fragment_manager_t *manager = lv_fragment_manager_create(container, NULL);
+/* Replace current fragment with instance of sample_cls, and init_argument is user defined pointer */
+lv_fragment_manager_replace(manager, &sample_cls, init_argument);
+```
+
+### Fragment Based Navigation
+
+```c
+/* Add one instance into manager stack. View object of current fragment will be destroyed,
+ * but instances created in class constructor will be kept.
+ */
+lv_fragment_manager_push(manager, &sample_cls, NULL);
+
+/* Remove the top most fragment from the stack, and bring back previous one. */
+lv_fragment_manager_pop(manager);
+```
+
+## Example
+
+```eval_rst
+
+.. include:: ../../examples/others/fragment/index.rst
+
+```
+
+## API
+
+```eval_rst
+
+.. doxygenfile:: lv_fragment.h
+  :project: lvgl
+
+```
--- a/docs/others/index.md
+++ b/docs/others/index.md
@@ -13,5 +13,6 @@
   snapshot
   monkey
   gridnav
+   fragment
 ```