Dialog#
#
See also
Dialogs provide important prompts in a user flow.
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#
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()
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):
super().on_start()
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()
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):
super().on_start()
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()
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):
super().on_start()
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()
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):
super().on_start()
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()
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):
super().on_start()
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()
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):
super().on_start()
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()
API - kivymd.uix.dialog.dialog
#
- class kivymd.uix.dialog.dialog.MDDialog(*args, **kwargs)#
Dialog class.
For more information, see in the
MDCard
andMotionDialogBehavior
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 anNumericProperty
and defaults to dp(48).
- radius#
Dialog corners rounding value.
radius
is anVariableListProperty
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 aColorProperty
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 aBooleanProperty
and defaults to True.
- 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.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
- 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.
- touch:
- 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.
- 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
andBoxLayout
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
andBoxLayout
classes documentation.