Modal (submodule)

The asynckivy.modal submodule provides an easy way to display modal dialogs in Kivy applications. Unlike kivy.uix.modalview:

• You can use any widget as a modal dialog. (ModalView is not required.)

• Consequently, you have full control over the dialog’s appearance and transitions.

from asynckivy import modal

async with modal.open(any_widget):
    ...

If you leave the with-block empty, the dialog will be dismissed immediately — which is probably not what you want. To keep it open, you must prevent the with-block from exiting. For example:

async with modal.open(any_widget):
    await ak.event(any_widget.ids.close_button, 'on_release')

A close button is not required for a dialog to work. The user can still dismiss the dialog by touching outside of it, pressing the Escape key or pressing the Android back button — unless auto_dismiss is set to False.

# This is totally fine.
async with modal.open(any_widget):
    await ak.sleep_forever()

# This may not be fine, depending on the situation.
async with modal.open(any_widget, auto_dismiss=False):
    await ak.sleep_forever()

API Reference

class FadeTransition(*, in_duration=0.1, out_duration=0.1, background_color=(0.0, 0.0, 0.0, 0.8))

from asynckivy import modal

async with modal.open(widget, transition=modal.FadeTransition(...)):
    ...

class SlideTransition(*, in_duration=0.2, out_duration=0.2, background_color=(0.0, 0.0, 0.0, 0.8), in_curve='out_back', out_curve='in_back', in_direction: Literal['left', 'right', 'down', 'up'] = 'down', out_direction: Literal['left', 'right', 'down', 'up'] = 'up')

from asynckivy import modal

async with modal.open(widget, transition=modal.SlideTransition(...)):
    ...

no_transition(dialog: kivy.uix.widget.Widget, parent: kivy.uix.floatlayout.FloatLayout, window: kivy.core.window.WindowBase)

from asynckivy import modal

async with modal.open(widget, transition=modal.no_transition):
    ...

open(dialog: kivy.uix.widget.Widget, *, window: kivy.core.window.WindowBase = kivy.core.window.Window, auto_dismiss=True, transition: ~collections.abc.Callable[[kivy.uix.widget.Widget, kivy.uix.floatlayout.FloatLayout, kivy.core.window.WindowBase], ~contextlib.AbstractAsyncContextManager] = <asynckivy.modal.FadeTransition object>, _cache=[]) → AsyncIterator[StatefulEvent]

Returns an async context manager that displays the given widget as a modal dialog.

Parameters:

• dialog – The widget to display as a dialog.

• window – The window in which to display the dialog.

• auto_dismiss – Whether to dismiss the dialog when the user touches outside it or presses the escape key or the Android back button.

• transition – The transition effect to use when opening and dismissing the dialog.

You can check whether the dialog was auto-dismissed and determine the cause as follows:

async with open(dialog) as auto_dismiss_event:
    ...
if auto_dismiss_event.is_fired:
    print("The dialog was auto-dismissed")

    # 'outside_touch', 'escape_key' or 'back_button'
    cause_of_dismissal = auto_dismiss_event.params[1]['cause']