Kivy-examples 2.3.1.dev0__py3-none-any.whl

kivy/uix/pagelayout.py

@@ -0,0 +1,233 @@
+"""
+PageLayout
+==========
+
+.. image:: images/pagelayout.gif
+    :align: right
+
+The :class:`PageLayout` class is used to create a simple multi-page
+layout, in a way that allows easy flipping from one page to another using
+borders.
+
+:class:`PageLayout` does not currently honor the
+:attr:`~kivy.uix.widget.Widget.size_hint`,
+:attr:`~kivy.uix.widget.Widget.size_hint_min`,
+:attr:`~kivy.uix.widget.Widget.size_hint_max`, or
+:attr:`~kivy.uix.widget.Widget.pos_hint` properties.
+
+.. versionadded:: 1.8.0
+
+Example:
+
+.. code-block:: kv
+
+    PageLayout:
+        Button:
+            text: 'page1'
+        Button:
+            text: 'page2'
+        Button:
+            text: 'page3'
+
+Transitions from one page to the next are made by swiping in from the border
+areas on the right or left hand side. If you wish to display multiple widgets
+in a page, we suggest you use a containing layout. Ideally, each page should
+consist of a single :mod:`~kivy.uix.layout` widget that contains the remaining
+widgets on that page.
+"""
+
+__all__ = ('PageLayout', )
+
+from kivy.uix.layout import Layout
+from kivy.properties import NumericProperty, DictProperty
+from kivy.animation import Animation
+
+
+class PageLayout(Layout):
+    '''PageLayout class. See module documentation for more information.
+    '''
+
+    page = NumericProperty(0)
+    '''The currently displayed page.
+
+    :data:`page` is a :class:`~kivy.properties.NumericProperty` and defaults
+    to 0.
+    '''
+
+    border = NumericProperty('50dp')
+    '''The width of the border around the current page used to display
+    the previous/next page swipe areas when needed.
+
+    :data:`border` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 50dp.
+    '''
+
+    swipe_threshold = NumericProperty(.5)
+    '''The threshold used to trigger swipes as ratio of the widget
+    size.
+
+    :data:`swipe_threshold` is a :class:`~kivy.properties.NumericProperty`
+    and defaults to .5.
+    '''
+
+    anim_kwargs = DictProperty({'d': .5, 't': 'in_quad'})
+    '''The animation kwargs used to construct the animation
+
+    :data:`anim_kwargs` is a :class:`~kivy.properties.DictProperty`
+    and defaults to {'d': .5, 't': 'in_quad'}.
+
+    .. versionadded:: 1.11.0
+    '''
+
+    def __init__(self, **kwargs):
+        super(PageLayout, self).__init__(**kwargs)
+
+        trigger = self._trigger_layout
+        fbind = self.fbind
+        fbind('border', trigger)
+        fbind('page', trigger)
+        fbind('parent', trigger)
+        fbind('children', trigger)
+        fbind('size', trigger)
+        fbind('pos', trigger)
+
+    def do_layout(self, *largs):
+        l_children = len(self.children) - 1
+        h = self.height
+        x_parent, y_parent = self.pos
+        p = self.page
+        border = self.border
+        half_border = border / 2.
+        right = self.right
+        width = self.width - border
+        for i, c in enumerate(reversed(self.children)):
+
+            if i < p:
+                x = x_parent
+            elif i == p:
+                if not p:  # it's first page
+                    x = x_parent
+                elif p != l_children:  # not first, but there are post pages
+                    x = x_parent + half_border
+                else:  # not first and there are no post pages
+                    x = x_parent + border
+            elif i == p + 1:
+                if not p:  # second page - no left margin
+                    x = right - border
+                else:  # there's already a left margin
+                    x = right - half_border
+            else:
+                x = right
+
+            c.height = h
+            c.width = width
+
+            Animation(
+                x=x,
+                y=y_parent,
+                **self.anim_kwargs).start(c)
+
+    def on_touch_down(self, touch):
+        if (
+            self.disabled or
+            not self.collide_point(*touch.pos) or
+            not self.children
+        ):
+            return
+
+        page = self.children[-self.page - 1]
+        if self.x <= touch.x < page.x:
+            touch.ud['page'] = 'previous'
+            touch.grab(self)
+            return True
+        elif page.right <= touch.x < self.right:
+            touch.ud['page'] = 'next'
+            touch.grab(self)
+            return True
+        return page.on_touch_down(touch)
+
+    def on_touch_move(self, touch):
+        if touch.grab_current != self:
+            return
+
+        p = self.page
+        border = self.border
+        half_border = border / 2.
+        page = self.children[-p - 1]
+        if touch.ud['page'] == 'previous':
+            # move next page up to right edge
+            if p < len(self.children) - 1:
+                self.children[-p - 2].x = min(
+                    self.right - self.border * (1 - (touch.sx - touch.osx)),
+                    self.right)
+
+            # move current page until edge hits the right border
+            if p >= 1:
+                b_right = half_border if p > 1 else border
+                b_left = half_border if p < len(self.children) - 1 else border
+                self.children[-p - 1].x = max(min(
+                    self.x + b_left + (touch.x - touch.ox),
+                    self.right - b_right),
+                    self.x + b_left)
+
+            # move previous page left edge up to left border
+            if p > 1:
+                self.children[-p].x = min(
+                    self.x + half_border * (touch.sx - touch.osx),
+                    self.x + half_border)
+
+        elif touch.ud['page'] == 'next':
+            # move current page up to left edge
+            if p >= 1:
+                self.children[-p - 1].x = max(
+                    self.x + half_border * (1 - (touch.osx - touch.sx)),
+                    self.x)
+
+            # move next page until its edge hit the left border
+            if p < len(self.children) - 1:
+                b_right = half_border if p >= 1 else border
+                b_left = half_border if p < len(self.children) - 2 else border
+                self.children[-p - 2].x = min(max(
+                    self.right - b_right + (touch.x - touch.ox),
+                    self.x + b_left),
+                    self.right - b_right)
+
+            # move second next page up to right border
+            if p < len(self.children) - 2:
+                self.children[-p - 3].x = max(
+                    self.right + half_border * (touch.sx - touch.osx),
+                    self.right - half_border)
+
+        return page.on_touch_move(touch)
+
+    def on_touch_up(self, touch):
+        if touch.grab_current == self:
+            if (
+                touch.ud['page'] == 'previous' and
+                abs(touch.x - touch.ox) / self.width > self.swipe_threshold
+            ):
+                self.page -= 1
+            elif (
+                touch.ud['page'] == 'next' and
+                abs(touch.x - touch.ox) / self.width > self.swipe_threshold
+            ):
+                self.page += 1
+            else:
+                self._trigger_layout()
+
+            touch.ungrab(self)
+
+        if len(self.children) > 1:
+            return self.children[-self.page + 1].on_touch_up(touch)
+
+
+if __name__ == '__main__':
+    from kivy.base import runTouchApp
+    from kivy.uix.button import Button
+
+    pl = PageLayout()
+    for i in range(1, 4):
+        b = Button(text='page%s' % i)
+        pl.add_widget(b)
+
+    runTouchApp(pl)

kivy/uix/popup.py

@@ -0,0 +1,266 @@
+'''
+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 explicitly 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, ColorProperty)
+
+
+class PopupException(Exception):
+    '''Popup exception, fired when multiple content widgets are added to the
+    popup.
+
+    .. versionadded:: 1.4.0
+    '''
+
+
+class Popup(ModalView):
+    '''Popup class. See module documentation for more information.
+
+    :Events:
+        `on_open`:
+            Fired when the Popup is opened.
+        `on_dismiss`:
+            Fired when the Popup is closed. If the callback returns True, the
+            dismiss will be canceled.
+    '''
+
+    title = StringProperty('No title')
+    '''String that represents the title of the popup.
+
+    :attr:`title` is a :class:`~kivy.properties.StringProperty` and defaults to
+    'No title'.
+    '''
+
+    title_size = NumericProperty('14sp')
+    '''Represents the font size of the popup title.
+
+    .. versionadded:: 1.6.0
+
+    :attr:`title_size` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to '14sp'.
+    '''
+
+    title_align = OptionProperty(
+        'left', options=['left', 'center', 'right', 'justify'])
+    '''Horizontal alignment of the title.
+
+    .. versionadded:: 1.9.0
+
+    :attr:`title_align` is a :class:`~kivy.properties.OptionProperty` and
+    defaults to 'left'. Available options are left, center, right and justify.
+    '''
+
+    title_font = StringProperty(DEFAULT_FONT)
+    '''Font used to render the title text.
+
+    .. versionadded:: 1.9.0
+
+    :attr:`title_font` is a :class:`~kivy.properties.StringProperty` and
+    defaults to 'Roboto'. This value is taken
+    from :class:`~kivy.config.Config`.
+    '''
+
+    content = ObjectProperty(None)
+    '''Content of the popup that is displayed just under the title.
+
+    :attr:`content` is an :class:`~kivy.properties.ObjectProperty` and defaults
+    to None.
+    '''
+
+    title_color = ColorProperty([1, 1, 1, 1])
+    '''Color used by the Title.
+
+    .. versionadded:: 1.8.0
+
+    :attr:`title_color` is a :class:`~kivy.properties.ColorProperty` and
+    defaults to [1, 1, 1, 1].
+
+    .. versionchanged:: 2.0.0
+        Changed from :class:`~kivy.properties.ListProperty` to
+        :class:`~kivy.properties.ColorProperty`.
+    '''
+
+    separator_color = ColorProperty([47 / 255., 167 / 255., 212 / 255., 1.])
+    '''Color used by the separator between title and content.
+
+    .. versionadded:: 1.1.0
+
+    :attr:`separator_color` is a :class:`~kivy.properties.ColorProperty` and
+    defaults to [47 / 255., 167 / 255., 212 / 255., 1.].
+
+    .. versionchanged:: 2.0.0
+        Changed from :class:`~kivy.properties.ListProperty` to
+        :class:`~kivy.properties.ColorProperty`.
+    '''
+
+    separator_height = NumericProperty('2dp')
+    '''Height of the separator.
+
+    .. versionadded:: 1.1.0
+
+    :attr:`separator_height` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 2dp.
+    '''
+
+    # Internal properties used for graphical representation.
+
+    _container = ObjectProperty(None)
+
+    def add_widget(self, widget, *args, **kwargs):
+        if self._container:
+            if self.content:
+                raise PopupException(
+                    'Popup can have only one widget as content')
+            self.content = widget
+        else:
+            super(Popup, self).add_widget(widget, *args, **kwargs)
+
+    def on_content(self, instance, value):
+        if self._container:
+            self._container.clear_widgets()
+            self._container.add_widget(value)
+
+    def on__container(self, instance, value):
+        if value is None or self.content is None:
+            return
+        self._container.clear_widgets()
+        self._container.add_widget(self.content)
+
+    def on_touch_down(self, touch):
+        if self.disabled and self.collide_point(*touch.pos):
+            return True
+        return super(Popup, self).on_touch_down(touch)
+
+
+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()

kivy/uix/progressbar.py

@@ -0,0 +1,95 @@
+'''
+Progress Bar
+============
+
+.. versionadded:: 1.0.8
+
+.. image:: images/progressbar.jpg
+    :align: right
+
+The :class:`ProgressBar` widget is used to visualize the progress of some task.
+Only the horizontal mode is currently supported: the vertical mode is not
+yet available.
+
+The progress bar has no interactive elements and is a display-only widget.
+
+To use it, simply assign a value to indicate the current progress::
+
+    from kivy.uix.progressbar import ProgressBar
+    pb = ProgressBar(max=1000)
+
+    # this will update the graphics automatically (75% done)
+    pb.value = 750
+
+'''
+
+__all__ = ('ProgressBar', )
+
+from kivy.uix.widget import Widget
+from kivy.properties import NumericProperty, AliasProperty
+
+
+class ProgressBar(Widget):
+    '''Class for creating a progress bar widget.
+
+    See module documentation for more details.
+    '''
+
+    def __init__(self, **kwargs):
+        self._value = 0.
+        super(ProgressBar, self).__init__(**kwargs)
+
+    def _get_value(self):
+        return self._value
+
+    def _set_value(self, value):
+        value = max(0, min(self.max, value))
+        if value != self._value:
+            self._value = value
+            return True
+
+    value = AliasProperty(_get_value, _set_value)
+    '''Current value used for the slider.
+
+    :attr:`value` is an :class:`~kivy.properties.AliasProperty` that
+    returns the value of the progress bar. If the value is < 0 or >
+    :attr:`max`, it will be normalized to those boundaries.
+
+    .. versionchanged:: 1.6.0
+        The value is now limited to between 0 and :attr:`max`.
+    '''
+
+    def get_norm_value(self):
+        d = self.max
+        if d == 0:
+            return 0
+        return self.value / float(d)
+
+    def set_norm_value(self, value):
+        self.value = value * self.max
+
+    value_normalized = AliasProperty(get_norm_value, set_norm_value,
+                                     bind=('value', 'max'), cache=True)
+    '''Normalized value inside the range 0-1::
+
+        >>> pb = ProgressBar(value=50, max=100)
+        >>> pb.value
+        50
+        >>> pb.value_normalized
+        0.5
+
+    :attr:`value_normalized` is an :class:`~kivy.properties.AliasProperty`.
+    '''
+
+    max = NumericProperty(100.)
+    '''Maximum value allowed for :attr:`value`.
+
+    :attr:`max` is a :class:`~kivy.properties.NumericProperty` and defaults to
+    100.
+    '''
+
+
+if __name__ == '__main__':
+
+    from kivy.base import runTouchApp
+    runTouchApp(ProgressBar(value=50))