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)[source]¶

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 color. 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)[source]¶

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)[source]¶: animation progress callback.

on_dismiss()[source]¶: default dismiss event handler.

on_motion(etype, me)[source]¶

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()[source]¶: default open event handler.

on_pre_dismiss()[source]¶: default pre-dismiss event handler.

on_pre_open()[source]¶: default pre-open event handler.

on_touch_down(touch)[source]¶: touch down event handler.

on_touch_move(touch)[source]¶: touch moved event handler.

on_touch_up(touch)[source]¶: touch up event handler.

open(*_args, **kwargs)[source]¶

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.

« Layout

PageLayout »

Version

Quick search

Table Of Contents

ModalView¶

Examples¶

ModalView Events¶