BottomSheet#

#

See also

Material Design spec, Sheets: bottom

Bottom sheets are surfaces containing supplementary content that are anchored to the bottom of the screen.

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

Usage#

Root:

    MDNavigationLayout:

        MDScreenManager:

            [...]

        MDBottomSheet:

The bottom sheet has two types:

Standard#

Standard bottom sheets co-exist with the screen’s main UI region and allow for simultaneously viewing and interacting with both regions, especially when the main UI region is frequently scrolled or panned.

Use a standard bottom sheet to display content that complements the screen’s primary content, such as an audio player in a music app.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-standard.gif

Standard bottom sheets are elevated above the main UI region so their visibility is not affected by panning or scrolling.

Add elements to MDBottomSheetDragHandleTitle class#

MDBottomSheet:

    MDBottomSheetDragHandle:

        MDBottomSheetDragHandleTitle:
            text: "MDBottomSheet"
            adaptive_height: True
            pos_hint: {"center_y": .5}

        MDBottomSheetDragHandleButton:
            icon: "close"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottomsheet-drag-handle-elements.png

A practical example with standard bottom sheet#

(A double tap on the map to open the bottom sheet)

import asynckivy

from kivy.lang import Builder
from kivy.properties import StringProperty, ObjectProperty, BooleanProperty
from kivy_garden.mapview import MapView

from kivymd.app import MDApp
from kivymd.uix.behaviors import TouchBehavior
from kivymd.uix.boxlayout import MDBoxLayout

KV = '''
#:import MapSource kivy_garden.mapview.MapSource
#:import asynckivy asynckivy


<TypeMapElement>
    orientation: "vertical"
    adaptive_height: True
    spacing: "8dp"

    MDIconButton:
        id: icon
        icon: root.icon
        theme_bg_color: "Custom"
        md_bg_color: "#EDF1F9" if not root.selected else app.theme_cls.primaryColor
        pos_hint: {"center_x": .5}
        theme_icon_color: "Custom"
        icon_color: "white" if root.selected else "black"
        on_release: app.set_active_element(root, root.title.lower())

    MDLabel:
        text: root.title
        pos_hint: {"center_x": .5}
        halign: "center"
        adaptive_height: True


MDScreen:

    MDNavigationLayout:

        MDScreenManager:

            MDScreen:

                CustomMapView:
                    bottom_sheet: bottom_sheet
                    map_source: MapSource(url=app.map_sources[app.current_map])
                    lat: 46.5124
                    lon: 47.9812
                    zoom: 12

        MDBottomSheet:
            id: bottom_sheet
            sheet_type: "standard"
            size_hint_y: None
            height: "150dp"
            on_open: asynckivy.start(app.generate_content())

            MDBottomSheetDragHandle:
                drag_handle_color: "grey"

                MDBottomSheetDragHandleTitle:
                    text: "Select type map"
                    pos_hint: {"center_y": .5}

                MDBottomSheetDragHandleButton:
                    icon: "close"
                    ripple_effect: False
                    on_release: bottom_sheet.set_state("toggle")

            BoxLayout:
                id: content_container
                padding: 0, 0, 0, "16dp"
'''


class TypeMapElement(MDBoxLayout):
    selected = BooleanProperty(False)
    icon = StringProperty()
    title = StringProperty()


class CustomMapView(MapView, TouchBehavior):
    bottom_sheet = ObjectProperty()

    def on_double_tap(self, touch, *args):
        if self.bottom_sheet:
            self.bottom_sheet.set_state("toggle")


class Example(MDApp):
    map_sources = {
        "street": "https://mt1.google.com/vt/lyrs=m&x={x}&y={y}&z={z}",
        "sputnik": "https://mt1.google.com/vt/lyrs=s&x={x}&y={y}&z={z}",
        "hybrid": "https://mt1.google.com/vt/lyrs=y&x={x}&y={y}&z={z}",
    }
    current_map = StringProperty("street")

    async def generate_content(self):
        icons = {
            "street": "google-street-view",
            "sputnik": "space-station",
            "hybrid": "map-legend",
        }
        if not self.root.ids.content_container.children:
            for i, title in enumerate(self.map_sources.keys()):
                await asynckivy.sleep(0)
                self.root.ids.content_container.add_widget(
                    TypeMapElement(
                        title=title.capitalize(),
                        icon=icons[title],
                        selected=not i,
                    )
                )

    def set_active_element(self, instance, type_map):
        for element in self.root.ids.content_container.children:
            if instance == element:
                element.selected = True
                self.current_map = type_map
            else:
                element.selected = False

    def build(self):
        return Builder.load_string(KV)


Example().run()

API break#

1.2.0 version#

Root:

    MDBottomSheet:

        # Optional.
        MDBottomSheetDragHandle:

            # Optional.
            MDBottomSheetDragHandleTitle:

            # Optional.
            MDBottomSheetDragHandleButton:

        MDBottomSheetContent:
            [...]

2.0.0 version#

Root:

    MDNavigationLayout:

        MDScreenManager:

            # Your screen.
            MDScreen:

        MDBottomSheet:

            # Optional.
            MDBottomSheetDragHandle:

                # Optional.
                MDBottomSheetDragHandleTitle:

                # Optional.
                MDBottomSheetDragHandleButton:
                    icon: "close"

            # Your content.
            BoxLayout:

API - kivymd.uix.bottomsheet.bottomsheet#

class kivymd.uix.bottomsheet.bottomsheet.MDBottomSheetDragHandleButton(**kwargs)#

Implements a close button (or other functionality) for the MDBottomSheetDragHandle container.

For more information, see in the MDIconButton class documentation.

New in version 1.2.0.

class kivymd.uix.bottomsheet.bottomsheet.MDBottomSheetDragHandleTitle(*args, **kwargs)#

Implements a header for the MDBottomSheetDragHandle container.

For more information, see in the MDLabel class documentation.

New in version 1.2.0.

class kivymd.uix.bottomsheet.bottomsheet.MDBottomSheetDragHandle(**kwargs)#

Implements a container that can place the header of the bottom sheet and the close button. Also implements the event of dragging the bottom sheet on the parent screen.

For more information, see in the BoxLayout class documentation.

New in version 1.2.0.

drag_handle_color#

Color of drag handle element in (r, g, b, a) or string format.

MDBottomSheet:

    MDBottomSheetDragHandle:
        drag_handle_color: "white"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-sheet-drag-handle-color.png

drag_handle_color is an ColorProperty 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.

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

Bottom sheet class.

For more information, see in the MDNavigationDrawer class documentation.

sheet_type#

Type of sheet.

Standard bottom sheets co-exist with the screen’s main UI region and allow for simultaneously viewing and interacting with both regions, especially when the main UI region is frequently scrolled or panned. Use a standard bottom sheet to display content that complements the screen’s primary content, such as an audio player in a music app.

Like dialogs, modal bottom sheets appear in front of app content, disabling all other app functionality when they appear, and remaining on screen until confirmed, dismissed, or a required action has been taken.

Changed in version 2.0.0: Rename from type to sheet_type.

sheet_type is a OptionProperty and defaults to ‘modal’.

on_sheet_type(instance, value) → None#

Fired when the sheet_type value changes.

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.

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

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.