Version

Quick search

Table Of Contents

Source code for kivy.uix.popup

'''
Popup
=====

.. versionadded:: 1.0.7

.. image:: images/popup.jpg
    :align: right

The :class:`Popup` widget is used to create modal popups. By default, the popup
will cover the whole "parent" window. When you are creating a popup, you
must at least set a :attr:`Popup.title` and :attr:`Popup.content`.

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


.. versionchanged:: 1.4.0
    The :class:`Popup` class now inherits from
    :class:`~kivy.uix.modalview.ModalView`. The :class:`Popup` offers a default
    layout with a title and a separation bar.

Examples
--------

Example of a simple 400x400 Hello world popup::

    popup = Popup(title='Test popup',
        content=Label(text='Hello world'),
        size_hint=(None, None), size=(400, 400))

By default, any click outside the popup will dismiss/close it. If you don't
want that, you can set
:attr:`~kivy.uix.modalview.ModalView.auto_dismiss` to False::

    popup = Popup(title='Test popup', content=Label(text='Hello world'),
                  auto_dismiss=False)
    popup.open()

To manually dismiss/close the popup, use
:attr:`~kivy.uix.modalview.ModalView.dismiss`::

    popup.dismiss()

Both :meth:`~kivy.uix.modalview.ModalView.open` and
:meth:`~kivy.uix.modalview.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 to the popup
    content = Button(text='Close me!')
    popup = Popup(content=content, auto_dismiss=False)

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

    # open the popup
    popup.open()

Same thing in KV language only with :class:`Factory`:

.. code-block:: kv

    #:import Factory kivy.factory.Factory
    <MyPopup@Popup>:
        auto_dismiss: False
        Button:
            text: 'Close me!'
            on_release: root.dismiss()

    Button:
        text: 'Open popup'
        on_release: Factory.MyPopup().open()

.. note::

    Popup is a special widget. Don't try to add it as a child to any other
    widget. If you do, Popup will be handled like an ordinary widget and
    won't be created hidden in the background.

    .. code-block:: kv

        BoxLayout:
            MyPopup:  # bad!

Popup Events
------------

There are two events available: `on_open` which is raised when the popup is
opening, and `on_dismiss` which is raised when the popup is closed.
For `on_dismiss`, you can prevent the
popup from closing by explictly returning True from your callback::

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

'''

__all__ = ('Popup', 'PopupException')

from kivy.core.text import DEFAULT_FONT
from kivy.uix.modalview import ModalView
from kivy.properties import (StringProperty, ObjectProperty, OptionProperty,
                             NumericProperty, ListProperty)


[docs]class PopupException(Exception): '''Popup exception, fired when multiple content widgets are added to the popup. .. versionadded:: 1.4.0 '''
if __name__ == '__main__': from kivy.base import runTouchApp from kivy.uix.button import Button from kivy.uix.label import Label from kivy.uix.gridlayout import GridLayout from kivy.core.window import Window # add popup content = GridLayout(cols=1) content_cancel = Button(text='Cancel', size_hint_y=None, height=40) content.add_widget(Label(text='This is a hello world')) content.add_widget(content_cancel) popup = Popup(title='Test popup', size_hint=(None, None), size=(256, 256), content=content, disabled=True) content_cancel.bind(on_release=popup.dismiss) layout = GridLayout(cols=3) for x in range(9): btn = Button(text=str(x)) btn.bind(on_release=popup.open) layout.add_widget(btn) Window.add_widget(layout) popup.open() runTouchApp()