NavigationDrawer#
#
See also
Navigation drawers provide access to destinations in your app.
Use navigation drawers in expanded layouts and modal navigation drawers in compact and medium layouts
Can be open or closed by default
Two types: standard and modal
When using the class MDNavigationDrawer
skeleton of your KV markup
should look like this:
Usage#
Root:
MDNavigationLayout:
MDScreenManager:
Screen_1:
Screen_2:
MDNavigationDrawer:
# This custom rule should implement what will be displayed in
# your MDNavigationDrawer.
ContentNavigationDrawer:
A simple example#
from kivy.lang import Builder
from kivymd.app import MDApp
KV = '''
MDScreen:
md_bg_color: self.theme_cls.backgroundColor
MDNavigationLayout:
MDScreenManager:
MDScreen:
MDButton:
pos_hint: {"center_x": .5, "center_y": .5}
on_release: nav_drawer.set_state("toggle")
MDButtonText:
text: "Open Drawer"
MDNavigationDrawer:
id: nav_drawer
radius: 0, dp(16), dp(16), 0
MDNavigationDrawerMenu:
MDNavigationDrawerLabel:
text: "Mail"
MDNavigationDrawerItem:
MDNavigationDrawerItemLeadingIcon:
icon: "account"
MDNavigationDrawerItemText:
text: "Inbox"
MDNavigationDrawerItemTrailingText:
text: "24"
MDNavigationDrawerDivider:
'''
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
Example().run()
from kivy.metrics import dp
from kivymd.uix.button import MDButton, MDButtonText
from kivymd.uix.screenmanager import MDScreenManager
from kivymd.uix.navigationdrawer import (
MDNavigationLayout,
MDNavigationDrawer,
MDNavigationDrawerMenu,
MDNavigationDrawerLabel,
MDNavigationDrawerItem,
MDNavigationDrawerItemLeadingIcon,
MDNavigationDrawerItemText,
MDNavigationDrawerItemTrailingText,
MDNavigationDrawerDivider,
)
from kivymd.uix.screen import MDScreen
from kivymd.app import MDApp
class Example(MDApp):
def build(self):
return MDScreen(
MDNavigationLayout(
MDScreenManager(
MDScreen(
MDButton(
MDButtonText(
text="Open Drawer",
),
on_release=lambda x: self.root.get_ids().nav_drawer.set_state(
"toggle"
),
pos_hint={"center_x": 0.5, "center_y": 0.5},
),
),
),
MDNavigationDrawer(
MDNavigationDrawerMenu(
MDNavigationDrawerLabel(
text="Mail",
),
MDNavigationDrawerItem(
MDNavigationDrawerItemLeadingIcon(
icon="account",
),
MDNavigationDrawerItemText(
text="Inbox",
),
MDNavigationDrawerItemTrailingText(
text="24",
),
),
MDNavigationDrawerDivider(
),
),
id="nav_drawer",
radius=(0, dp(16), dp(16), 0),
),
),
md_bg_color=self.theme_cls.backgroundColor,
)
Example().run()
Anatomy#
Note
MDNavigationDrawer
is an empty
MDCard
panel.
Item anatomy#
MDNavigationDrawerItem:
MDNavigationDrawerItemLeadingIcon:
icon: "account"
MDNavigationDrawerItemText:
text: "Inbox"
MDNavigationDrawerItemTrailingText:
text: "24"
Type drawer#
Standard#
MDNavigationDrawer:
drawer_type: "standard"
Modal#
MDNavigationDrawer:
drawer_type: "modal"
Anchoring screen edge for drawer#
MDNavigationDrawer: anchor: "left"MDNavigationDrawer: anchor: "right"
API break#
1.2.0 version#
from kivy.lang import Builder
from kivymd.app import MDApp
KV = '''
<DrawerClickableItem@MDNavigationDrawerItem>
focus_color: "#e7e4c0"
text_color: "#4a4939"
icon_color: "#4a4939"
ripple_color: "#c5bdd2"
selected_color: "#0c6c4d"
<DrawerLabelItem@MDNavigationDrawerItem>
text_color: "#4a4939"
icon_color: "#4a4939"
focus_behavior: False
selected_color: "#4a4939"
_no_ripple_effect: True
MDScreen:
MDNavigationLayout:
MDScreenManager:
MDScreen:
MDRaisedButton:
text: "Open Drawer"
pos_hint: {"center_x": .5, "center_y": .5}
on_release: nav_drawer.set_state("toggle")
MDNavigationDrawer:
id: nav_drawer
radius: (0, dp(16), dp(16), 0)
MDNavigationDrawerMenu:
MDNavigationDrawerHeader:
title: "Header title"
title_color: "#4a4939"
text: "Header text"
spacing: "4dp"
padding: "12dp", 0, 0, "56dp"
MDNavigationDrawerLabel:
text: "Mail"
DrawerClickableItem:
icon: "gmail"
right_text: "+99"
text_right_color: "#4a4939"
text: "Inbox"
DrawerClickableItem:
icon: "send"
text: "Outbox"
MDNavigationDrawerDivider:
MDNavigationDrawerLabel:
text: "Labels"
DrawerLabelItem:
icon: "information-outline"
text: "Label"
DrawerLabelItem:
icon: "information-outline"
text: "Label"
'''
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
Example().run()
2.2.0 version#
from kivy.lang import Builder
from kivy.properties import StringProperty, ColorProperty
from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.navigationdrawer import (
MDNavigationDrawerItem, MDNavigationDrawerItemTrailingText
)
KV = '''
<DrawerItem>
active_indicator_color: "#e7e4c0"
MDNavigationDrawerItemLeadingIcon:
icon: root.icon
theme_icon_color: "Custom"
icon_color: "#4a4939"
MDNavigationDrawerItemText:
text: root.text
theme_text_color: "Custom"
text_color: "#4a4939"
<DrawerLabel>
adaptive_height: True
padding: "18dp", 0, 0, "12dp"
MDNavigationDrawerItemLeadingIcon:
icon: root.icon
theme_icon_color: "Custom"
icon_color: "#4a4939"
pos_hint: {"center_y": .5}
MDNavigationDrawerLabel:
text: root.text
theme_text_color: "Custom"
text_color: "#4a4939"
pos_hint: {"center_y": .5}
padding: "6dp", 0, "16dp", 0
theme_line_height: "Custom"
line_height: 0
MDScreen:
md_bg_color: self.theme_cls.backgroundColor
MDNavigationLayout:
MDScreenManager:
MDScreen:
MDButton:
pos_hint: {"center_x": .5, "center_y": .5}
on_release: nav_drawer.set_state("toggle")
MDButtonText:
text: "Open Drawer"
MDNavigationDrawer:
id: nav_drawer
radius: 0, dp(16), dp(16), 0
MDNavigationDrawerMenu:
MDNavigationDrawerHeader:
orientation: "vertical"
padding: 0, 0, 0, "12dp"
adaptive_height: True
MDLabel:
text: "Header title"
theme_text_color: "Custom"
theme_line_height: "Custom"
line_height: 0
text_color: "#4a4939"
adaptive_height: True
padding_x: "16dp"
font_style: "Display"
role: "small"
MDLabel:
text: "Header text"
padding_x: "18dp"
adaptive_height: True
font_style: "Title"
role: "large"
MDNavigationDrawerDivider:
DrawerItem:
icon: "gmail"
text: "Inbox"
trailing_text: "+99"
trailing_text_color: "#4a4939"
DrawerItem:
icon: "send"
text: "Outbox"
MDNavigationDrawerDivider:
MDNavigationDrawerLabel:
text: "Labels"
padding_y: "12dp"
DrawerLabel:
icon: "information-outline"
text: "Label"
DrawerLabel:
icon: "information-outline"
text: "Label"
'''
class DrawerLabel(MDBoxLayout):
icon = StringProperty()
text = StringProperty()
class DrawerItem(MDNavigationDrawerItem):
icon = StringProperty()
text = StringProperty()
trailing_text = StringProperty()
trailing_text_color = ColorProperty()
_trailing_text_obj = None
def on_trailing_text(self, instance, value):
self._trailing_text_obj = MDNavigationDrawerItemTrailingText(
text=value,
theme_text_color="Custom",
text_color=self.trailing_text_color,
)
self.add_widget(self._trailing_text_obj)
def on_trailing_text_color(self, instance, value):
self._trailing_text_obj.text_color = value
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
Example().run()
API - kivymd.uix.navigationdrawer.navigationdrawer
#
- class kivymd.uix.navigationdrawer.navigationdrawer.BaseNavigationDrawerItem#
Implement the base class for the menu list item.
New in version 2.0.0.
- selected#
Is the item selected.
selected
is aBooleanProperty
and defaults to False.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationLayout(*args, **kwargs)#
For more information, see in the
DeclarativeBehavior
andFloatLayout
classes documentation.- add_scrim(instance_manager: kivy.uix.screenmanager.ScreenManager) → None#
- update_scrim_rectangle(instance_manager: kivy.uix.screenmanager.ScreenManager, size: list) → None#
- add_widget(widget, index=0, canvas=None)#
Only two layouts are allowed:
ScreenManager
andMDNavigationDrawer
.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerLabel(*args, **kwargs)#
Implements a label class.
For more information, see in the
MDLabel
class documentation.New in version 1.0.0.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerDivider(**kwargs)#
Implements a divider class.
For more information, see in the
BoxLayout
class documentation.New in version 1.0.0.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerHeader(*args, **kwargs)#
Implements a header class.
For more information, see in the
DeclarativeBehavior
andBoxLayout
classes documentation.New in version 1.0.0.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItem(*args, **kwargs)#
Implements an item for the
MDNavigationDrawer
menu list.For more information, see in the
MDListItem
andFocusBehavior
andBaseNavigationDrawerItem
classes documentation.New in version 1.0.0.
- active_indicator_color#
The active indicator color in (r, g, b, a) or string format.
New in version 2.0.0.
active_indicator_color
is aColorProperty
and defaults to None.
- inactive_indicator_color#
The inactive indicator color in (r, g, b, a) or string format.
New in version 2.0.0.
inactive_indicator_color
is aColorProperty
and defaults to None.
- add_widget(widget, *args, **kwargs)#
Add a new widget as a child of this widget.
- Parameters:
- widget:
Widget
Widget to add to our list of children.
- index: int, defaults to 0
Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.
New in version 1.0.5.
- canvas: str, defaults to None
Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.
New in version 1.9.0.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItemLeadingIcon(*args, **kwargs)#
Implements the leading icon for the menu list item.
For more information, see in the
MDListItemLeadingIcon
andBaseNavigationDrawerItem
classes documentation.New in version 2.0.0.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItemText(*args, **kwargs)#
Implements the text for the menu list item.
For more information, see in the
MDListItemSupportingText
andBaseNavigationDrawerItem
classes documentation.New in version 2.0.0.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerItemTrailingText(*args, **kwargs)#
Implements the supporting text for the menu list item.
For more information, see in the
MDListItemTrailingSupportingText
andBaseNavigationDrawerItem
classes documentation.New in version 2.0.0.
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawerMenu(*args, **kwargs)#
Implements a scrollable list for menu items of the
MDNavigationDrawer
class.For more information, see in the
MDScrollView
class documentation.New in version 1.0.0.
MDNavigationDrawer: MDNavigationDrawerMenu: # Your menu items. ...
- spacing#
Spacing between children, in pixels.
spacing
is aNumericProperty
and defaults to 0.
- add_widget(widget, *args, **kwargs)#
Add a new widget as a child of this widget.
- Parameters:
- widget:
Widget
Widget to add to our list of children.
- index: int, defaults to 0
Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.
New in version 1.0.5.
- canvas: str, defaults to None
Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.
New in version 1.9.0.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
- update_items_color(item: MDNavigationDrawerItem) → None#
- class kivymd.uix.navigationdrawer.navigationdrawer.MDNavigationDrawer(*args, **kwargs)#
Navigation drawer class.
For more information, see in the
MDCard
class documentation.- Events:
New in version 2.0.0.
- on_open:
Fired when the navigation drawer is opened.
- on_close:
Fired when the navigation drawer is closed.
- drawer_type#
Type of drawer. Modal type will be on top of screen. Standard type will be at left or right of screen. Also it automatically disables
close_on_click
andenable_swiping
to prevent closing drawer for standard type.Changed in version 2.0.0: Rename from type to drawer_type.
drawer_type
is aOptionProperty
and defaults to ‘modal’.
- anchor#
Anchoring screen edge for drawer. Set it to ‘right’ for right-to-left languages. Available options are: ‘left’, ‘right’.
anchor
is aOptionProperty
and defaults to ‘left’.
- scrim_color#
Color for scrim in (r, g, b, a) or string format. Alpha channel will be multiplied with
_scrim_alpha
. Set fourth channel to 0 if you want to disable scrim.scrim_color
is aColorProperty
and defaults to [0, 0, 0, 0.5].
- padding#
Padding between layout box and children: [padding_left, padding_top, padding_right, padding_bottom].
Padding also accepts a two argument form [padding_horizontal, padding_vertical] and a one argument form [padding].
Changed in version 1.0.0.
MDNavigationDrawer: padding: "56dp"
padding
is aVariableListProperty
and defaults to ‘[dp(16), dp(16), dp(12), dp(16)]’.
- close_on_click#
Close when click on scrim or keyboard escape. It automatically sets to False for “standard” type.
close_on_click
is aBooleanProperty
and defaults to True.
- state#
Indicates if panel closed or opened. Sets after
status
change. Available options are: ‘close’, ‘open’.state
is aOptionProperty
and defaults to ‘close’.
- status#
Detailed state. Sets before
state
. Bind tostate
instead ofstatus
. Available options are: ‘closed’, ‘opening_with_swipe’, ‘opening_with_animation’, ‘opened’, ‘closing_with_swipe’, ‘closing_with_animation’.status
is aOptionProperty
and defaults to ‘closed’.
- open_progress#
Percent of visible part of side panel. The percent is specified as a floating point number in the range 0-1. 0.0 if panel is closed and 1.0 if panel is opened.
open_progress
is aNumericProperty
and defaults to 0.0.
- enable_swiping#
Allow to open or close navigation drawer with swipe. It automatically sets to False for “standard” type.
enable_swiping
is aBooleanProperty
and defaults to True.
- swipe_distance#
The distance of the swipe with which the movement of navigation drawer begins.
swipe_distance
is aNumericProperty
and defaults to 10.
- swipe_edge_width#
The size of the area in px inside which should start swipe to drag navigation drawer.
swipe_edge_width
is aNumericProperty
and defaults to 20.
- scrim_alpha_transition#
The name of the animation transition type to use for changing
scrim_alpha
.scrim_alpha_transition
is aStringProperty
and defaults to ‘linear’.
- opening_transition#
The name of the animation transition type to use when animating to the
state
‘open’.opening_transition
is aStringProperty
and defaults to ‘out_cubic’.
- opening_time#
The time taken for the panel to slide to the
state
‘open’.opening_time
is aNumericProperty
and defaults to 0.2.
- closing_transition#
The name of the animation transition type to use when animating to the
state
‘close’.closing_transition
is aStringProperty
and defaults to ‘out_sine’.
- closing_time#
The time taken for the panel to slide to the
state
‘close’.closing_time
is aNumericProperty
and defaults to 0.2.
- background_color#
The drawer background color in (r, g, b, a) or string format.
New in version 2.0.0.
background_color
is aColorProperty
and defaults to None.
- theme_elevation_level = 'Custom'#
Drawer elevation level scheme name.
New in version 2.0.0.
Available options are: ‘Primary’, ‘Custom’.
theme_elevation_level
is anOptionProperty
and defaults to ‘Custom’.
- elevation_level = 1#
Drawer elevation level (values from 0 to 5)
New in version 2.2.0.
elevation_level
is anBoundedNumericProperty
and defaults to 2.
- set_state(new_state='toggle', animation=True) → None#
Change state of the side panel. New_state can be one of “toggle”, “open” or “close”.
- 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.
- on_radius(instance_navigation_drawer, radius_value: list) → None#
Fired when the
radius
value changes.
- on_drawer_type(instance_navigation_drawer, drawer_type: str) → None#
Fired when the
drawer_type
value changes.