Menu#
#
See also
Menus display a list of choices on temporary surfaces.
Menus should be easy to open, close, and interact with
Menu content should be suited to user needs
Menu items should be easy to scan
Usage#
from kivy.lang import Builder
from kivy.metrics import dp
from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu
KV = '''
MDScreen:
MDRaisedButton:
id: button
text: "Press me"
pos_hint: {"center_x": .5, "center_y": .5}
on_release: app.menu_open()
'''
class Test(MDApp):
def menu_open(self):
menu_items = [
{
"text": f"Item {i}",
"on_release": lambda x=f"Item {i}": self.menu_callback(x),
} for i in range(5)
]
MDDropdownMenu(
caller=self.root.ids.button, items=menu_items
).open()
def menu_callback(self, text_item):
print(text_item)
def build(self):
self.theme_cls.primary_palette = "Orange"
self.theme_cls.theme_style = "Dark"
return Builder.load_string(KV)
Test().run()
Anatomy#
You can combine the following parameters:#
leading_icon
text
trailing_icon
trailing_text
…to create the necessary types of menu items:
menu_items = [
{
"text": "Strikethrough",
"leading_icon": "check",
"trailing_icon": "apple-keyboard-command",
"trailing_text": "+Shift+X",
}
]
menu_items = [
{
"text": "Strikethrough",
"trailing_icon": "apple-keyboard-command",
"trailing_text": "+Shift+X",
}
]
menu_items = [
{
"text": "Strikethrough",
"trailing_icon": "apple-keyboard-command",
}
]
menu_items = [
{
"text": "Strikethrough",
"trailing_text": "Shift+X",
}
]
menu_items = [
{
"text": "Strikethrough",
"leading_icon": "check",
"trailing_icon": "apple-keyboard-command",
}
]
menu_items = [
{
"text": "Strikethrough",
"leading_icon": "check",
}
]
menu_items = [
{
"text": "Strikethrough",
"leading_icon": "check",
"trailing_text": "Shift+X",
}
]
menu_items = [
{
"text": "Strikethrough",
}
]
You can use the following parameters to customize the menu items:#
text_color
leading_icon_color
trailing_icon_color
trailing_text_color
menu_items = [
{
"text": "Strikethrough",
"leading_icon": "check",
"trailing_icon": "apple-keyboard-command",
"trailing_text": "+Shift+X",
"leading_icon_color": "orange",
"trailing_icon_color": "green",
"trailing_text_color": "red",
}
]
Header#
from kivy.lang import Builder
from kivy.metrics import dp
from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu
from kivymd.uix.boxlayout import MDBoxLayout
KV = '''
<MenuHeader>
spacing: "12dp"
padding: "4dp"
adaptive_height: True
MDIconButton:
icon: "gesture-tap-button"
pos_hint: {"center_y": .5}
MDLabel:
text: "Actions"
adaptive_size: True
pos_hint: {"center_y": .5}
MDScreen:
MDRaisedButton:
id: button
text: "PRESS ME"
pos_hint: {"center_x": .5, "center_y": .5}
on_release: app.menu.open()
'''
class MenuHeader(MDBoxLayout):
'''An instance of the class that will be added to the menu header.'''
class Test(MDApp):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.screen = Builder.load_string(KV)
menu_items = [
{
"text": f"Item {i}",
"on_release": lambda x=f"Item {i}": self.menu_callback(x),
} for i in range(5)
]
self.menu = MDDropdownMenu(
header_cls=MenuHeader(),
caller=self.screen.ids.button,
items=menu_items,
)
def menu_callback(self, text_item):
print(text_item)
def build(self):
self.theme_cls.primary_palette = "Orange"
self.theme_cls.theme_style = "Dark"
return self.screen
Test().run()
Menu with MDTopAppBar#
The MDDropdownMenu
works well with the standard
MDTopAppBar
. Since the buttons on the Toolbar are created
by the MDTopAppBar component, it is necessary to pass the button as an argument to
the callback using lambda x: app.callback(x). This example uses drop down menus
for both the righthand and lefthand menus.
from kivy.lang import Builder
from kivy.metrics import dp
from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu
from kivymd.uix.snackbar import Snackbar
KV = '''
MDBoxLayout:
orientation: "vertical"
MDTopAppBar:
title: "MDTopAppBar"
left_action_items: [["menu", lambda x: app.callback(x)]]
right_action_items: [["dots-vertical", lambda x: app.callback(x)]]
MDLabel:
text: "Content"
halign: "center"
'''
class Test(MDApp):
def build(self):
self.theme_cls.primary_palette = "Orange"
self.theme_cls.theme_style = "Dark"
menu_items = [
{
"text": f"Item {i}",
"on_release": lambda x=f"Item {i}": self.menu_callback(x),
} for i in range(5)
]
self.menu = MDDropdownMenu(items=menu_items)
return Builder.load_string(KV)
def callback(self, button):
self.menu.caller = button
self.menu.open()
def menu_callback(self, text_item):
self.menu.dismiss()
Snackbar(text=text_item).open()
Test().run()
Position#
Bottom position#
See also
from kivy.lang import Builder
from kivy.metrics import dp
from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu
KV = '''
MDScreen:
MDTextField:
id: field
pos_hint: {'center_x': .5, 'center_y': .6}
size_hint_x: None
width: "200dp"
hint_text: "Password"
on_focus: if self.focus: app.menu.open()
'''
class Test(MDApp):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.screen = Builder.load_string(KV)
menu_items = [
{
"text": f"Item {i}",
"on_release": lambda x=f"Item {i}": self.set_item(x),
} for i in range(5)]
self.menu = MDDropdownMenu(
caller=self.screen.ids.field,
items=menu_items,
position="bottom",
)
def set_item(self, text_item):
self.screen.ids.field.text = text_item
self.menu.dismiss()
def build(self):
self.theme_cls.primary_palette = "Orange"
self.theme_cls.theme_style = "Dark"
return self.screen
Test().run()
Center position#
from kivy.lang import Builder
from kivymd.uix.menu import MDDropdownMenu
from kivymd.app import MDApp
KV = '''
MDScreen
md_bg_color: self.theme_cls.backgroundColor
MDDropDownItem:
pos_hint: {"center_x": .5, "center_y": .5}
on_release: app.open_drop_item_menu(self)
MDDropDownItemText:
id: drop_text
text: "Item"
'''
class Example(MDApp, CommonApp):
drop_item_menu: MDDropdownMenu = None
def open_drop_item_menu(self, item):
menu_items = [
{
"text": f"{i}",
"on_release": lambda x=f"Item {i}": self.menu_callback(x),
} for i in range(5)
]
if not self.drop_item_menu:
self.drop_item_menu = MDDropdownMenu(
caller=item, items=menu_items, position="center"
)
self.drop_item_menu.open()
def menu_callback(self, text_item):
self.root.ids.drop_text.text = text_item
self.drop_item_menu.dismiss()
def build(self):
return Builder.load_string(KV)
Example().run()
API break#
1.1.1 version#
from kivy.lang import Builder
from kivy.metrics import dp
from kivy.properties import StringProperty
from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.list import IRightBodyTouch, OneLineAvatarIconListItem
from kivymd.uix.menu import MDDropdownMenu
KV = '''
<RightContentCls>
disabled: True
adaptive_size: True
pos_hint: {"center_y": .5}
MDIconButton:
icon: root.icon
icon_size: "16sp"
md_bg_color_disabled: 0, 0, 0, 0
MDLabel:
text: root.text
font_style: "Caption"
adaptive_size: True
pos_hint: {"center_y": .5}
<Item>
IconLeftWidget:
icon: root.left_icon
RightContentCls:
id: container
icon: root.right_icon
text: root.right_text
MDScreen:
MDRaisedButton:
id: button
text: "PRESS ME"
pos_hint: {"center_x": .5, "center_y": .5}
on_release: app.menu.open()
'''
class RightContentCls(IRightBodyTouch, MDBoxLayout):
icon = StringProperty()
text = StringProperty()
class Item(OneLineAvatarIconListItem):
left_icon = StringProperty()
right_icon = StringProperty()
right_text = StringProperty()
class Test(MDApp):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.screen = Builder.load_string(KV)
menu_items = [
{
"text": f"Item {i}",
"right_text": "+Shift+X",
"right_icon": "apple-keyboard-command",
"left_icon": "web",
"viewclass": "Item",
"height": dp(54),
"on_release": lambda x=f"Item {i}": self.menu_callback(x),
} for i in range(5)
]
self.menu = MDDropdownMenu(
caller=self.screen.ids.button,
items=menu_items,
bg_color="#bdc6b0",
width_mult=4,
)
def menu_callback(self, text_item):
print(text_item)
def build(self):
return self.screen
Test().run()
1.2.0 version#
from kivy.lang import Builder
from kivy.metrics import dp
from kivymd.app import MDApp
from kivymd.uix.menu import MDDropdownMenu
KV = '''
MDScreen:
MDRaisedButton:
id: button
text: "PRESS ME"
pos_hint: {"center_x": .5, "center_y": .5}
on_release: app.menu.open()
'''
class Test(MDApp):
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.screen = Builder.load_string(KV)
menu_items = [
{
"text": f"Item {i}",
"leading_icon": "web",
"trailing_icon": "apple-keyboard-command",
"trailing_text": "+Shift+X",
"trailing_icon_color": "grey",
"trailing_text_color": "grey",
"on_release": lambda x=f"Item {i}": self.menu_callback(x),
} for i in range(5)
]
self.menu = MDDropdownMenu(
md_bg_color="#bdc6b0",
caller=self.screen.ids.button,
items=menu_items,
)
def menu_callback(self, text_item):
print(text_item)
def build(self):
return self.screen
Test().run()
API - kivymd.uix.menu.menu
#
- class kivymd.uix.menu.menu.BaseDropdownItem(**kwargs)#
Base class for menu items.
Added in version 1.2.0.
For more information, see in the
RectangularRippleBehavior
andMDBoxLayout
classes.- text#
The text of the menu item.
text
is aStringProperty
and defaults to ‘’.
- leading_icon#
The leading icon of the menu item.
leading_icon
is aStringProperty
and defaults to ‘’.
- trailing_icon#
The trailing icon of the menu item.
trailing_icon
is aStringProperty
and defaults to ‘’.
- trailing_text#
The trailing text of the menu item.
trailing_text
is aStringProperty
and defaults to ‘’.
- text_color#
The color of the text in (r, g, b, a) or string format for the text of the menu item.
text_color
is aColorProperty
and defaults to None.
- leading_icon_color#
The color of the text in (r, g, b, a) or string format for the leading icon of the menu item.
leading_icon_color
is aColorProperty
and defaults to None.
- trailing_icon_color#
The color of the text in (r, g, b, a) or string format for the trailing icon of the menu item.
leading_icon_color
is aColorProperty
and defaults to None.
- trailing_text_color#
The color of the text in (r, g, b, a) or string format for the trailing text of the menu item.
leading_icon_color
is aColorProperty
and defaults to None.
- divider#
Divider mode. Available options are: ‘Full’, None and default to ‘Full’.
divider
is aOptionProperty
and defaults to ‘Full’.
- divider_color#
Divider color in (r, g, b, a) or string format.
divider_color
is aColorProperty
and defaults to None.
- class kivymd.uix.menu.menu.MDDropdownTextItem(**kwargs)#
Implements a menu item with text without leading and trailing icons.
Added in version 1.2.0.
For more information, see in the
BaseDropdownItem
class.
- class kivymd.uix.menu.menu.MDDropdownLeadingIconItem(**kwargs)#
Implements a menu item with text, leading icon and without trailing icon.
Added in version 1.2.0.
For more information, see in the
BaseDropdownItem
class.
- class kivymd.uix.menu.menu.MDDropdownTrailingIconItem(**kwargs)#
Implements a menu item with text, without leading icon and with trailing icon.
Added in version 1.2.0.
For more information, see in the
BaseDropdownItem
class.
- class kivymd.uix.menu.menu.MDDropdownTrailingIconTextItem(**kwargs)#
Implements a menu item with text, without leading icon, with trailing icon and with trailing text.
Added in version 1.2.0.
For more information, see in the
BaseDropdownItem
class.
- class kivymd.uix.menu.menu.MDDropdownTrailingTextItem(**kwargs)#
Implements a menu item with text, without leading icon, without trailing icon and with trailing text.
Added in version 1.2.0.
For more information, see in the
BaseDropdownItem
class.
- class kivymd.uix.menu.menu.MDDropdownLeadingIconTrailingTextItem(**kwargs)#
Implements a menu item with text, leading icon and with trailing text.
Added in version 1.2.0.
For more information, see in the
BaseDropdownItem
class.
- class kivymd.uix.menu.menu.MDDropdownLeadingTrailingIconTextItem(**kwargs)#
Implements a menu item with text, with leading icon, with trailing icon and with trailing text.
Added in version 1.2.0.
For more information, see in the
BaseDropdownItem
class.
- class kivymd.uix.menu.menu.MDDropdownMenu(**kwargs)#
Dropdown menu class.
For more information, see in the
MotionDropDownMenuBehavior
andStencilBehavior
andMDCard
classes documentation.- Events:
- on_release
The method that will be called when you click menu items.
- header_cls#
An instance of the class (Kivy or KivyMD widget) that will be added to the menu header.
Added in version 0.104.2.
See Header for more information.
header_cls
is aObjectProperty
and defaults to None.
- items#
List of dictionaries with properties for menu items.
items
is aListProperty
and defaults to [].
- width_mult#
This number multiplied by the standard increment (‘56dp’ on mobile, ‘64dp’ on desktop), determines the width of the menu items.
If the resulting number were to be too big for the application Window, the multiplier will be adjusted for the biggest possible one.
Deprecated since version 1.2.0: Use width instead.
self.menu = MDDropdownMenu( width=dp(240), ..., )
width_mult
is aNumericProperty
and defaults to 1.
- min_height#
- max_height#
The menu will grow no bigger than this number. Set to 0 for no limit.
max_height
is aNumericProperty
and defaults to 0.
- border_margin#
Margin between Window border and menu.
self.menu = MDDropdownMenu( border_margin=dp(24), ..., )
border_margin
is aNumericProperty
and defaults to 4dp.
- ver_growth#
Where the menu will grow vertically to when opening. Set to None to let the widget pick for you. Available options are: ‘up’, ‘down’.
self.menu = MDDropdownMenu( ver_growth="up", ..., )
self.menu = MDDropdownMenu( ver_growth="down", ..., )
ver_growth
is aOptionProperty
and defaults to None.
- hor_growth#
Where the menu will grow horizontally to when opening. Set to None to let the widget pick for you. Available options are: ‘left’, ‘right’.
self.menu = MDDropdownMenu( hor_growth="left", ..., )
self.menu = MDDropdownMenu( hor_growth="right", ..., )
hor_growth
is aOptionProperty
and defaults to None.
- background_color#
Color in (r, g, b, a) or string format of the background of the menu.
Deprecated since version 1.2.0: Use md_bg_color instead.
background_color
is aColorProperty
and defaults to None.
- caller#
The widget object that calls the menu window.
caller
is aObjectProperty
and defaults to None.
- position#
Menu window position relative to parent element. Available options are: ‘auto’, ‘top’, ‘center’, ‘bottom’.
See Position for more information.
position
is aOptionProperty
and defaults to ‘auto’.
- radius#
Menu radius.
radius
is aVariableListProperty
and defaults to ‘[dp(7)]’.
- adjust_width() → None#
Adjust the width of the menu if the width of the menu goes beyond the boundaries of the parent window from starting point.
- check_ver_growth() → None#
Checks whether the height of the lower/upper borders of the menu exceeds the limits borders of the parent window.
- check_hor_growth() → None#
Checks whether the width of the left/right menu borders exceeds the boundaries of the parent window.
- adjust_position() → str#
Return value ‘auto’ for the menu position if the menu position is out of screen.
- on_items(instance, value: list) → None#
The method sets the class that will be used to create the menu item.
- on_header_cls(instance_dropdown_menu, instance_user_menu_header) → None#
Called when a value is set to the
header_cls
parameter.
- on_touch_down(touch)#
Receive a touch down event.
- Parameters:
- touch:
MotionEvent
class Touch received. The touch is in parent coordinates. See
relativelayout
for a discussion on coordinate systems.
- touch:
- Returns:
bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.
- on_touch_move(touch)#
Receive a touch move event. The touch is in parent coordinates.
See
on_touch_down()
for more information.
- on_touch_up(touch)#
Receive a touch up event. The touch is in parent coordinates.
See
on_touch_down()
for more information.