1.. _fragment:
2
3========
4Fragment
5========
6
7Fragment is a concept copied from
8`Android <https://developer.android.com/guide/fragments>`__.
9
10It represents a reusable portion of your app's UI. A fragment defines
11and manages its own layout, has its own lifecycle, and can handle its
12own events. Like Android's Fragment that must be hosted by an activity
13or another fragment, Fragment in LVGL needs to be hosted by a Widget,
14or another fragment. The fragment's view hierarchy becomes part of, or
15attaches to, the host's view hierarchy.
16
17Such concept also has some similarities to `UiViewController on
18iOS <https://developer.apple.com/documentation/uikit/uiviewcontroller>`__.
19
20Fragment Manager is a manager holding references to fragments attached
21to it, and has an internal stack to achieve forward and backwards navigation. You can use
22fragment manager to build a navigation stack, or a multi-pane application
23easily.
24
25
26
27.. _fragment_usage:
28
29Usage
30*****
31
32Enable :c:macro:`LV_USE_FRAGMENT` in ``lv_conf.h``.
33
34Create Fragment Class
35---------------------
36
37.. code-block:: c
38
39   struct sample_fragment_t {
40       /* IMPORTANT: don't miss this part */
41       lv_fragment_t base;
42       /* States, object references and data fields for this fragment */
43       const char *title;
44   };
45
46   const lv_fragment_class_t sample_cls = {
47           /* Initialize something needed */
48           .constructor_cb = sample_fragment_ctor,
49           /* Create view objects */
50           .create_obj_cb = sample_fragment_create_obj,
51           /* IMPORTANT: size of your fragment struct */
52           .instance_size = sizeof(struct sample_fragment_t),
53   };
54
55Use ``lv_fragment_manager``
56---------------------------
57
58.. code-block:: c
59
60   /* Create fragment instance, and Widgets will be added to container */
61   lv_fragment_manager_t *manager = lv_fragment_manager_create(container, NULL);
62   /* Replace current fragment with instance of sample_cls, and init_argument is user defined pointer */
63   lv_fragment_manager_replace(manager, &sample_cls, init_argument);
64
65Fragment Based Navigation
66-------------------------
67
68.. code-block:: c
69
70   /* Add one instance into manager stack. View object of current fragment will be destroyed,
71    * but instances created in class constructor will be kept.
72    */
73   lv_fragment_manager_push(manager, &sample_cls, NULL);
74
75   /* Remove the top most fragment from the stack, and bring back previous one. */
76   lv_fragment_manager_pop(manager);
77
78
79
80.. _fragment_example:
81
82Example
83*******
84
85.. include:: ../../examples/others/fragment/index.rst
86
87
88
89.. _fragment_api:
90
91API
92***
93