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

    MDTopAppBar:
        id: toolbar
        title: "Example Banners"
        elevation: 4
        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()

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

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

Implements the creation and addition of child widgets as declarative programming style.

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])