Version

Quick search

 

Table Of Contents

ModalView

New in version 1.4.0.

The ModalView widget is used to create modal views. By default, the view will cover the whole “parent” 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 bindable. 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 two events available: on_open which is raised when the view is opening, and on_dismiss which is raised when the view is closed. For on_dismiss, you can prevent the view from closing by explictly 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’.

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(*largs, **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 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 animation, use:

view.dismiss(animation=False)
on_touch_down(touch)[source]

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.

on_touch_move(touch)[source]

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_up(touch)[source]

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

open(*largs, **kwargs)[source]

Show the view window from the attach_to widget. If set, it will attach to the nearest window. If the widget is not attached to any window, the view will attach to the global 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 »