openCom-Companion/sbapp/kivymd/uix/navigationrail/navigationrail.py
2022-10-08 17:17:59 +02:00

1242 lines
41 KiB
Python

"""
Components/NavigationRail
=========================
.. versionadded:: 1.0.0
.. seealso::
`Material Design spec, Navigation rail <https://m3.material.io/components/navigation-rail/specs>`_
.. rubric::
Navigation rails provide access to primary destinations in apps when using
tablet and desktop screens.
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail.png
:align: center
Usage
=====
.. code-block:: kv
MDNavigationRail:
MDNavigationRailItem:
MDNavigationRailItem:
MDNavigationRailItem:
.. tabs::
.. tab:: Declarative KV style
.. code-block:: python
from kivy.lang import Builder
from kivymd.app import MDApp
KV = '''
MDBoxLayout:
MDNavigationRail:
MDNavigationRailItem:
text: "Python"
icon: "language-python"
MDNavigationRailItem:
text: "JavaScript"
icon: "language-javascript"
MDNavigationRailItem:
text: "CPP"
icon: "language-cpp"
MDNavigationRailItem:
text: "Git"
icon: "git"
MDScreen:
'''
class Example(MDApp):
def build(self):
return Builder.load_string(KV)
Example().run()
.. tab:: Declarative python style
.. code-block:: python
from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.navigationrail import MDNavigationRail, MDNavigationRailItem
class Example(MDApp):
def build(self):
self.theme_cls.theme_style = "Dark"
self.theme_cls.primary_palette = "Orange"
return (
MDBoxLayout(
MDNavigationRail(
MDNavigationRailItem(
text="Python",
icon="language-python",
),
MDNavigationRailItem(
text="JavaScript",
icon="language-javascript",
),
MDNavigationRailItem(
text="CPP",
icon="language-cpp",
),
MDNavigationRailItem(
text="Git",
icon="git",
),
)
)
)
Example().run()
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-usage.png
:align: center
Example
=======
.. tabs::
.. tab:: Declarative KV and imperative python styles
.. code-block:: python
from kivy.clock import Clock
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.behaviors import CommonElevationBehavior
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.button import MDFillRoundFlatIconButton
from kivymd.uix.label import MDLabel
from kivymd.uix.screen import MDScreen
KV = '''
#:import FadeTransition kivy.uix.screenmanager.FadeTransition
<ExtendedButton>
elevation: 3.5
shadow_radius: 12
shadow_softness: 4
-height: "56dp"
<DrawerClickableItem@MDNavigationDrawerItem>
focus_color: "#e7e4c0"
unfocus_color: "#fffcf4"
MDScreen:
MDNavigationLayout:
ScreenManager:
MDScreen:
MDBoxLayout:
orientation: "vertical"
MDBoxLayout:
adaptive_height: True
md_bg_color: "#fffcf4"
padding: "12dp"
MDLabel:
text: "12:00"
adaptive_height: True
pos_hint: {"center_y": .5}
MDBoxLayout:
MDNavigationRail:
id: navigation_rail
md_bg_color: "#fffcf4"
selected_color_background: "#e7e4c0"
ripple_color_item: "#e7e4c0"
on_item_release: app.switch_screen(*args)
MDNavigationRailMenuButton:
on_release: nav_drawer.set_state("open")
MDNavigationRailFabButton:
md_bg_color: "#b0f0d6"
MDNavigationRailItem:
text: "Python"
icon: "language-python"
MDNavigationRailItem:
text: "JavaScript"
icon: "language-javascript"
MDNavigationRailItem:
text: "CPP"
icon: "language-cpp"
MDNavigationRailItem:
text: "Swift"
icon: "language-swift"
ScreenManager:
id: screen_manager
transition:
FadeTransition(duration=.2, clearcolor=app.theme_cls.bg_dark)
MDNavigationDrawer:
id: nav_drawer
radius: (0, 16, 16, 0)
md_bg_color: "#fffcf4"
elevation: 4
width: "240dp"
MDNavigationDrawerMenu:
MDBoxLayout:
orientation: "vertical"
adaptive_height: True
spacing: "12dp"
padding: "3dp", 0, 0, "12dp"
MDIconButton:
icon: "menu"
ExtendedButton:
text: "Compose"
icon: "pencil"
DrawerClickableItem:
text: "Python"
icon: "language-python"
DrawerClickableItem:
text: "JavaScript"
icon: "language-javascript"
DrawerClickableItem:
text: "CPP"
icon: "language-cpp"
DrawerClickableItem:
text: "Swift"
icon: "language-swift"
'''
class ExtendedButton(MDFillRoundFlatIconButton, CommonElevationBehavior):
'''
Implements a button of type
`Extended FAB <https://m3.material.io/components/extended-fab/overview>`_.
.. rubric::
Extended FABs help people take primary actions.
They're wider than FABs to accommodate a text label and larger target
area.
This type of buttons is not yet implemented in the standard widget set
of the KivyMD library, so we will implement it ourselves in this class.
'''
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.padding = "16dp"
Clock.schedule_once(self.set_spacing)
def set_spacing(self, interval):
self.ids.box.spacing = "12dp"
def set_radius(self, *args):
if self.rounded_button:
self._radius = self.radius = self.height / 4
class Example(MDApp):
def build(self):
self.theme_cls.material_style = "M3"
self.theme_cls.primary_palette = "Orange"
return Builder.load_string(KV)
def switch_screen(
self, instance_navigation_rail, instance_navigation_rail_item
):
'''
Called when tapping on rail menu items. Switches application screens.
'''
self.root.ids.screen_manager.current = (
instance_navigation_rail_item.icon.split("-")[1].lower()
)
def on_start(self):
'''Creates application screens.'''
navigation_rail_items = self.root.ids.navigation_rail.get_items()[:]
navigation_rail_items.reverse()
for widget in navigation_rail_items:
name_screen = widget.icon.split("-")[1].lower()
screen = MDScreen(
name=name_screen,
md_bg_color="#edd769",
radius=[18, 0, 0, 0],
)
box = MDBoxLayout(padding="12dp")
label = MDLabel(
text=name_screen.capitalize(),
font_style="H1",
halign="right",
adaptive_height=True,
shorten=True,
)
box.add_widget(label)
screen.add_widget(box)
self.root.ids.screen_manager.add_widget(screen)
Example().run()
.. tab:: Declarative python style
.. code-block:: python
from kivy.clock import Clock
from kivy.metrics import dp
from kivymd.app import MDApp
from kivymd.uix.behaviors import CommonElevationBehavior
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.button import MDFillRoundFlatIconButton, MDIconButton
from kivymd.uix.label import MDLabel
from kivymd.uix.navigationdrawer import (
MDNavigationDrawerItem,
MDNavigationLayout,
MDNavigationDrawer,
MDNavigationDrawerMenu,
)
from kivymd.uix.navigationrail import (
MDNavigationRail,
MDNavigationRailMenuButton,
MDNavigationRailFabButton,
MDNavigationRailItem,
)
from kivymd.uix.screen import MDScreen
from kivymd.uix.screenmanager import MDScreenManager
class DrawerClickableItem(MDNavigationDrawerItem):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.focus_color = "#e7e4c0"
self.unfocus_color = self.theme_cls.bg_light
self.radius = 24
class ExtendedButton(MDFillRoundFlatIconButton, CommonElevationBehavior):
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.padding = "16dp"
self.elevation = 3.5
self.shadow_radius = 12
self.shadow_softness = 4
self.height = dp(56)
Clock.schedule_once(self.set_spacing)
def set_spacing(self, interval):
self.ids.box.spacing = "12dp"
def set_radius(self, *args):
if self.rounded_button:
self._radius = self.radius = self.height / 4
class Example(MDApp):
def build(self):
self.theme_cls.material_style = "M3"
self.theme_cls.primary_palette = "Orange"
return MDScreen(
MDNavigationLayout(
MDScreenManager(
MDScreen(
MDBoxLayout(
MDBoxLayout(
MDLabel(
text="12:00",
adaptive_height=True,
pos_hint={"center_y": 0.5},
),
adaptive_height=True,
md_bg_color="#fffcf4",
padding="12dp",
),
MDBoxLayout(
MDNavigationRail(
MDNavigationRailMenuButton(
on_release=self.open_nav_drawer,
),
MDNavigationRailFabButton(
md_bg_color="#b0f0d6",
),
MDNavigationRailItem(
text="Python",
icon="language-python",
),
MDNavigationRailItem(
text="JavaScript",
icon="language-javascript",
),
MDNavigationRailItem(
text="CPP",
icon="language-cpp",
),
MDNavigationRailItem(
text="Swift",
icon="language-swift",
),
id="navigation_rail",
md_bg_color="#fffcf4",
selected_color_background="#e7e4c0",
ripple_color_item="#e7e4c0",
),
MDScreenManager(
id="screen_manager_content",
),
id="root_box",
),
id="box_rail",
orientation="vertical",
),
id="box",
),
id="screen",
),
id="screen_manager",
),
MDNavigationDrawer(
MDNavigationDrawerMenu(
MDBoxLayout(
MDIconButton(
icon="menu",
),
ExtendedButton(
text="Compose",
icon="pencil",
),
orientation="vertical",
adaptive_height=True,
spacing="12dp",
padding=("3dp", 0, 0, "12dp"),
),
DrawerClickableItem(
text="Python",
icon="language-python",
),
DrawerClickableItem(
text="JavaScript",
icon="language-javascript",
),
DrawerClickableItem(
text="CPP",
icon="language-cpp",
),
DrawerClickableItem(
text="Swift",
icon="language-swift",
),
),
id="nav_drawer",
radius=(0, 16, 16, 0),
elevation=4,
width="240dp",
),
)
def switch_screen(self, *args, screen_manager_content=None):
'''
Called when tapping on rail menu items. Switches application screens.
'''
instance_navigation_rail, instance_navigation_rail_item = args
screen_manager_content.current = (
instance_navigation_rail_item.icon.split("-")[1].lower()
)
def open_nav_drawer(self, *args):
self.root.ids.nav_drawer.set_state("open")
def on_start(self):
'''Creates application screens.'''
screen_manager = self.root.ids.screen_manager
root_box = screen_manager.ids.screen.ids.box.ids.box_rail.ids.root_box
navigation_rail = root_box.ids.navigation_rail
screen_manager_content = root_box.ids.screen_manager_content
navigation_rail_items = navigation_rail.get_items()[:]
navigation_rail_items.reverse()
navigation_rail.bind(
on_item_release=lambda *args: self.switch_screen(
*args, screen_manager_content=screen_manager_content
)
)
for widget in navigation_rail_items:
name_screen = widget.icon.split("-")[1].lower()
screen_manager_content.add_widget(
MDScreen(
MDBoxLayout(
MDLabel(
text=name_screen.capitalize(),
font_style="H1",
halign="right",
adaptive_height=True,
shorten=True,
),
padding="12dp",
),
name=name_screen,
md_bg_color="#edd769",
radius=[18, 0, 0, 0],
),
)
Example().run()
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-example.gif
:align: center
"""
__all__ = (
"MDNavigationRail",
"MDNavigationRailItem",
"MDNavigationRailFabButton",
"MDNavigationRailMenuButton",
)
import os
from typing import Union
from kivy.animation import Animation
from kivy.clock import Clock
from kivy.lang import Builder
from kivy.logger import Logger
from kivy.metrics import dp
from kivy.properties import (
BooleanProperty,
ColorProperty,
ListProperty,
NumericProperty,
ObjectProperty,
OptionProperty,
StringProperty,
VariableListProperty,
)
from kivy.uix.behaviors import ButtonBehavior
from kivymd import uix_path
from kivymd.theming import ThemableBehavior
from kivymd.uix.behaviors import ScaleBehavior
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.button import MDFloatingActionButton, MDIconButton
from kivymd.uix.card import MDCard
from kivymd.uix.floatlayout import MDFloatLayout
from kivymd.uix.widget import MDWidget
with open(
os.path.join(uix_path, "navigationrail", "navigationrail.kv"),
encoding="utf-8",
) as kv_file:
Builder.load_string(kv_file.read())
class PanelRoot(MDFloatLayout):
"""
Contains
:class:`~MDNavigationRailFabButton`, :class:`~MDNavigationRailMenuButton`
buttons and a :class:`~Paneltems` container with menu items.
"""
class PanelItems(MDBoxLayout):
"""Box for menu items."""
class RippleWidget(MDWidget, ScaleBehavior):
"""
Implements a background color for a menu item -
(:class:`~MDNavigationRailItem`).
"""
class MDNavigationRailFabButton(MDFloatingActionButton):
"""Implements an optional floating action button (FAB)."""
icon = StringProperty("pencil")
"""
Button icon name.
.. code-block:: kv
MDNavigationRail:
MDNavigationRailFabButton:
icon: "home"
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-fab-button-icon.png
:align: center
:attr:`icon` is an :class:`~kivy.properties.StringProperty`
and defaults to `'pencil'`.
"""
class MDNavigationRailMenuButton(MDIconButton):
"""Implements a menu button."""
icon = StringProperty("menu")
"""
Button icon name.
.. code-block:: kv
MDNavigationRail:
MDNavigationRailMenuButton:
icon: "home"
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-menu-button-icon.png
:align: center
:attr:`icon` is an :class:`~kivy.properties.StringProperty`
and defaults to `'menu'`.
"""
class MDNavigationRailItem(ThemableBehavior, ButtonBehavior, MDBoxLayout):
"""Implements a menu item with an icon and text."""
navigation_rail = ObjectProperty()
"""
:class:`~MDNavigationRail` object.
:attr:`navigation_rail` is an :class:`~kivy.properties.ObjectProperty`
and defaults to `None`.
"""
icon = StringProperty("checkbox-blank-circle")
"""
Icon item.
.. code-block:: kv
MDNavigationRail:
MDNavigationRailItem:
icon: "language-python"
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-icon.png
:align: center
:attr:`icon` is an :class:`~kivy.properties.StringProperty`
and defaults to `'checkbox-blank'`.
"""
text = StringProperty()
"""
Text item.
.. code-block:: kv
MDNavigationRail:
MDNavigationRailItem:
text: "Python"
icon: "language-python"
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-text.png
:align: center
:attr:`text` is an :class:`~kivy.properties.StringProperty`
and defaults to `''`.
"""
badge_icon = StringProperty()
"""
Badge icon name.
.. code-block:: kv
MDNavigationRail:
MDNavigationRailItem:
text: "Python"
icon: "language-python"
badge_icon: "plus"
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-badge-icon.png
:align: center
:attr:`badge_icon` is an :class:`~kivy.properties.StringProperty`
and defaults to `''`.
"""
badge_icon_color = ColorProperty(None)
"""
Badge icon color in (r, g, b, a) format.
.. code-block:: kv
MDNavigationRail:
MDNavigationRailItem:
text: "Python"
icon: "language-python"
badge_icon: "plus"
badge_icon_color: 0, 0, 1, 1
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-badge-icon-color.png
:align: center
:attr:`badge_icon_color` is an :class:`~kivy.properties.StringProperty`
and defaults to `None`.
"""
badge_bg_color = ColorProperty(None)
"""
Badge icon background color in (r, g, b, a) format.
.. code-block:: kv
MDNavigationRail:
MDNavigationRailItem:
text: "Python"
icon: "language-python"
badge_icon: "plus"
badge_bg_color: "#b0f0d6"
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-badge-bg-color.png
:align: center
:attr:`badge_bg_color` is an :class:`~kivy.properties.ColorProperty`
and defaults to `None`.
"""
badge_font_size = NumericProperty(0)
"""
Badge icon font size.
.. code-block:: kv
MDNavigationRail:
MDNavigationRailItem:
text: "Python"
icon: "language-python"
badge_icon: "plus"
badge_font_size: "24sp"
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-badge-font-size.png
:align: center
:attr:`badge_font_size` is an :class:`~kivy.properties.NumericProperty`
and defaults to `0`.
"""
active = BooleanProperty(False)
"""
Is the element active.
:attr:`active` is an :class:`~kivy.properties.BooleanProperty`
and defaults to `False`.
"""
_selected_region_width = NumericProperty("56dp")
_ripple_size = ListProperty([0, 0])
_release = BooleanProperty(False)
def on_active(
self, instance_navigation_rail_item, value_active: bool
) -> None:
"""Called when the value of `active` changes."""
self.animation_size_ripple_area(1 if value_active else 0)
def animation_size_ripple_area(self, value: int) -> None:
"""Animates the size/fade of the ripple area."""
Animation(
scale_value_x=value,
scale_value_y=value,
scale_value_z=value,
opacity=value,
d=0.25,
t=self.navigation_rail.ripple_transition,
).start(self.ids.ripple_widget)
def on_press(self) -> None:
"""Called when pressed on a panel element."""
self._release = False
self.active = True
self.navigation_rail.deselect_item(self)
self.navigation_rail.dispatch("on_item_press", self)
def on_release(self) -> None:
"""Called when released on a panel element."""
self._release = True
self.animation_size_ripple_area(0)
self.navigation_rail.dispatch("on_item_release", self)
class MDNavigationRail(MDCard):
"""
:Events:
:attr:`on_item_press`
Called on the `on_press` event of menu item -
:class:`~MDNavigationRailItem`.
:attr:`on_item_release`
Called on the `on_release` event of menu item -
:class:`~MDNavigationRailItem`.
"""
radius = VariableListProperty(0, length=4)
"""
Rail radius.
:attr:`radius` is an :class:`~kivy.properties.VariableListProperty`
and defaults to `[0, 0, 0, 0]`.
"""
padding = VariableListProperty([0, "36dp", 0, "36dp"], length=4)
"""
Padding between layout box and children:
[padding_left, padding_top, padding_right, padding_bottom].
:attr:`padding` is a :class:`~kivy.properties.VariableListProperty`
and defaults to `[0, '36dp', 0, '36dp']`.
"""
anchor = OptionProperty("top", options=["top", "bottom", "center"])
"""
The position of the panel with menu items.
Available options are: `'top'`, `'bottom'`, `'center'`.
.. rubric:: Top
.. code-block:: kv
MDNavigationRail:
anchor: "top"
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-anchor-top.png
:align: center
.. rubric:: Center
.. code-block:: kv
MDNavigationRail:
anchor: "center"
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-center.png
:align: center
.. rubric:: Bottom
.. code-block:: kv
MDNavigationRail:
anchor: "bottom"
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-bottom.png
:align: center
:attr:`anchor` is an :class:`~kivy.properties.OptionProperty`
and defaults to `'top'`.
"""
type = OptionProperty(
"labeled", options=["labeled", "selected", "unselected"]
)
"""
Type of switching menu items.
Available options are: `'labeled'`, `'selected'`, `'unselected'`.
.. rubric:: Labeled
.. code-block:: kv
MDNavigationRail:
type: "labeled"
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-labeled.png
:align: center
.. rubric:: Selected
.. code-block:: kv
MDNavigationRail:
type: "selected"
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-selected.gif
:align: center
.. rubric:: Unselected
.. code-block:: kv
MDNavigationRail:
type: "unselected"
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-unselected.gif
:align: center
:attr:`type` is an :class:`~kivy.properties.OptionProperty`
and defaults to `'labeled'`.
"""
text_color_item_normal = ColorProperty(None)
"""
The text color of the normal menu item (:class:`~MDNavigationRailItem`).
.. code-block:: kv
MDNavigationRail:
text_color_item_normal: app.theme_cls.primary_color
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-text-color-item-normal.png
:align: center
:attr:`text_color_item_normal` is an :class:`~kivy.properties.ColorProperty`
and defaults to `None`.
"""
text_color_item_active = ColorProperty(None)
"""
The text color of the active menu item (:class:`~MDNavigationRailItem`).
.. code-block:: kv
MDNavigationRail:
text_color_item_active: app.theme_cls.primary_color
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-text-color-item-active.png
:align: center
:attr:`text_color_item_active` is an :class:`~kivy.properties.ColorProperty`
and defaults to `None`.
"""
icon_color_item_normal = ColorProperty(None)
"""
The icon color of the normal menu item (:class:`~MDNavigationRailItem`).
.. code-block:: kv
MDNavigationRail:
icon_color_item_normal: app.theme_cls.primary_color
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-icon-color-item-normal.png
:align: center
:attr:`icon_color_item_normal` is an :class:`~kivy.properties.ColorProperty`
and defaults to `None`.
"""
icon_color_item_active = ColorProperty(None)
"""
The icon color of the active menu item (:class:`~MDNavigationRailItem`).
.. code-block:: kv
MDNavigationRail:
icon_color_item_active: app.theme_cls.primary_color
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-icon-color-item-active.png
:align: center
:attr:`icon_color_item_active` is an :class:`~kivy.properties.ColorProperty`
and defaults to `None`.
"""
selected_color_background = ColorProperty(None)
"""
Background color which will highlight the icon of the active menu item -
:class:`~MDNavigationRailItem` - in (r, g, b, a) format.
.. code-block:: kv
MDNavigationRail:
selected_color_background: "#e7e4c0"
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-selected-color-background.png
:align: center
:attr:`selected_color_background` is an :class:`~kivy.properties.ColorProperty`
and defaults to `None`.
"""
ripple_color_item = ColorProperty(None)
"""
Ripple effect color of menu items (:class:`~MDNavigationRailItem`)
in (r, g, b, a) format.
.. code-block:: kv
MDNavigationRail:
ripple_color_item: "#e7e4c0"
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-ripple-color-item.png
:align: center
:attr:`ripple_color_item` is an :class:`~kivy.properties.ColorProperty`
and defaults to `None`.
"""
ripple_transition = StringProperty("out_cubic")
"""
Type of animation of the ripple effect when a menu item is selected.
:attr:`ripple_transition` is a :class:`~kivy.properties.StringProperty`
and defaults to `'ripple_transition'`.
"""
current_selected_item = NumericProperty(0)
"""
Index of the menu list item (:class:`~MDNavigationRailItem`) that will be
active by default
.. code-block:: kv
MDNavigationRail:
current_selected_item: 1
MDNavigationRailItem:
...
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-current-selected-item.png
:align: center
:attr:`current_selected_item` is a :class:`~kivy.properties.NumericProperty`
and defaults to `0`.
"""
font_name = StringProperty("Roboto")
"""
Font path for menu item (:class:`~MDNavigationRailItem`) text.
.. code-block:: kv
MDNavigationRail:
MDNavigationRailItem:
text: "Python"
icon: "language-python"
font_name: "nasalization-rg.ttf"
.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-font-name.png
:align: center
:attr:`font_name` is an :class:`~kivy.properties.StringProperty`
and defaults to `'Roboto'`.
"""
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
Clock.schedule_once(self.set_pos_menu_fab_buttons)
Clock.schedule_once(self.set_current_selected_item)
self.register_event_type("on_item_press")
self.register_event_type("on_item_release")
def on_item_press(self, *args) -> None:
"""
Called on the `on_press` event of menu item -
:class:`~MDNavigationRailItem`.
"""
def on_item_release(self, *args) -> None:
"""
Called on the `on_release` event of menu item -
:class:`~MDNavigationRailItem`.
"""
def deselect_item(
self, selected_navigation_rail_item: MDNavigationRailItem
) -> None:
"""
Sets the `active` value to `False` for all menu items
(:class:`~MDNavigationRailItem`) except the selected item.
Called when a menu item is touched.
"""
for navigation_rail_item in self.ids.box_items.children:
if selected_navigation_rail_item is not navigation_rail_item:
navigation_rail_item.active = False
def get_items(self) -> list:
"""Returns a list of :class:`~MDNavigationRailItem` objects"""
return self.ids.box_items.children
def set_pos_panel_items(
self,
instance_fab_button: Union[None, MDNavigationRailFabButton],
instance_menu_button: Union[None, MDNavigationRailFabButton],
) -> None:
"""Set :class:`~Paneltems` panel position with menu items."""
if self.anchor == "top":
if instance_fab_button:
self.ids.box_items.y = instance_fab_button.y - (
len(self.ids.box_items.children) * dp(56)
+ self.padding[1] * 2
+ dp(24)
)
else:
if not instance_menu_button:
self.ids.box_items.pos_hint = {"top": 1}
else:
self.ids.box_items.y = instance_menu_button.y - (
len(self.ids.box_items.children) * dp(56)
+ self.padding[1] * 2
)
elif self.anchor == "center":
self.ids.box_items.pos_hint = {"center_y": 0.5}
elif self.anchor == "bottom":
self.ids.box_items.y = dp(12)
def set_current_selected_item(self, interval: Union[int, float]) -> None:
"""Sets the active menu list item (:class:`~MDNavigationRailItem`)."""
if self.ids.box_items.children:
items = self.ids.box_items.children[:]
items.reverse()
if len(items) <= self.current_selected_item:
Logger.error(
f"MDNavigationRail:You have "
f"{len(self.ids.box_items.children)} menu items, but you "
f"set {self.current_selected_item} as the active item. "
f"The very first menu item will be set active."
)
index = 0
else:
index = self.current_selected_item
items[index].dispatch("on_press")
items[index].dispatch("on_release")
def set_pos_menu_fab_buttons(self, interval: Union[int, float]) -> None:
"""
Sets the position of the :class:`~MDNavigationRailFabButton` and
:class:`~MDNavigationRailMenuButton` buttons on the panel.
"""
fab_button = None # MDNavigationRailFabButton
menu_button = None # MDNavigationRailMenuButton
for widget in self.ids.box_buttons.children:
if isinstance(widget, MDNavigationRailFabButton):
fab_button = widget
if isinstance(widget, MDNavigationRailMenuButton):
menu_button = widget
if fab_button and menu_button:
def set_fab_button_y(interval):
fab_button.y = self.parent.height - (
menu_button.height
+ fab_button.height
+ self.padding[1]
+ dp(18)
)
self.set_pos_panel_items(fab_button, menu_button)
Clock.schedule_once(set_fab_button_y)
elif fab_button and not menu_button:
def set_fab_button_y(interval):
fab_button.y = self.parent.height - (
self.padding[1] + fab_button.height
)
self.set_pos_panel_items(fab_button, menu_button)
Clock.schedule_once(set_fab_button_y)
else:
Clock.schedule_once(
lambda x: self.set_pos_panel_items(fab_button, menu_button)
)
def add_widget(self, widget, *args, **kwargs):
if isinstance(widget, MDNavigationRailFabButton):
self.ids.box_buttons.add_widget(widget)
elif isinstance(widget, MDNavigationRailMenuButton):
self.ids.box_buttons.add_widget(widget)
elif isinstance(widget, MDNavigationRailItem):
widget.navigation_rail = self
self.ids.box_items.add_widget(widget)
elif isinstance(widget, (PanelRoot, PanelItems)):
return super().add_widget(widget)