Dialog#

#

See also

Material Design spec, Dialogs

Dialogs provide important prompts in a user flow.

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

  • Use dialogs to make sure users act on information

  • Two types: basic and full-screen (full-screen not provided in KivyMD)

  • Should be dedicated to completing a single task

  • Can also display information relevant to the task

  • Commonly used to confirm high-risk actions like deleting progress

Anatomy#

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

Example#

from kivy.lang import Builder
from kivy.uix.widget import Widget

from kivymd.app import MDApp
from kivymd.uix.button import MDButton, MDButtonText
from kivymd.uix.dialog import (
    MDDialog,
    MDDialogIcon,
    MDDialogHeadlineText,
    MDDialogSupportingText,
    MDDialogButtonContainer,
    MDDialogContentContainer,
)
from kivymd.uix.divider import MDDivider
from kivymd.uix.list import (
    MDListItem,
    MDListItemLeadingIcon,
    MDListItemSupportingText,
)

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

    MDButton:
        pos_hint: {'center_x': .5, 'center_y': .5}
        on_release: app.show_alert_dialog()

        MDButtonText:
            text: "Show dialog"
'''


class Example(MDApp):
    def build(self):
        return Builder.load_string(KV)

    def show_alert_dialog(self):
        MDDialog(
            # ----------------------------Icon-----------------------------
            MDDialogIcon(
                icon="refresh",
            ),
            # -----------------------Headline text-------------------------
            MDDialogHeadlineText(
                text="Reset settings?",
            ),
            # -----------------------Supporting text-----------------------
            MDDialogSupportingText(
                text="This will reset your app preferences back to their "
                "default settings. The following accounts will also "
                "be signed out:",
            ),
            # -----------------------Custom content------------------------
            MDDialogContentContainer(
                MDDivider(),
                MDListItem(
                    MDListItemLeadingIcon(
                        icon="gmail",
                    ),
                    MDListItemSupportingText(
                        text="KivyMD-library@yandex.com",
                    ),
                    theme_bg_color="Custom",
                    md_bg_color=self.theme_cls.transparentColor,
                ),
                MDListItem(
                    MDListItemLeadingIcon(
                        icon="gmail",
                    ),
                    MDListItemSupportingText(
                        text="kivydevelopment@gmail.com",
                    ),
                    theme_bg_color="Custom",
                    md_bg_color=self.theme_cls.transparentColor,
                ),
                MDDivider(),
                orientation="vertical",
            ),
            # ---------------------Button container------------------------
            MDDialogButtonContainer(
                Widget(),
                MDButton(
                    MDButtonText(text="Cancel"),
                    style="text",
                ),
                MDButton(
                    MDButtonText(text="Accept"),
                    style="text",
                ),
                spacing="8dp",
            ),
            # -------------------------------------------------------------
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dialog-example.gif

Warning

Do not try to use the MDDialog widget in KV files.

API break#

1.2.0 version#

from kivy.uix.widget import Widget

from kivymd.app import MDApp
from kivymd.uix.button import MDFlatButton
from kivymd.uix.dialog import MDDialog


class Example(MDApp):
    def build(self):
        return Widget()

    def on_start(self):
        MDDialog(
            title="Discard draft?",
            buttons=[
                MDFlatButton(
                    text="CANCEL",
                    theme_text_color="Custom",
                    text_color=self.theme_cls.primary_color,
                ),
                MDFlatButton(
                    text="DISCARD",
                    theme_text_color="Custom",
                    text_color=self.theme_cls.primary_color,
                ),
            ],
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dialog-api-break-1-2-0.png 
from kivy.uix.widget import Widget

from kivymd.app import MDApp
from kivymd.uix.button import MDFlatButton
from kivymd.uix.dialog import MDDialog


class Example(MDApp):
    def build(self):
        return Widget()

    def on_start(self):
        MDDialog(
            title="Discard draft?",
            text="This will reset your device to its default factory settings.",
            buttons=[
                MDFlatButton(
                    text="CANCEL",
                    theme_text_color="Custom",
                    text_color=self.theme_cls.primary_color,
                ),
                MDFlatButton(
                    text="DISCARD",
                    theme_text_color="Custom",
                    text_color=self.theme_cls.primary_color,
                ),
            ],
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/2-dialog-api-break-1-2-0.png 
from kivy.lang import Builder
from kivy.properties import StringProperty
from kivy.uix.widget import Widget

from kivymd import images_path
from kivymd.app import MDApp
from kivymd.uix.dialog import MDDialog
from kivymd.uix.list import OneLineAvatarListItem

KV = '''
<Item>

    ImageLeftWidget:
        source: root.source
'''


class Item(OneLineAvatarListItem):
    divider = None
    source = StringProperty()


class Example(MDApp):
    def build(self):
        Builder.load_string(KV)
        return Widget()

    def on_start(self):
        MDDialog(
            title="Set backup account",
            type="simple",
            items=[
                Item(text="user01@gmail.com", source=f"{images_path}/logo/kivymd-icon-128.png"),
                Item(text="user02@gmail.com", source="data/logo/kivy-icon-128.png"),
            ],
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/3-dialog-api-break-1-2-0.png

2.2.0 version#

from kivy.uix.widget import Widget

from kivymd.uix.widget import MDWidget
from kivymd.app import MDApp
from kivymd.uix.button import MDButton, MDButtonText
from kivymd.uix.dialog import MDDialog, MDDialogHeadlineText, MDDialogButtonContainer


class Example(MDApp):
    def build(self):
        return MDWidget(md_bg_color=self.theme_cls.backgroundColor)

    def on_start(self):
        MDDialog(
            MDDialogHeadlineText(
                text="Discard draft?",
                halign="left",
            ),
            MDDialogButtonContainer(
                Widget(),
                MDButton(
                    MDButtonText(text="Cancel"),
                    style="text",
                ),
                MDButton(
                    MDButtonText(text="Discard"),
                    style="text",
                ),
                spacing="8dp",
            ),
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/dialog-api-break-2-2-0.png 
from kivy.uix.widget import Widget

from kivymd.uix.widget import MDWidget
from kivymd.app import MDApp
from kivymd.uix.button import MDButton, MDButtonText
from kivymd.uix.dialog import MDDialog, MDDialogHeadlineText, MDDialogButtonContainer


class Example(MDApp):
    def build(self):
        return MDWidget(md_bg_color=self.theme_cls.backgroundColor)

    def on_start(self):
        MDDialog(
            MDDialogHeadlineText(
                text="Discard draft?",
                halign="left",
            ),
            MDDialogSupportingText(
                text="This will reset your device to its default factory settings.",
                halign="left",
            ),
            MDDialogButtonContainer(
                Widget(),
                MDButton(
                    MDButtonText(text="Cancel"),
                    style="text",
                ),
                MDButton(
                    MDButtonText(text="Discard"),
                    style="text",
                ),
                spacing="8dp",
            ),
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/2-dialog-api-break-2-2-0.png 
from kivymd import images_path
from kivymd.uix.widget import MDWidget
from kivymd.app import MDApp
from kivymd.uix.dialog import (
    MDDialog,
    MDDialogHeadlineText,
    MDDialogContentContainer,
)
from kivymd.uix.list import (
    MDListItem,
    MDListItemLeadingAvatar,
    MDListItemSupportingText,
)


class Example(MDApp):
    def build(self):
        return MDWidget(md_bg_color=self.theme_cls.backgroundColor)

    def on_start(self):
        MDDialog(
            MDDialogHeadlineText(
                text="Set backup account",
                halign="left",
            ),
            MDDialogContentContainer(
                MDListItem(
                    MDListItemLeadingAvatar(
                        source=f"{images_path}/logo/kivymd-icon-128.png",
                    ),
                    MDListItemSupportingText(
                        text="user01@gmail.com",
                    ),
                    theme_bg_color="Custom",
                    md_bg_color=self.theme_cls.transparentColor,
                ),
                MDListItem(
                    MDListItemLeadingAvatar(
                        source="data/logo/kivy-icon-128.png",
                    ),
                    MDListItemSupportingText(
                        text="user01@gmail.com",
                    ),
                    theme_bg_color="Custom",
                    md_bg_color=self.theme_cls.transparentColor,
                ),
                orientation="vertical",
            ),
        ).open()


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/3-dialog-api-break-2-2-0.png

API - kivymd.uix.dialog.dialog#

class kivymd.uix.dialog.dialog.MDDialog(*args, **kwargs)#

Dialog class.

For more information, see in the MDCard and MotionDialogBehavior classes documentation.

Events:
on_pre_open:

Fired before the MDDialog is opened. When this event is fired MDDialog is not yet added to window.

on_open:

Fired when the MDDialog is opened.

on_pre_dismiss:

Fired before the MDDialog is closed.

on_dismiss:

Fired when the MDDialog is closed. If the callback returns True, the dismiss will be canceled.

width_offset#

Dialog offset from device width.

width_offset is an NumericProperty and defaults to dp(48).

radius#

Dialog corners rounding value.

radius is an VariableListProperty and defaults to [dp(28), dp(28), dp(28), dp(28)].

scrim_color#

Color for scrim in (r, g, b, a) or string format.

scrim_color is a ColorProperty and defaults to [0, 0, 0, 0.5].

auto_dismiss#

This property determines if the dialog is automatically dismissed when the user clicks outside it.

..versionadded:: 2.0.0

auto_dismiss is a BooleanProperty and defaults to True.

update_width(*args) → None#
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.

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

New 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)
open() → None#

Show the dialog.

on_pre_open(*args) → None#

Fired when a dialog pre opened.

on_open(*args) → None#

Fired when a dialog opened.

on_dismiss(*args) → None#

Fired when a dialog dismiss.

on_pre_dismiss(*args) → None#

Fired when a dialog pre-dismiss.

on_touch_down(touch)#

Receive a touch down event.

Parameters:
touch: MotionEvent class

Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

dismiss(*args) → None#

Closes the dialog.

class kivymd.uix.dialog.dialog.MDDialogIcon(*args, **kwargs)#

The class implements an icon.

For more information, see in the MDIcon class documentation.

class kivymd.uix.dialog.dialog.MDDialogHeadlineText(*args, **kwargs)#

The class implements the headline text.

For more information, see in the MDLabel class documentation.

class kivymd.uix.dialog.dialog.MDDialogSupportingText(*args, **kwargs)#

The class implements the supporting text.

For more information, see in the MDLabel class documentation.

class kivymd.uix.dialog.dialog.MDDialogContentContainer(*args, **kwargs)#

The class implements the container for custom widgets.

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

class kivymd.uix.dialog.dialog.MDDialogButtonContainer(*args, **kwargs)#

The class implements a container for placing dialog buttons.

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