1.. _lv_menu: 2 3============== 4Menu (lv_menu) 5============== 6 7 8Overview 9******** 10 11The Menu Widget can be used to easily create multi-level menus. It 12handles the traversal between Pages automatically. 13 14 15.. _lv_menu_parts_and_styles: 16 17Parts and Styles 18**************** 19 20The Menu Widget is built from the following Widgets: 21 22- Main container: :cpp:type:`lv_menu_main_cont` 23- Main header: :cpp:type:`lv_menu_main_header_cont` 24- Back button: :ref:`lv_button` 25- Back button icon: :ref:`lv_image` 26- Main Page: :cpp:type:`lv_menu_page` 27- Sidebar container: :cpp:type:`lv_menu_sidebar_cont` 28- Sidebar header: :cpp:type:`lv_menu_sidebar_header_cont` 29- Back button: :ref:`lv_button` 30- Back button icon: :ref:`lv_image` 31- Sidebar Page: :cpp:type:`lv_menu_page` 32 33 34.. _lv_menu_usage: 35 36Usage 37***** 38 39Create a Menu 40------------- 41 42:cpp:expr:`lv_menu_create(parent)` creates a new empty Menu. 43 44Header mode 45----------- 46 47The following header modes exist: 48 49- :cpp:enumerator:`LV_MENU_HEADER_TOP_FIXED` Header is positioned at the top. 50- :cpp:enumerator:`LV_MENU_HEADER_TOP_UNFIXED` Header is positioned at the top and can be scrolled out of view. 51- :cpp:enumerator:`LV_MENU_HEADER_BOTTOM_FIXED` Header is positioned at the bottom. 52 53You can set header modes with :cpp:expr:`lv_menu_set_mode_header(menu, LV_MENU_HEADER...)`. 54 55Root back button mode 56--------------------- 57 58The following root back button modes exist: 59 60- :cpp:enumerator:`LV_MENU_ROOT_BACK_BTN_DISABLED` 61- :cpp:enumerator:`LV_MENU_ROOT_BACK_BTN_ENABLED` 62 63You can set root back button modes with 64:cpp:expr:`lv_menu_set_mode_root_back_button(menu, LV_MENU_ROOT_BACK_BTN...)`. 65 66Create a Menu Page 67------------------ 68 69:cpp:expr:`lv_menu_page_create(menu, title)` creates a new empty Menu Page. You 70can add any Widgets to the Page. 71 72Set a Menu Page in the main area 73-------------------------------- 74 75Once a Menu Page has been created, you can set it to the main area with 76:cpp:expr:`lv_menu_set_page(menu, page)`. ``NULL`` to clear main and clear Menu 77history. 78 79Set a Menu Page in the sidebar 80------------------------------ 81 82Once a Menu Page has been created, you can set it to the sidebar with 83:cpp:expr:`lv_menu_set_sidebar_page(menu, page)`. ``NULL`` to clear sidebar. 84 85Linking between Menu Pages 86-------------------------- 87 88If you have, for instance, created a button obj in the main Page. When you 89click the button Widget, you want it to open up a new Page, use 90:cpp:expr:`lv_menu_set_load_page_event(menu, btn, new page)`. 91 92Create a Menu container, section, separator 93------------------------------------------- 94 95The following objects can be created so that it is easier to style the 96Menu: 97 98- :cpp:expr:`lv_menu_cont_create(parent_page)` creates a new empty container. 99- :cpp:expr:`lv_menu_section_create(parent_page)` creates a new empty section. 100- :cpp:expr:`lv_menu_separator_create(parent_page)` creates a separator. 101 102 103 104.. _lv_menu_events: 105 106Events 107****** 108 109- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent when a Page is shown. 110 111 - :cpp:expr:`lv_menu_get_cur_main_page(menu)` returns a pointer to Menu Page 112 that is currently displayed in the main container. 113 - :cpp:expr:`lv_menu_get_cur_sidebar_page(menu)` returns a pointer to Menu 114 Page that is currently displayed in the sidebar container. 115 116- :cpp:enumerator:`LV_EVENT_CLICKED` Sent when a back button in a header from either 117 main or sidebar is clicked. :cpp:enumerator:`LV_OBJ_FLAG_EVENT_BUBBLE` is enabled 118 on the buttons so you can add events to the Menu itself. 119 120 - :cpp:expr:`lv_menu_back_button_is_root(menu, button)` to check if button is root 121 back button. 122 123.. admonition:: Further Reading 124 125 Learn more about :ref:`lv_obj_events` emitted by all Widgets. 126 127 Learn more about :ref:`events`. 128 129 130 131.. _lv_menu_keys: 132 133Keys 134**** 135 136No *Keys* are processed by Menu Widgets. 137 138.. admonition:: Further Reading 139 140 Learn more about :ref:`indev_keys`. 141 142 143 144.. _lv_menu_example: 145 146Example 147******* 148 149.. include:: ../../examples/widgets/menu/index.rst 150 151 152 153.. _lv_menu_api: 154 155API 156*** 157