Appbar

Appbar#

#

See also

Material Design spec, App bars: top

Material Design spec, App bars: bottom

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/app-bar-top.png

KivyMD provides the following bar positions for use:

TopAppBar#

  • Contains a title and actions related to the current screen

  • Four types: center-aligned, small, medium, and large

  • On scroll, apply a container fill color to separate app bar from body content

  • Top app bars have the same width as the device window

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-available-types.png

  1. Center-aligned

  2. Small

  3. Medium

  4. Large

Note

KivyMD does not provide a Center-aligned type panel. But you can easily create this pit panel yourself (read the documentation below).

Usage#

MDTopAppBar:
    type: "small"

    MDTopAppBarLeadingButtonContainer:

        MDActionTopAppBarButton:
            icon: "menu"

    MDTopAppBarTitle:
        text: "AppBar Center-aligned"
        halign: "center"

    MDTopAppBarTrailingButtonContainer:

        MDActionTopAppBarButton:
            icon: "account-circle-outline"

Anatomy#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-anatomy.png

Configurations#

1. Center-aligned#

MDScreen:
    md_bg_color: self.theme_cls.secondaryContainerColor

    MDTopAppBar:
        type: "small"
        size_hint_x: .8
        pos_hint: {"center_x": .5, "center_y": .5}

        MDTopAppBarLeadingButtonContainer:

            MDActionTopAppBarButton:
                icon: "menu"

        MDTopAppBarTitle:
            text: "AppBar small"
            halign: "center"

        MDTopAppBarTrailingButtonContainer:

            MDActionTopAppBarButton:
                icon: "account-circle-outline"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-center-aligned.png

2. Small#

MDScreen:
    md_bg_color: self.theme_cls.secondaryContainerColor

    MDTopAppBar:
        type: "small"
        size_hint_x: .8
        pos_hint: {"center_x": .5, "center_y": .5}

        MDTopAppBarLeadingButtonContainer:

            MDActionTopAppBarButton:
                icon: "arrow-left"

        MDTopAppBarTitle:
            text: "AppBar small"

        MDTopAppBarTrailingButtonContainer:

            MDActionTopAppBarButton:
                icon: "attachment"

            MDActionTopAppBarButton:
                icon: "calendar"

            MDActionTopAppBarButton:
                icon: "dots-vertical"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-small.png

3. Medium#

MDTopAppBar:
    type: "medium"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-medium.png

4. Large#

MDTopAppBar:
    type: "large"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/top-appbar-large.png

BottomAppBar#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/app-bar-bottom-m3.png 
from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDBottomAppBar:

        MDFabBottomAppBarButton:
            icon: "plus"
'''


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-app-bar-m3-style-1.png

Add action items#

#:import MDActionBottomAppBarButton kivymd.uix.appbar.MDActionBottomAppBarButton


MDScreen:

    MDBottomAppBar:
        action_items:
            [
            MDActionBottomAppBarButton(icon="gmail"),
            MDActionBottomAppBarButton(icon="label-outline"),
            MDActionBottomAppBarButton(icon="bookmark"),
            ]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-app-bar-m3-style-2.png

Change action items#

from kivy.lang import Builder

from kivymd.app import MDApp
from kivymd.uix.appbar import MDActionBottomAppBarButton

KV = '''
#:import MDActionBottomAppBarButton kivymd.uix.appbar.MDActionBottomAppBarButton


MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDBottomAppBar:
        id: bottom_appbar
        action_items:
            [
            MDActionBottomAppBarButton(icon="gmail"),
            MDActionBottomAppBarButton(icon="bookmark"),
            ]

        MDFabBottomAppBarButton:
            icon: "plus"
            on_release: app.change_actions_items()
'''


class Example(MDApp):
    def change_actions_items(self):
        self.root.ids.bottom_appbar.action_items = [
            MDActionBottomAppBarButton(icon="magnify"),
            MDActionBottomAppBarButton(icon="trash-can-outline"),
            MDActionBottomAppBarButton(icon="download-box-outline"),
        ]

    def build(self):
        self.theme_cls.theme_style = "Dark"
        return Builder.load_string(KV)


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-app-bar-m3-style-3.gif

A practical example#

import asynckivy

from kivy.clock import Clock
from kivy.lang import Builder
from kivy.properties import StringProperty, BooleanProperty, ObjectProperty
from kivy.uix.behaviors import StateFocusBehavior
from kivy.uix.recycleboxlayout import RecycleBoxLayout
from kivy.uix.recycleview.layout import LayoutSelectionBehavior
from kivy.uix.recycleview.views import RecycleDataViewBehavior

from kivymd.uix.appbar import MDActionBottomAppBarButton
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.app import MDApp

from faker import Faker  # pip install Faker

KV = '''
#:import MDFabBottomAppBarButton kivymd.uix.appbar.MDFabBottomAppBarButton


<UserCard>
    orientation: "vertical"
    adaptive_height: True
    md_bg_color: "#373A22" if self.selected else "#1F1E15"
    radius: 16
    padding: 0, 0, 0, "16dp"

    MDListItem:
        theme_bg_color: "Custom"
        md_bg_color: root.md_bg_color
        radius: root.radius
        ripple_effect: False

        MDListItemLeadingAvatar:
            source: root.avatar
            # radius: self.height / 2

        MDListItemHeadlineText:
            text: root.name
            theme_text_color: "Custom"
            text_color: "#8A8D79"

        MDListItemSupportingText:
            text: root.time
            theme_text_color: "Custom"
            text_color: "#8A8D79"

    MDLabel:
        text: root.text
        adaptive_height: True
        theme_text_color: "Custom"
        text_color: "#8A8D79"
        padding_x: "16dp"
        shorten: True
        shorten_from: "right"

    Widget:


MDFloatLayout:
    md_bg_color: "#151511"

    RecycleView:
        id: card_list
        viewclass: "UserCard"

        SelectableRecycleGridLayout:
            orientation: 'vertical'
            spacing: "16dp"
            padding: "16dp"
            default_size: None, dp(120)
            default_size_hint: 1, None
            size_hint_y: None
            height: self.minimum_height
            multiselect: True
            touch_multiselect: True

    MDBottomAppBar:
        id: bottom_appbar
        scroll_cls: card_list
        allow_hidden: True
        theme_bg_color: "Custom"
        md_bg_color: "#232217"

        MDFabBottomAppBarButton:
            id: fab_button
            icon: "plus"
            theme_bg_color: "Custom"
            md_bg_color: "#373A22"
            theme_icon_color: "Custom"
            icon_color: "#ffffff"
'''


class UserCard(RecycleDataViewBehavior, MDBoxLayout):
    name = StringProperty()
    time = StringProperty()
    text = StringProperty()
    avatar = StringProperty()
    callback = ObjectProperty(lambda x: x)

    index = None
    selected = BooleanProperty(False)
    selectable = BooleanProperty(True)

    def refresh_view_attrs(self, rv, index, data):
        self.index = index
        return super().refresh_view_attrs(rv, index, data)

    def on_touch_down(self, touch):
        if super().on_touch_down(touch):
            return True
        if self.collide_point(*touch.pos) and self.selectable:
            Clock.schedule_once(self.callback)
            return self.parent.select_with_touch(self.index, touch)

    def apply_selection(self, rv, index, is_selected):
        self.selected = is_selected
        rv.data[index]["selected"] = is_selected


class SelectableRecycleGridLayout(
    StateFocusBehavior, LayoutSelectionBehavior, RecycleBoxLayout
):
    pass


class BottomAppBarButton(MDActionBottomAppBarButton):
    theme_icon_color = "Custom"
    icon_color = "#8A8D79"


class Example(MDApp):
    selected_cards = False

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

    def on_tap_card(self, *args):
        datas = [data["selected"] for data in self.root.ids.card_list.data]
        if True in datas and not self.selected_cards:
            self.root.ids.bottom_appbar.action_items = [
                BottomAppBarButton(icon="gmail"),
                BottomAppBarButton(icon="label-outline"),
                BottomAppBarButton(icon="bookmark"),
            ]
            self.root.ids.fab_button.icon = "pencil"
            self.selected_cards = True
        else:
            if len(list(set(datas))) == 1 and not list(set(datas))[0]:
                self.selected_cards = False
            if not self.selected_cards:
                self.root.ids.bottom_appbar.action_items = [
                    BottomAppBarButton(icon="magnify"),
                    BottomAppBarButton(icon="trash-can-outline"),
                    BottomAppBarButton(icon="download-box-outline"),
                ]
                self.root.ids.fab_button.icon = "plus"

    def on_start(self):
        async def generate_card():
            for i in range(10):
                await asynckivy.sleep(0)
                self.root.ids.card_list.data.append(
                    {
                        "name": fake.name(),
                        "time": fake.date(),
                        "avatar": fake.image_url(),
                        "text": fake.text(),
                        "selected": False,
                        "callback": self.on_tap_card,
                    }
                )

        self.on_tap_card()
        fake = Faker()
        Clock.schedule_once(lambda x: asynckivy.start(generate_card()))


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/bottom-app-bar-m3-style-4.gif

API break#

1.2.0 version#

MDTopAppBar:
    type_height: "large"
    headline_text: "Headline"
    left_action_items: [["arrow-left", lambda x: x]]
    right_action_items:
        [             ["attachment", lambda x: x],             ["calendar", lambda x: x],             ["dots-vertical", lambda x: x],             ]
    anchor_title: "left"

2.0.0 version#

MDTopAppBar:
    type: "large"

    MDTopAppBarLeadingButtonContainer:

        MDActionTopAppBarButton:
            icon: "arrow-left"

    MDTopAppBarTitle:
        text: "AppBar small"

    MDTopAppBarTrailingButtonContainer:

        MDActionTopAppBarButton:
            icon: "attachment"

        MDActionTopAppBarButton:
            icon: "calendar"

        MDActionTopAppBarButton:
            icon: "dots-vertical"

API - kivymd.uix.appbar.appbar#

class kivymd.uix.appbar.appbar.MDFabBottomAppBarButton(**kwargs)#

Implements a floating action button (FAB) for a bar with type ‘bottom’.

For more information, see in the MDFabButton and RotateBehavior and ScaleBehavior and classes documentation.

class kivymd.uix.appbar.appbar.MDActionTopAppBarButton(**kwargs)#

Implements action buttons on the bar.

For more information, see in the MDIconButton class documentation.

md_bg_color_disabled#

The background color in (r, g, b, a) or string format of the button when the button is disabled.

md_bg_color_disabled is a ColorProperty and defaults to None.

class kivymd.uix.appbar.appbar.MDActionBottomAppBarButton(**kwargs)#

Implements action buttons for a :class:’~kivymd.uix.appbar.appbar.MDBottomAppBar’ class.

Added in version 1.2.0.

For more information, see in the MDActionTopAppBarButton class documentation.

class kivymd.uix.appbar.appbar.MDTopAppBarTitle(*args, **kwargs)#

Implements the panel title.

Added in version 2.0.0.

For more information, see in the MDLabel class documentation.

class kivymd.uix.appbar.appbar.MDTopAppBarLeadingButtonContainer(*args, **kwargs)#

Implements a container for the leading action buttons.

Added in version 2.0.0.

For more information, see in the DeclarativeBehavior and BoxLayout classes documentation.

class kivymd.uix.appbar.appbar.MDTopAppBarTrailingButtonContainer(*args, **kwargs)#

Implements a container for the trailing action buttons.

Added in version 2.0.0.

For more information, see in the DeclarativeBehavior and BoxLayout classes documentation.

class kivymd.uix.appbar.appbar.MDTopAppBar(*args, **kwargs)#

Top app bar class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and CommonElevationBehavior and BackgroundColorBehavior and BoxLayout and WindowController classes documentation.

Events:
on_action_button

Method for the button used for the MDBottomAppBar class.

set_bars_color#

If True the background color of the bar status will be set automatically according to the current color of the bar.

Added in version 1.0.0.

See set_bars_colors for more information.

set_bars_color is an BooleanProperty and defaults to False.

type#

Bar height type.

Added in version 1.0.0.

Available options are: ‘medium’, ‘large’, ‘small’.

type_height is an OptionProperty and defaults to ‘small’.

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.

Added 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.

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

Bottom app bar class.

For more information, see in the DeclarativeBehavior and ThemableBehavior and BackgroundColorBehavior and CommonElevationBehavior and FloatLayout classes documentation.

Events:
on_show_bar

The method is fired when the MDBottomAppBar panel is shown.

on_hide_bar

The method is fired when the MDBottomAppBar panel is hidden.

action_items#

The icons on the left bar.

Added in version 1.2.0.

action_items is an ListProperty and defaults to [].

animation#

# TODO: add description. # FIXME: changing the value does not affect anything.

Added in version 1.2.0.

animation is an BooleanProperty and defaults to True.

show_transition#

Type of button display transition.

Added in version 1.2.0.

show_transition is a StringProperty and defaults to ‘linear’.

hide_transition#

Type of button hidden transition.

Added in version 1.2.0.

hide_transition is a StringProperty and defaults to ‘in_back’.

hide_duration#

Duration of button hidden transition.

Added in version 1.2.0.

hide_duration is a NumericProperty and defaults to 0.2.

show_duration#

Duration of button display transition.

Added in version 1.2.0.

show_duration is a NumericProperty and defaults to 0.2.

scroll_cls#

Widget inherited from the ScrollView class. The value must be set if the allow_hidden parameter is True.

Added in version 1.2.0.

scroll_cls is a ObjectProperty and defaults to None.

allow_hidden#

Allows or disables hiding the panel when scrolling content. If the value is True, the scroll_cls parameter must be specified.

Added in version 1.2.0.

allow_hidden is a BooleanProperty and defaults to False.

bar_is_hidden#

Is the panel currently hidden.

Added in version 1.2.0.

bar_is_hidden is a BooleanProperty and defaults to False.

button_centering_animation(button: MDActionBottomAppBarButton | MDFabBottomAppBarButton) → None#

Animation of centering buttons for MDActionOverFlowButton, MDActionBottomAppBarButton and MDFabBottomAppBarButton classes.

check_scroll_direction(scroll_cls, y: float) → None#

Checks the scrolling direction. Depending on the scrolling direction, hides or shows the MDBottomAppBar panel.

show_bar() → None#

Show MDBottomAppBar panel.

hide_bar() → None#

Hide MDBottomAppBar panel.

on_show_bar(*args) → None#

The method is fired when the MDBottomAppBar panel is shown.

on_hide_bar(*args) → None#

The method is fired when the MDBottomAppBar panel is hidden.

on_scroll_cls(instance, scroll_cls) → None#

Fired when the value of the scroll_cls attribute changes.

on_size(*args) → None#

Fired when the root screen is resized.

on_action_items(instance, value: list) → None#

Fired when the value of the action_items attribute changes.

set_fab_opacity(*ars) → None#

Sets the transparency value of the:class:~MDFabBottomAppBarButton button.

set_fab_icon(instance, value) → None#

Animates the size of the MDFabBottomAppBarButton button.

add_widget(widget, index=0, canvas=None)#

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.

Added 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.

Added 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)
Contents