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