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

Note

See full example

API - kivymd.uix.banner

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

FakeRectangularElevationBehavio`r is a shadow mockup for widgets. Improves performance using cached images inside `kivymd.images dir

This class cast a fake Rectangular shadow behaind the widget.

You can either use this behavior to overwrite the elevation of a prefab widget, or use it directly inside a new widget class definition.

Use this class as follows for new widgets:

class NewWidget(
    ThemableBehavior,
    FakeCircularElevationBehavior,
    SpecificBackgroundColorBehavior,
    # here you add the other front end classes for the widget front_end,
):
    [...]

With this method each class can draw it’s content in the canvas in the correct order, avoiding some visual errors.

FakeCircularElevationBehavior will load prefabricated textures to optimize loading times.

Also, this class allows you to overwrite real time shadows, in the sence that if you are using a standard widget, like a button, MDCard or Toolbar, you can include this class after the base class to optimize the loading times.

As an example of this flexibility:

class Custom_rectangular_Card(
    MDCard,
    FakeRectangularElevationBehavior
):
    [...]

Note

About rounded corners: be careful, since this behavior is a mockup and will not draw any rounded corners.

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)