Menu (lv_menu)

Multi-level menu widget. Handles navigation between pages automatically and reports page changes and clicks.

Overview

Deprecated

The lv_menu widget is deprecated and kept only for backward compatibility. A menu is page navigation over base widgets — pages built from lv_obj and a back button that swaps the visible page — so build it directly instead. See the lv_example_menu_navigation example for a starting point.

The Menu widget builds multi-level menus. It handles navigation between pages automatically and lets you react to page changes and item clicks.

Styling

A Menu is made of standard building blocks — a main container, an optional sidebar, headers, back buttons, and one or more pages. Each block is a regular widget, so styling follows the same rules as Base Widget, Button, and Image. See Create a Menu below for the full tree.

lv_menu_create(parent) creates a new empty Menu.

This creates a Menu Widget with this object hierarchy:

Menu: lv_menu_t
- Hidden Sub-Page Storage: lv_obj_t
- Main container: lv_menu_main_cont_class
  - Main header: lv_menu_main_header_cont_class
    - Back button: Button (lv_button)
      - Back button icon: Image (lv_image)
    - Main header title: Label (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:

LV_MENU_HEADER_TOP_FIXED Header is positioned at the top. (default)
LV_MENU_HEADER_TOP_UNFIXED Header is positioned at the top and can be scrolled out of view.
LV_MENU_HEADER_BOTTOM_FIXED Header is positioned at the bottom.

You can set header modes with lv_menu_set_mode_header(menu, LV_MENU_HEADER...).

Root back button mode

The following root back button modes exist:

LV_MENU_ROOT_BACK_BTN_DISABLED (default)
LV_MENU_ROOT_BACK_BTN_ENABLED

You can set root back button modes with lv_menu_set_mode_root_back_button(menu, LV_MENU_ROOT_BACK_BTN...).

lv_menu_page_create(menu, title) creates a new empty Menu Page. You can add any Widgets to the Page.

Once a Menu Page has been created, you can set it to the main area with lv_menu_set_page(menu, page). NULL to clear main and clear Menu history.

Once a Menu Page has been created, you can set it to the sidebar with lv_menu_set_sidebar_page(menu, page). NULL to clear sidebar.

If you have, for instance, created a button obj in the main Page. When you click the button Widget, you want it to open up a new Page, use lv_menu_set_load_page_event(menu, btn, new page).

The following objects can be created so that it is easier to style the Menu:

lv_menu_cont_create(parent_page) creates a new empty container.
lv_menu_section_create(parent_page) creates a new empty section.
lv_menu_separator_create(parent_page) creates a separator.

Events

LV_EVENT_VALUE_CHANGED Sent when a Page is shown.
- lv_menu_get_cur_main_page(menu) returns a pointer to Menu Page that is currently displayed in the main container.
- lv_menu_get_cur_sidebar_page(menu) returns a pointer to Menu Page that is currently displayed in the sidebar container.
LV_EVENT_CLICKED Sent when a back button in a header from either main or sidebar is clicked. LV_OBJ_FLAG_EVENT_BUBBLE is enabled on the buttons so you can add events to the Menu itself.
- lv_menu_back_button_is_root(menu, button) to check if button is root back button.

Learn more about Events emitted by all Widgets.

lv_example_menu_navigation.c

Since lv_menu is deprecated, this example shows the recommended approach: pages are lv_obj containers stacked in a content area, only one shown at a time by toggling LV_OBJ_FLAG_HIDDEN. A header back button returns to the root page. The small menu_* helpers mirror the parts of the old API you actually need.