.. _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:

Example
*******

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



.. _lv_menu_api:

API
***
