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 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()
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(*args, **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(*args, **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.MDNavigationRailItem(**kwargs)#

Implements a menu item with an icon and text.

navigation_rail#

MDNavigationRail object.

navigation_rail is an ObjectProperty and defaults to None.

icon#

Icon item.

MDNavigationRail:

    MDNavigationRailItem:
        icon: "language-python"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-icon.png

icon is an StringProperty and defaults to ‘checkbox-blank’.

text#

Text item.

MDNavigationRail:

    MDNavigationRailItem:
        text: "Python"
        icon: "language-python"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-text.png

text is an StringProperty and defaults to ‘’.

badge_icon#

Badge icon name.

MDNavigationRail:

    MDNavigationRailItem:
        text: "Python"
        icon: "language-python"
        badge_icon: "plus"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-badge-icon.png

badge_icon is an StringProperty and defaults to ‘’.

badge_icon_color#

Badge icon color in (r, g, b, a) format.

MDNavigationRail:

    MDNavigationRailItem:
        text: "Python"
        icon: "language-python"
        badge_icon: "plus"
        badge_icon_color: 0, 0, 1, 1
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-badge-icon-color.png

badge_icon_color is an StringProperty and defaults to None.

badge_bg_color#

Badge icon background color in (r, g, b, a) format.

MDNavigationRail:

    MDNavigationRailItem:
        text: "Python"
        icon: "language-python"
        badge_icon: "plus"
        badge_bg_color: "#b0f0d6"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-badge-bg-color.png

badge_bg_color is an ColorProperty and defaults to None.

badge_font_size#

Badge icon font size.

MDNavigationRail:

    MDNavigationRailItem:
        text: "Python"
        icon: "language-python"
        badge_icon: "plus"
        badge_font_size: "24sp"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/navigation-rail-item-badge-font-size.png

badge_font_size is an NumericProperty and defaults to 0.

active#

Is the element active.

active is an BooleanProperty and defaults to False.

on_active(self, instance_navigation_rail_item, value_active: bool)#

Called when the value of active changes.

animation_size_ripple_area(self, value: int)#

Animates the size/fade of the ripple area.

on_press(self)#

Called when pressed on a panel element.

on_release(self)#

Called when released on a panel element.

class kivymd.uix.navigationrail.navigationrail.MDNavigationRail(*args, **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: "#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: "#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)