Fragment¶
Fragment is a concept copied from Android.
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.
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¶
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
¶
/* 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);
Example¶
Basic fragment usage¶
C code
GitHub/**
* @file lv_example_fragment_1.c
* @brief Basic usage of obj fragment
*/
#include "../../lv_examples.h"
#if LV_USE_FRAGMENT && LV_BUILD_EXAMPLES
static void sample_fragment_ctor(lv_fragment_t * self, void * args);
static lv_obj_t * sample_fragment_create_obj(lv_fragment_t * self, lv_obj_t * parent);
static void sample_container_del(lv_event_t * e);
static lv_obj_t * root = NULL;
struct sample_fragment_t {
lv_fragment_t base;
const char * name;
};
static const lv_fragment_class_t sample_cls = {
.constructor_cb = sample_fragment_ctor,
.create_obj_cb = sample_fragment_create_obj,
.instance_size = sizeof(struct sample_fragment_t)
};
void lv_example_fragment_1(void)
{
root = lv_obj_create(lv_scr_act());
lv_obj_set_size(root, LV_PCT(100), LV_PCT(100));
lv_fragment_manager_t * manager = lv_fragment_manager_create(NULL);
/* Clean up the fragment manager before objects in containers got deleted */
lv_obj_add_event_cb(root, sample_container_del, LV_EVENT_DELETE, manager);
lv_fragment_t * fragment = lv_fragment_create(&sample_cls, "Fragment");
lv_fragment_manager_replace(manager, fragment, &root);
}
static void sample_fragment_ctor(lv_fragment_t * self, void * args)
{
((struct sample_fragment_t *) self)->name = args;
}
static lv_obj_t * sample_fragment_create_obj(lv_fragment_t * self, lv_obj_t * parent)
{
lv_obj_t * label = lv_label_create(parent);
lv_obj_set_style_bg_opa(label, LV_OPA_COVER, 0);;
lv_label_set_text_fmt(label, "Hello, %s!", ((struct sample_fragment_t *) self)->name);
return label;
}
static void sample_container_del(lv_event_t * e)
{
lv_fragment_manager_t * manager = (lv_fragment_manager_t *) lv_event_get_user_data(e);
lv_fragment_manager_del(manager);
}
#endif
Error encountered while trying to open /home/runner/work/100ask_lvgl_docs/100ask_lvgl_docs/examples/others/fragment/lv_example_fragment_1.py
API¶
Public header for Fragment
Typedefs
-
typedef struct _lv_fragment_manager_t lv_fragment_manager_t¶
-
typedef struct _lv_fragment_t lv_fragment_t¶
-
typedef struct _lv_fragment_class_t lv_fragment_class_t¶
-
typedef struct _lv_fragment_managed_states_t lv_fragment_managed_states_t¶
Fragment states
Functions
-
lv_fragment_manager_t *lv_fragment_manager_create(lv_fragment_t *parent)¶
Create fragment manager instance
- Parameters
parent -- Parent fragment if this manager is placed inside another fragment, can be null.
- Returns
Fragment manager instance
-
void lv_fragment_manager_del(lv_fragment_manager_t *manager)¶
Destroy fragment manager instance
- Parameters
manager -- Fragment manager instance
-
void lv_fragment_manager_create_obj(lv_fragment_manager_t *manager)¶
Create object of all fragments managed by this manager.
- Parameters
manager -- Fragment manager instance
-
void lv_fragment_manager_del_obj(lv_fragment_manager_t *manager)¶
Delete object created by all fragments managed by this manager. Instance of fragments will not be deleted.
- Parameters
manager -- Fragment manager instance
-
void lv_fragment_manager_add(lv_fragment_manager_t *manager, lv_fragment_t *fragment, lv_obj_t *const *container)¶
Attach fragment to manager, and add to container.
- Parameters
manager -- Fragment manager instance
fragment -- Fragment instance
container -- Pointer to container object for manager to add objects to
-
void lv_fragment_manager_remove(lv_fragment_manager_t *manager, lv_fragment_t *fragment)¶
Detach and destroy fragment. If fragment is in navigation stack, remove from it.
- Parameters
manager -- Fragment manager instance
fragment -- Fragment instance
-
void lv_fragment_manager_push(lv_fragment_manager_t *manager, lv_fragment_t *fragment, lv_obj_t *const *container)¶
Attach fragment to manager and add to navigation stack.
- Parameters
manager -- Fragment manager instance
fragment -- Fragment instance
container -- Pointer to container object for manager to add objects to
-
bool lv_fragment_manager_pop(lv_fragment_manager_t *manager)¶
Remove the top-most fragment for stack
- Parameters
manager -- Fragment manager instance
- Returns
true if there is fragment to pop
-
void lv_fragment_manager_replace(lv_fragment_manager_t *manager, lv_fragment_t *fragment, lv_obj_t *const *container)¶
Replace fragment. Old item in the stack will be removed.
- Parameters
manager -- Fragment manager instance
fragment -- Fragment instance
container -- Pointer to container object for manager to add objects to
-
bool lv_fragment_manager_send_event(lv_fragment_manager_t *manager, int code, void *userdata)¶
Send event to top-most fragment
- Parameters
manager -- Fragment manager instance
code -- User-defined ID of event
userdata -- User-defined data
- Returns
true if fragment returned true
-
size_t lv_fragment_manager_get_stack_size(lv_fragment_manager_t *manager)¶
Get stack size of this fragment manager
- Parameters
manager -- Fragment manager instance
- Returns
Stack size of this fragment manager
-
lv_fragment_t *lv_fragment_manager_get_top(lv_fragment_manager_t *manager)¶
Get top most fragment instance
- Parameters
manager -- Fragment manager instance
- Returns
Top most fragment instance
-
lv_fragment_t *lv_fragment_manager_find_by_container(lv_fragment_manager_t *manager, const lv_obj_t *container)¶
Find first fragment instance in the container
- Parameters
manager -- Fragment manager instance
container -- Container which target fragment added to
- Returns
First fragment instance in the container
-
lv_fragment_t *lv_fragment_manager_get_parent_fragment(lv_fragment_manager_t *manager)¶
Get parent fragment
- Parameters
manager -- Fragment manager instance
- Returns
Parent fragment instance
-
lv_fragment_t *lv_fragment_create(const lv_fragment_class_t *cls, void *args)¶
Create a fragment instance.
- Parameters
cls -- Fragment class. This fragment must return non null object.
args -- Arguments assigned by fragment manager
- Returns
Fragment instance
-
void lv_fragment_del(lv_fragment_t *fragment)¶
Destroy a fragment.
- Parameters
fragment -- Fragment instance.
-
lv_fragment_manager_t *lv_fragment_get_manager(lv_fragment_t *fragment)¶
Get associated manager of this fragment
- Parameters
fragment -- Fragment instance
- Returns
Fragment manager instance
-
lv_obj_t *const *lv_fragment_get_container(lv_fragment_t *fragment)¶
Get container object of this fragment
- Parameters
fragment -- Fragment instance
- Returns
Reference to container object
-
lv_fragment_t *lv_fragment_get_parent(lv_fragment_t *fragment)¶
Get parent fragment of this fragment
- Parameters
fragment -- Fragment instance
- Returns
Parent fragment
-
lv_obj_t *lv_fragment_create_obj(lv_fragment_t *fragment, lv_obj_t *container)¶
Create object by fragment.
- Parameters
fragment -- Fragment instance.
container -- Container of the objects should be created upon.
- Returns
Created object
-
void lv_fragment_del_obj(lv_fragment_t *fragment)¶
Delete created object of a fragment
- Parameters
fragment -- Fragment instance.
-
void lv_fragment_recreate_obj(lv_fragment_t *fragment)¶
Destroy obj in fragment, and recreate them.
- Parameters
fragment -- Fragment instance
-
struct _lv_fragment_t¶
Public Members
-
const lv_fragment_class_t *cls¶
Class of this fragment
-
lv_fragment_managed_states_t *managed¶
Managed fragment states. If not null, then this fragment is managed.
Warning
Don't modify values inside this struct!
-
lv_fragment_manager_t *child_manager¶
Child fragment manager
-
const lv_fragment_class_t *cls¶
-
struct _lv_fragment_class_t¶
Public Members
-
void (*constructor_cb)(lv_fragment_t *self, void *args)¶
Constructor function for fragment class
- Param self
Fragment instance
- Param args
Arguments assigned by fragment manager
-
void (*destructor_cb)(lv_fragment_t *self)¶
Destructor function for fragment class
- Param self
Fragment instance, will be freed after this call
-
void (*attached_cb)(lv_fragment_t *self)¶
Fragment attached to manager
- Param self
Fragment instance
-
void (*detached_cb)(lv_fragment_t *self)¶
Fragment detached from manager
- Param self
Fragment instance
-
lv_obj_t *(*create_obj_cb)(lv_fragment_t *self, lv_obj_t *container)¶
Create objects
- Param self
Fragment instance
- Param container
Container of the objects should be created upon
- Return
Created object, NULL if multiple objects has been created
-
void (*obj_created_cb)(lv_fragment_t *self, lv_obj_t *obj)¶
- Param self
Fragment instance
- Param obj
lv_obj returned by create_obj_cb
-
void (*obj_will_delete_cb)(lv_fragment_t *self, lv_obj_t *obj)¶
Called before objects in the fragment will be deleted.
- Param self
Fragment instance
- Param obj
object with this fragment
-
void (*obj_deleted_cb)(lv_fragment_t *self, lv_obj_t *obj)¶
Called when the object created by fragment received
LV_EVENT_DELETE
event- Param self
Fragment instance
- Param obj
object with this fragment
-
bool (*event_cb)(lv_fragment_t *self, int code, void *userdata)¶
Handle event
- Param self
Fragment instance
- Param which
User-defined ID of event
- Param data1
User-defined data
- Param data2
User-defined data
-
size_t instance_size¶
REQUIRED: Allocation size of fragment
-
void (*constructor_cb)(lv_fragment_t *self, void *args)¶
-
struct _lv_fragment_managed_states_t¶
- #include <lv_fragment.h>
Fragment states
Public Members
-
const lv_fragment_class_t *cls¶
Class of the fragment
-
lv_fragment_manager_t *manager¶
Manager the fragment attached to
-
lv_fragment_t *instance¶
Fragment instance
-
bool obj_created¶
true between
create_obj_cb
andobj_deleted_cb
-
bool destroying_obj¶
true before
lv_fragment_del_obj
is called. Don't touch any object if this is true
-
bool in_stack¶
true if this fragment is in navigation stack that can be popped
-
const lv_fragment_class_t *cls¶