Widget ID

Widgets can optionally have identifiers added to their functionality if needed for the application. Exactly how that happens is designed to be flexible, and can morph with the needs of the applicat...

Widgets can optionally have identifiers added to their functionality if needed for the application. Exactly how that happens is designed to be flexible, and can morph with the needs of the application. It can even be a timestamp or other data current at the time the Widget was created.

Usage

Enable Widget ID functionality by setting LV_USE_OBJ_ID to 1 in lv_conf.h.

Once enabled, several things change:

• each Widget will now have a void * field called id;

• these two API functions become available:

  • lv_obj_get_id(widget),
  • lv_obj_find_by_id(widget, id);

• several more Widget-ID-related API functions become available if LV_USE_OBJ_ID_BUILTIN is non-zero (more on this below);

• two additional configuration macros both LV_OBJ_ID_AUTO_ASSIGN and LV_USE_OBJ_ID_BUILTIN now have meaning.

LV_OBJ_ID_AUTO_ASSIGN

This macro in lv_conf.h defaults to whatever value LV_USE_OBJ_ID equates to. You can change this if you wish. Either way, if it equates to a non-zero value, it causes two things to happen:

• lv_obj_assign_id(class_p, widget) will be called at the end of each Widget's creation, and
• lv_obj_free_id(widget) will be called at the end of the sequence when each Widget is deleted.

Because of this timing, custom versions of these functions can be used according to the below, and they can even be used like "event hooks" to implement a trace operation that occurs when each Widget is created and deleted.

lv_obj_assign_id(class_p, widget)

This function (whether provided by LVGL or by you --- more on this below) is responsible for assigning a value to the Widget's id field, and possibly do other things, depending on the implementation.

lv_obj_free_id(widget)

This function (whether provided by LVGL or by you --- more on this below) is responsible for doing the clean-up of any resources allocated by

LV_USE_OBJ_ID_BUILTIN

This macro in lv_conf.h equates to 1 by default. You can change this if you wish. When it equates to a non-zero value the following function implementations are provided by LVGL:

• lv_obj_assign_id(class_p, widget)
• lv_obj_free_id(widget)
• lv_obj_set_id(widget, id)
• lv_obj_stringify_id(widget, buf, len)
• lv_obj_id_compare(id1, id2)

These supply the default implementation for Widget IDs, namely that for each Widget created, lv_obj_stringify_id(widget, buf, len) will produce a unique string for it. Example: if the following 6 Widgets are created in this sequence:

• Screen
• Label
• Button
• Label
• Label
• Image

the strings produced by lv_obj_stringify_id(widget, buf, len) would be

• obj1
• label1
• btn1
• label2
• label3
• image1

respectively.

Using a custom ID generator

If you wish, you can provide custom implementations for several Widget-ID related functions. You do this by first setting LV_USE_OBJ_ID_BUILTIN to 0 in lv_conf.h.

You will then need to provide implementations for the following functions (and link them with LVGL):

const char * lv_obj_stringify_id(lv_obj_t * widget, char * buf, uint32_t len);
int          lv_obj_id_compare(const void * id1, const void * id2);

If LV_OBJ_ID_AUTO_ASSIGN equates to a non-zero value (or if you otherwise simply need to use them), you will also need to provide implementations for:

void         lv_obj_assign_id(const lv_obj_class_t * class_p, lv_obj_t * widget);
void         lv_obj_free_id(lv_obj_t * widget);

If LV_BUILD_TEST equates to a non-zero value and you are including LVGL test code in your compile (or if you otherwise simply need to use them), you will also need to provide an implementation for:

void         lv_obj_set_id(lv_obj_t * widget, void * id);

Examples of implementations of these functions exist in lv_obj_id_builtin.c, but you are free to use a different design if needed.

lv_obj_stringify_id converts the passed widget to a string representation (typically incorporating the id field) and writes it into the buffer provided in its buf argument.

lv_obj_id_compare compares 2 void * id values and returns 0 when they are considered equal, and non-zero otherwise.

If LV_OBJ_ID_AUTO_ASSIGN equates to a non-zero value, lv_obj_assign_id is called when a Widget is created. It is responsible for assigning a value to the Widget's id field. A pointer to the Widget's final class is passed in its class_p argument in case it is needed for determining the value for the id field, or for other possible needs related to your design for Widget IDs. Note that this pointer may be different than widget->class_p which is the class of the Widget currently being created.

If LV_OBJ_ID_AUTO_ASSIGN equates to a non-zero value, lv_obj_free_id is called when a Widget is deleted. It needs to perform the clean-up for any resources allocated by lv_obj_assign_id.

Dumping a Widget Tree

Regardless of the state of any of the above macros, the function lv_obj_dump_tree(widget) provides a "dump" of the Widget Tree for the specified Widget (that Widget plus all its children recursively) using the currently-configured method used by the LV_LOG_USER macro. If NULL is passed instead of a pointer to a "root" Widget, the dump will include the Widget Tree for all Screens, for all Displays in the system.

For LV_LOG_USER to produce output, the following needs to be true in lv_conf.h:

• LV_USE_LOG must equate to a non-zero value
• LV_LOG_LEVEL <= LV_LOG_LEVEL_USER

It will recursively walk through all that Widget's children (starting with the Widget itself) and print the Widget's parent's address, the Widget's address, and if LV_USE_OBJ_ID equates to a non-zero value, will also print the output of lv_obj_stringify_id for that Widget.

This can be useful in the event of a UI crash. From that log you can examine the state of the Widget Tree when lv_obj_dump_tree(widget) was called.

For example, if a pointer to a deleted Widget is stored in a Timer's timer->user_data field when the timer event callback is called, attempted use of that pointer will likely cause a crash because the pointer is not valid any more. However, a timely dump of the Widget Tree right before that point will show that the Widget no longer exists.

Find child by ID

lv_obj_find_by_id(widget, id) will perform a recursive walk through widget's children and return the first child encountered having the given ID.