Banner

A banner displays a prominent message and related optional actions.

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

Usage

from kivy.lang import Builder
from kivy.factory import Factory

from kivymd.app import MDApp

Builder.load_string('''
<ExampleBanner@Screen>

    MDBanner:
        id: banner
        text: ["One line string text example without actions."]
        # The widget that is under the banner.
        # It will be shifted down to the height of the banner.
        over_widget: screen
        vertical_pad: toolbar.height

    MDToolbar:
        id: toolbar
        title: "Example Banners"
        elevation: 10
        pos_hint: {'top': 1}

    MDBoxLayout:
        id: screen
        orientation: "vertical"
        size_hint_y: None
        height: Window.height - toolbar.height

        OneLineListItem:
            text: "Banner without actions"
            on_release: banner.show()

        Widget:
''')


class Test(MDApp):
    def build(self):
        return Factory.ExampleBanner()


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/banner-example-1.gif

Banner type.

By default, the banner is of the type 'one-line':

MDBanner:
    text: ["One line string text example without actions."]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/banner-one-line.png

To use a two-line banner, specify the 'two-line' MDBanner.type for the banner and pass the list of two lines to the MDBanner.text parameter:

MDBanner:
    type: "two-line"
    text:
        ["One line string text example without actions.", "This is the second line of the banner message."]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/banner-two-line.png

Similarly, create a three-line banner:

MDBanner:
    type: "three-line"
    text:
        ["One line string text example without actions.", "This is the second line of the banner message.", "and this is the third line of the banner message."]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/banner-three-line.png

To add buttons to any type of banner, use the MDBanner.left_action and MDBanner.right_action parameters, which should take a list [‘Button name’, function]:

MDBanner:
    text: ["One line string text example without actions."]
    left_action: ["CANCEL", lambda x: None]

Or two buttons:

MDBanner:
    text: ["One line string text example without actions."]
    left_action: ["CANCEL", lambda x: None]
    right_action: ["CLOSE", lambda x: None]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/banner-actions.png

If you want to use the icon on the left in the banner, add the prefix ‘-icon’ to the banner type:

MDBanner:
    type: "one-line-icon"
    icon: f"{images_path}/kivymd.png"
    text: ["One line string text example without actions."]
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/banner-icon.png

API - kivymd.uix.banner.banner

class kivymd.uix.banner.banner.MDBanner(**kwargs)

Common base class for rectangular and circular elevation behavior.

vertical_pad

Indent the banner at the top of the screen.

vertical_pad is an NumericProperty and defaults to dp(68).

opening_transition

The name of the animation transition.

opening_transition is an StringProperty and defaults to ‘in_quad’.

icon

Icon banner.

icon is an StringProperty and defaults to ‘data/logo/kivy-icon-128.png’.

over_widget

The widget that is under the banner. It will be shifted down to the height of the banner.

over_widget is an ObjectProperty and defaults to None.

text

List of lines for banner text. Must contain no more than three lines for a ‘one-line’, ‘two-line’ and ‘three-line’ banner, respectively.

text is an ListProperty and defaults to [].

left_action

The action of banner.

To add one action, make a list [‘name_action’, callback] where ‘name_action’ is a string that corresponds to an action name and callback is the function called on a touch release event.

left_action is an ListProperty and defaults to [].

right_action

Works the same way as left_action.

right_action is an ListProperty and defaults to [].

type

Banner type. . Available options are: (“one-line”, “two-line”, “three-line”, “one-line-icon”, “two-line-icon”, “three-line-icon”).

type is an OptionProperty and defaults to ‘one-line’.

opening_timeout

Time interval after which the banner will be shown.

New in version 1.0.0.

opening_timeout is an BoundedNumericProperty and defaults to 0.7.

opening_time

The time taken for the banner to slide to the state ‘open’.

New in version 1.0.0.

opening_time is a NumericProperty and defaults to 0.15.

closing_time

The time taken for the banner to slide to the state ‘close’.

New in version 1.0.0.

closing_time is a NumericProperty and defaults to 0.15.

add_actions_buttons(self, instance_box: MDBoxLayout, data: list)

Adds buttons to the banner.

Parameters

data – [‘NAME BUTTON’, <function>];

show(self)

Displays a banner on the screen.

hide(self)

Hides the banner from the screen.

set_type_banner(self)
animation_display_banner(self, interval: Union[int, float])