.. _lv_menu:

============== Menu (lv_menu)

Overview

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:

Parts and Styles

The Menu Widget is built from the following Widgets:

• Main container: :cpp:type:lv_menu_main_cont
• Main header: :cpp:type:lv_menu_main_header_cont
• Back button: :ref:lv_button
• Back button icon: :ref:lv_image
• Main Page: :cpp:type:lv_menu_page
• Sidebar container: :cpp:type:lv_menu_sidebar_cont
• Sidebar header: :cpp:type:lv_menu_sidebar_header_cont
• Back button: :ref:lv_button
• Back button icon: :ref:lv_image
• Sidebar Page: :cpp:type:lv_menu_page

.. _lv_menu_usage:

Usage

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. (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.

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

Root back button mode

The following root back button modes exist:

• :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 :cpp:expr:lv_menu_set_mode_root_back_button(menu, LV_MENU_ROOT_BACK_BTN...).

Create a Menu Page

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

Set a Menu Page in the main area

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

Set a Menu Page in the sidebar

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

Linking between Menu Pages

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 :cpp:expr:lv_menu_set_load_page_event(menu, btn, new page).

Create a Menu container, section, separator

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

• :cpp:expr:lv_menu_cont_create(parent_page) creates a new empty container.
• :cpp:expr:lv_menu_section_create(parent_page) creates a new empty section.
• :cpp:expr:lv_menu_separator_create(parent_page) creates a separator.

.. _lv_menu_events:

Events

• :cpp:enumerator:LV_EVENT_VALUE_CHANGED Sent when a Page is shown.

  • :cpp:expr:lv_menu_get_cur_main_page(menu) returns a pointer to Menu Page that is currently displayed in the main container.
  • :cpp:expr:lv_menu_get_cur_sidebar_page(menu) returns a pointer to Menu Page that is currently displayed in the sidebar container.

• :cpp:enumerator:LV_EVENT_CLICKED Sent when a back button in a header from either main or sidebar is clicked. :cpp:enumerator:LV_OBJ_FLAG_EVENT_BUBBLE is enabled on the buttons so you can add events to the Menu itself.

  • :cpp:expr:lv_menu_back_button_is_root(menu, button) to check if button is root back button.

.. admonition:: Further Reading

Learn more about :ref:`lv_obj_events` emitted by all Widgets.

Learn more about :ref:`events`.

.. _lv_menu_keys:

Keys

No Keys are processed by Menu Widgets.

.. admonition:: Further Reading

Learn more about :ref:`indev_keys`.

.. _lv_menu_example:

Examples

.. include:: /examples/widgets/menu/index.rst

.. _lv_menu_api:

API