Banner

See also

Material Design spec, Banner

A banner displays a prominent message and related optional actions.

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}

    BoxLayout:
        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()

Banner type.

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

MDBanner:
    text: ["One line string text example without actions."]

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."]

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."]

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]

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_logo.png"
    text: ["One line string text example without actions."]

Note

See full example

API - kivymd.uix.banner

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

Widget class. See module documentation for more information.

Events

on_touch_down: (touch, )

Fired when a new touch event occurs. touch is the touch object.

on_touch_move: (touch, )

Fired when an existing touch moves. touch is the touch object.

on_touch_up: (touch, )

Fired when an existing touch disappears. touch is the touch object.

on_kv_post: (base_widget, )

Fired after all the kv rules associated with the widget and all other widgets that are in any of those rules have had all their kv rules applied. base_widget is the base-most widget whose instantiation triggered the kv rules (i.e. the widget instantiated from Python, e.g. MyWidget()).

Changed in version 1.11.0.

Warning

Adding a __del__ method to a class derived from Widget with Python prior to 3.4 will disable automatic garbage collection for instances of that class. This is because the Widget class creates reference cycles, thereby preventing garbage collection.

Changed in version 1.0.9: Everything related to event properties has been moved to the EventDispatcher. Event properties can now be used when contructing a simple class without subclassing Widget.

Changed in version 1.5.0: The constructor now accepts on_* arguments to automatically bind callbacks to properties or events, as in the Kv language.

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

add_actions_buttons(self, box, data)

set_left_action(self)

set_right_action(self)

set_type_banner(self)

add_banner_to_container(self)

show(self)

animation_display_banner(self, i)

hide(self)