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_open:
Fired when the ModalView is opened.
- on_dismiss:
Fired when the ModalView is closed. If the callback returns True, the dismiss will be canceled.
-
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 anObjectProperty
and defaults to None.
-
auto_dismiss
¶ This property determines if the view is automatically dismissed when the user clicks outside it.
auto_dismiss
is aBooleanProperty
and defaults to True.
-
background
¶ Background image of the view used for the view background.
background
is aStringProperty
and defaults to ‘atlas://data/images/defaulttheme/modalview-background’.
-
background_color
¶ Background color in the format (r, g, b, a).
background_color
is aListProperty
and defaults to [0, 0, 0, .7].
-
border
¶ Border used for
BorderImage
graphics instruction. Used for thebackground_normal
and thebackground_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 aListProperty
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)