ModalView

New in version 1.4.0.

The ModalView widget is used to create modal views. By default, the view will cover the whole “main” window.

Remember that the default size of a Widget is size_hint=(1, 1). If you don’t want your view to be fullscreen, either use size hints with values lower than 1 (for instance size_hint=(.8, .8)) or deactivate the size_hint and use fixed size attributes.

Examples

Example of a simple 400x400 Hello world view:

view = ModalView(size_hint=(None, None), size=(400, 400))
view.add_widget(Label(text='Hello world'))

By default, any click outside the view will dismiss it. If you don’t want that, you can set ModalView.auto_dismiss to False:

view = ModalView(auto_dismiss=False)
view.add_widget(Label(text='Hello world'))
view.open()

To manually dismiss/close the view, use the ModalView.dismiss() method of the ModalView instance:

view.dismiss()

Both ModalView.open() and ModalView.dismiss() are bind-able. That means you can directly bind the function to an action, e.g. to a button’s on_press

# create content and add it to the view
content = Button(text='Close me!')
view = ModalView(auto_dismiss=False)
view.add_widget(content)

# bind the on_press event of the button to the dismiss function
content.bind(on_press=view.dismiss)

# open the view
view.open()

ModalView Events

There are four events available: on_pre_open and on_open which are raised when the view is opening; on_pre_dismiss and on_dismiss which are raised when the view is closed.

For on_dismiss, you can prevent the view from closing by explicitly returning True from your callback:

def my_callback(instance):
    print('ModalView', instance, 'is being dismissed, but is prevented!')
    return True
view = ModalView()
view.add_widget(Label(text='Hello world'))
view.bind(on_dismiss=my_callback)
view.open()

Changed in version 1.5.0: The ModalView can be closed by hitting the escape key on the keyboard if the ModalView.auto_dismiss property is True (the default).

class kivy.uix.modalview.ModalView(**kwargs)

Bases: kivy.uix.anchorlayout.AnchorLayout

ModalView class. See module documentation for more information.

Events:

on_pre_open:

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

on_open:

Fired when the ModalView is opened.

on_pre_dismiss:

Fired before the ModalView is closed.

on_dismiss:

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

Changed in version 1.11.0: Added events on_pre_open and on_pre_dismiss.

Changed in version 2.0.0: Added property ‘overlay_color’.

Changed in version 2.1.0: Marked attach_to property as deprecated.

attach_to

If a widget is set on attach_to, the view will attach to the nearest parent window of the widget. If none is found, it will attach to the main/global Window.

attach_to is an ObjectProperty and defaults to None.

auto_dismiss

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

auto_dismiss is a BooleanProperty and defaults to True.

background

Background image of the view used for the view background.

background is a StringProperty and defaults to ‘atlas://data/images/defaulttheme/modalview-background’.

background_color

Background color, in the format (r, g, b, a).

This acts as a multiplier to the texture colour. The default texture is grey, so just setting the background color will give a darker result. To set a plain color, set the background_normal to ''.

The background_color is a ColorProperty and defaults to [1, 1, 1, 1].

Changed in version 2.0.0: Changed behavior to affect the background of the widget itself, not the overlay dimming. Changed from ListProperty to ColorProperty.

border

Border used for BorderImage graphics instruction. Used for the background_normal and the background_down properties. Can be used when using custom backgrounds.

It must be a list of four values: (bottom, right, top, left). Read the BorderImage instructions for more information about how to use it.

border is a ListProperty and defaults to (16, 16, 16, 16).

dismiss(*_args, **kwargs)

Close the view if it is open.

If you really want to close the view, whatever the on_dismiss event returns, you can use the force keyword argument:

view = ModalView()
view.dismiss(force=True)

When the view is dismissed, it will be faded out before being removed from the parent. If you don’t want this animation, use:

view.dismiss(animation=False)

on__anim_alpha(_instance, value)

animation progress callback.

on_dismiss()

default dismiss event handler.

on_motion(etype, me)

Called when a motion event is received.

Parameters:

etype: str

Event type, one of “begin”, “update” or “end”

me: MotionEvent

Received motion event

Returns:

bool True to stop event dispatching

New in version 2.1.0.

Warning

This is an experimental method and it remains so while this warning is present.

on_open()

default open event handler.

on_pre_dismiss()

default pre-dismiss event handler.

on_pre_open()

default pre-open event handler.

on_touch_down(touch)

touch down event handler.

on_touch_move(touch)

touch moved event handler.

on_touch_up(touch)

touch up event handler.

open(*_args, **kwargs)

Display the modal in the Window.

When the view is opened, it will be faded in with an animation. If you don’t want the animation, use:

view.open(animation=False)

overlay_color

Overlay color in the format (r, g, b, a). Used for dimming the window behind the modal view.

overlay_color is a ColorProperty and defaults to [0, 0, 0, .7].

New in version 2.0.0.