diff --git a/docs/details/widgets/menu.rst b/docs/details/widgets/menu.rst index ded4a5622..0c1f5bd8d 100644 --- a/docs/details/widgets/menu.rst +++ b/docs/details/widgets/menu.rst @@ -8,8 +8,9 @@ Menu (lv_menu) Overview ******** -The Menu Widget can be used to easily create multi-level menus. It -handles the traversal between Pages automatically. +The Menu Widget can be used to create multi-level menus that automatically handle +navigation among menu levels, and enable its user to capture page navigation and +click events. .. _lv_menu_parts_and_styles: @@ -31,6 +32,7 @@ The Menu Widget is built from the following Widgets: - Sidebar Page: :cpp:type:`lv_menu_page` + .. _lv_menu_usage: Usage @@ -41,12 +43,25 @@ Create a Menu :cpp:expr:`lv_menu_create(parent)` creates a new empty Menu. +This creates a Menu Widget with this object hierarchy: + + - Menu: :cpp:type:`lv_menu_t` + - Hidden Sub-Page Storage: :cpp:type:`lv_obj_t` + - Main container: :cpp:var:`lv_menu_main_cont_class` + - Main header: :cpp:var:`lv_menu_main_header_cont_class` + - Back button: :ref:`lv_button` + - Back button icon: :ref:`lv_image` + - Main header title: :ref:`lv_label` (default hidden) + +Note that no sidebar is created. You can create one later if you wish. + + Header mode ----------- The following header modes exist: -- :cpp:enumerator:`LV_MENU_HEADER_TOP_FIXED` Header is positioned at the top. +- :cpp:enumerator:`LV_MENU_HEADER_TOP_FIXED` Header is positioned at the top. (default) - :cpp:enumerator:`LV_MENU_HEADER_TOP_UNFIXED` Header is positioned at the top and can be scrolled out of view. - :cpp:enumerator:`LV_MENU_HEADER_BOTTOM_FIXED` Header is positioned at the bottom. @@ -57,7 +72,7 @@ Root back button mode The following root back button modes exist: -- :cpp:enumerator:`LV_MENU_ROOT_BACK_BTN_DISABLED` +- :cpp:enumerator:`LV_MENU_ROOT_BACK_BTN_DISABLED` (default) - :cpp:enumerator:`LV_MENU_ROOT_BACK_BTN_ENABLED` You can set root back button modes with diff --git a/src/widgets/menu/lv_menu.c b/src/widgets/menu/lv_menu.c index bf0a94c06..04f040bdc 100644 --- a/src/widgets/menu/lv_menu.c +++ b/src/widgets/menu/lv_menu.c @@ -113,7 +113,6 @@ static void lv_menu_value_changed_event_cb(lv_event_t * e); /********************** * GLOBAL FUNCTIONS **********************/ -bool lv_menu_item_back_button_is_root(lv_obj_t * menu, lv_obj_t * obj); void lv_menu_clear_history(lv_obj_t * obj); lv_obj_t * lv_menu_create(lv_obj_t * parent) @@ -124,12 +123,12 @@ lv_obj_t * lv_menu_create(lv_obj_t * parent) return obj; } -lv_obj_t * lv_menu_page_create(lv_obj_t * parent, char const * const title) +lv_obj_t * lv_menu_page_create(lv_obj_t * menu, char const * const title) { - LV_ASSERT_OBJ(parent, MY_CLASS); + LV_ASSERT_OBJ(menu, MY_CLASS); LV_LOG_INFO("begin"); - lv_obj_t * obj = lv_obj_class_create_obj(&lv_menu_page_class, parent); + lv_obj_t * obj = lv_obj_class_create_obj(&lv_menu_page_class, menu); lv_obj_class_init_obj(obj); lv_menu_page_t * page = (lv_menu_page_t *)obj; diff --git a/src/widgets/menu/lv_menu.h b/src/widgets/menu/lv_menu.h index 053f121a9..e7bcb7135 100644 --- a/src/widgets/menu/lv_menu.h +++ b/src/widgets/menu/lv_menu.h @@ -60,12 +60,16 @@ LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_menu_main_header_cont_cl lv_obj_t * lv_menu_create(lv_obj_t * parent); /** - * Create a menu page object - * @param parent pointer to menu object + * Create a menu page object. + * + * This call inserts the new page under menu->storage as its parent, which is itself a + * child of the menu, so the resulting object hierarchy is: menu => storage => new_page + * where `storage` is a Base Widget. + * @param menu pointer to menu object. * @param title pointer to text for title in header (NULL to not display title) * @return pointer to the created menu page */ -lv_obj_t * lv_menu_page_create(lv_obj_t * parent, char const * const title); +lv_obj_t * lv_menu_page_create(lv_obj_t * menu, char const * const title); /** * Create a menu cont object