NavigationRail

New in version 1.0.0.

See also

Material Design spec, Navigation rail

Usage

MDNavigationRail:

    MDNavigationRailItem:

    MDNavigationRailItem:

    MDNavigationRailItem:

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()

Example

from kivy.clock import Clock
from kivy.lang import Builder
from kivy.utils import get_color_from_hex

from kivymd.app import MDApp
from kivymd.uix.behaviors import RoundedRectangularElevationBehavior
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 get_color_from_hex kivy.utils.get_color_from_hex
#:import FadeTransition kivy.uix.screenmanager.FadeTransition

#:set rail_bg_color get_color_from_hex("#fffcf4")
#:set fab_button_bg_color get_color_from_hex("#b0f0d6")
#:set selected_item_bg_color get_color_from_hex("#e7e4c0")


<ExtendedButton>
    elevation: 3
    -height: "56dp"


<DrawerClickableItem@MDNavigationDrawerItem>
    focus_color: selected_item_bg_color
    unfocus_color: rail_bg_color


MDScreen:

    MDNavigationLayout:

        ScreenManager:

            MDScreen:

                MDBoxLayout:
                    orientation: "vertical"

                    MDBoxLayout:
                        adaptive_height: True
                        md_bg_color: rail_bg_color
                        padding: "12dp"

                        MDLabel:
                            text: "12:00"
                            adaptive_height: True
                            pos_hint: {"center_y": .5}

                    MDBoxLayout:

                        MDNavigationRail:
                            id: navigation_rail
                            md_bg_color: rail_bg_color
                            selected_color_background: selected_item_bg_color
                            ripple_color_item: selected_item_bg_color
                            on_item_release: app.switch_screen(*args)

                            MDNavigationRailMenuButton:
                                on_release: nav_drawer.set_state("open")

                            MDNavigationRailFabButton:
                                md_bg_color: fab_button_bg_color

                            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: rail_bg_color
        elevation: 12
        width: "240dp"

        MDNavigationDrawerMenu:

            MDBoxLayout:
                orientation: "vertical"
                adaptive_height: True
                spacing: "12dp"
                padding: 0, 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(
    RoundedRectangularElevationBehavior, MDFillRoundFlatIconButton
):
    '''
    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, **kwargs):
        super().__init__(**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=get_color_from_hex("#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()

API - kivymd.uix.navigationrail.navigationrail

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailFabButton(**kwargs)

Implements an optional floating action button (FAB).

icon

Button icon name.

MDNavigationRail:

    MDNavigationRailFabButton:
        icon: "home"

icon is an StringProperty and defaults to ‘pencil’.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRailMenuButton(**kwargs)

Implements a menu button.

icon

Button icon name.

MDNavigationRail:

    MDNavigationRailMenuButton:
        icon: "home"

icon is an StringProperty and defaults to ‘menu’.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRail(**kwargs)

Events

on_item_press

Called on the on_press event of menu item - MDNavigationRailItem.

on_item_release

Called on the on_release event of menu item - MDNavigationRailItem.

radius

Rail radius.

radius is an VariableListProperty and defaults to [0, 0, 0, 0].

padding

Padding between layout box and children: [padding_left, padding_top, padding_right, padding_bottom].

padding is a VariableListProperty and defaults to [0, ‘36dp’, 0, ‘36dp’].

anchor

The position of the panel with menu items. Available options are: ‘top’, ‘bottom’, ‘center’.

Top

MDNavigationRail:
    anchor: "top"

    MDNavigationRailItem:
        ...

Center

MDNavigationRail:
    anchor: "center"

    MDNavigationRailItem:
        ...

Bottom

MDNavigationRail:
    anchor: "bottom"

    MDNavigationRailItem:
        ...

anchor is an OptionProperty and defaults to ‘top’.

type

Type of switching menu items. Available options are: ‘labeled’, ‘selected’, ‘unselected’.

Labeled

MDNavigationRail:
    type: "labeled"

    MDNavigationRailItem:
        ...

Selected

MDNavigationRail:
    type: "selected"

    MDNavigationRailItem:
        ...

Unselected

MDNavigationRail:
    type: "unselected"

    MDNavigationRailItem:
        ...

type is an OptionProperty and defaults to ‘labeled’.

text_color_item_normal

The text color of the normal menu item (MDNavigationRailItem).

MDNavigationRail:
    text_color_item_normal: app.theme_cls.primary_color

    MDNavigationRailItem:
        ...

text_color_item_normal is an ColorProperty and defaults to None.

text_color_item_active

The text color of the active menu item (MDNavigationRailItem).

MDNavigationRail:
    text_color_item_active: app.theme_cls.primary_color

    MDNavigationRailItem:
        ...

text_color_item_active is an ColorProperty and defaults to None.

icon_color_item_normal

The icon color of the normal menu item (MDNavigationRailItem).

MDNavigationRail:
    icon_color_item_normal: app.theme_cls.primary_color

    MDNavigationRailItem:
        ...

icon_color_item_normal is an ColorProperty and defaults to None.

icon_color_item_active

The icon color of the active menu item (MDNavigationRailItem).

MDNavigationRail:
    icon_color_item_active: app.theme_cls.primary_color

    MDNavigationRailItem:
        ...

icon_color_item_active is an ColorProperty and defaults to None.

selected_color_background

Background color which will highlight the icon of the active menu item - MDNavigationRailItem - in (r, g, b, a) format.

MDNavigationRail:
    selected_color_background: get_color_from_hex("#e7e4c0")

    MDNavigationRailItem:
        ...

selected_color_background is an ColorProperty and defaults to None.

ripple_color_item

Ripple effect color of menu items (MDNavigationRailItem) in (r, g, b, a) format.

MDNavigationRail:
    ripple_color_item: get_color_from_hex("#e7e4c0")

    MDNavigationRailItem:
        ...

ripple_color_item is an ColorProperty and defaults to None.

ripple_transition

Type of animation of the ripple effect when a menu item is selected.

ripple_transition is a StringProperty and defaults to ‘ripple_transition’.

current_selected_item

Index of the menu list item (MDNavigationRailItem) that will be active by default

MDNavigationRail:
    current_selected_item: 1

    MDNavigationRailItem:
        ...

current_selected_item is a NumericProperty and defaults to 0.

font_name

Font path for menu item (MDNavigationRailItem) text.

MDNavigationRail:

    MDNavigationRailItem:
        text: "Python"
        icon: "language-python"
        font_name: "nasalization-rg.ttf"

font_name is an StringProperty and defaults to ‘Roboto’.

on_item_press(self, *args)

Called on the on_press event of menu item - MDNavigationRailItem.

on_item_release(self, *args)

Called on the on_release event of menu item - MDNavigationRailItem.

deselect_item(self, selected_navigation_rail_item: MDNavigationRailItem)

Sets the active value to False for all menu items (MDNavigationRailItem) except the selected item. Called when a menu item is touched.

get_items(self)

Returns a list of MDNavigationRailItem objects

set_pos_panel_items(self, instance_fab_button: Union[None, MDNavigationRailFabButton], instance_menu_button: Union[None, MDNavigationRailFabButton])

Set Paneltems panel position with menu items.

set_current_selected_item(self, interval: Union[int, float])

Sets the active menu list item (MDNavigationRailItem).

set_pos_menu_fab_buttons(self, interval: Union[int, float])

Sets the position of the MDNavigationRailFabButton and MDNavigationRailMenuButton buttons on the panel.

add_widget(self, 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.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)