NavigationRail

New in version 1.0.0.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail.png

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-usage.png

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()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-example.gif

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"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-fab-button-icon.png

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"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-menu-button-icon.png

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:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-anchor-top.png

Center

MDNavigationRail:
    anchor: "center"

    MDNavigationRailItem:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-center.png

Bottom

MDNavigationRail:
    anchor: "bottom"

    MDNavigationRailItem:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-bottom.png

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:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-labeled.png

Selected

MDNavigationRail:
    type: "selected"

    MDNavigationRailItem:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-selected.gif

Unselected

MDNavigationRail:
    type: "unselected"

    MDNavigationRailItem:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-type-unselected.gif

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:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-text-color-item-normal.png

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:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-text-color-item-active.png

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:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-icon-color-item-normal.png

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:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-icon-color-item-active.png

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:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-selected-color-background.png

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:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-ripple-color-item.png

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:
        ...
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-current-selected-item.png

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"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-font-name.png

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)