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

kivy/uix/behaviors/cover.py

@@ -0,0 +1,160 @@
+'''
+Cover Behavior
+==============
+
+The :class:`~kivy.uix.behaviors.cover.CoverBehavior`
+`mixin <https://en.wikipedia.org/wiki/Mixin>`_ is intended for rendering
+textures to full widget size keeping the aspect ratio of the original texture.
+
+Use cases are i.e. rendering full size background images or video content in
+a dynamic layout.
+
+For an overview of behaviors, please refer to the :mod:`~kivy.uix.behaviors`
+documentation.
+
+Example
+-------
+
+The following examples add cover behavior to an image:
+
+In python:
+
+.. code-block:: python
+
+    from kivy.app import App
+    from kivy.uix.behaviors import CoverBehavior
+    from kivy.uix.image import Image
+
+
+    class CoverImage(CoverBehavior, Image):
+
+        def __init__(self, **kwargs):
+            super(CoverImage, self).__init__(**kwargs)
+            texture = self._coreimage.texture
+            self.reference_size = texture.size
+            self.texture = texture
+
+
+    class MainApp(App):
+
+        def build(self):
+            return CoverImage(source='image.jpg')
+
+    MainApp().run()
+
+In Kivy Language:
+
+.. code-block:: kv
+
+    CoverImage:
+        source: 'image.png'
+
+    <CoverImage@CoverBehavior+Image>:
+        reference_size: self.texture_size
+
+See :class:`~kivy.uix.behaviors.cover.CoverBehavior` for details.
+'''
+
+__all__ = ('CoverBehavior', )
+
+from decimal import Decimal
+from kivy.lang import Builder
+from kivy.properties import ListProperty
+
+
+Builder.load_string("""
+<-CoverBehavior>:
+    canvas.before:
+        StencilPush
+        Rectangle:
+            pos: self.pos
+            size: self.size
+        StencilUse
+    canvas:
+        Rectangle:
+            texture: self.texture
+            size: self.cover_size
+            pos: self.cover_pos
+    canvas.after:
+        StencilUnUse
+        Rectangle:
+            pos: self.pos
+            size: self.size
+        StencilPop
+""")
+
+
+class CoverBehavior(object):
+    '''The CoverBehavior `mixin <https://en.wikipedia.org/wiki/Mixin>`_
+    provides rendering a texture covering full widget size keeping aspect ratio
+    of the original texture.
+
+    .. versionadded:: 1.10.0
+    '''
+
+    reference_size = ListProperty([])
+    '''Reference size used for aspect ratio approximation calculation.
+
+    :attr:`reference_size` is a :class:`~kivy.properties.ListProperty` and
+    defaults to `[]`.
+    '''
+
+    cover_size = ListProperty([0, 0])
+    '''Size of the aspect ratio aware texture. Gets calculated in
+    ``CoverBehavior.calculate_cover``.
+
+    :attr:`cover_size` is a :class:`~kivy.properties.ListProperty` and
+    defaults to `[0, 0]`.
+    '''
+
+    cover_pos = ListProperty([0, 0])
+    '''Position of the aspect ratio aware texture. Gets calculated in
+    ``CoverBehavior.calculate_cover``.
+
+    :attr:`cover_pos` is a :class:`~kivy.properties.ListProperty` and
+    defaults to `[0, 0]`.
+    '''
+
+    def __init__(self, **kwargs):
+        super(CoverBehavior, self).__init__(**kwargs)
+        # bind covering
+        self.bind(
+            size=self.calculate_cover,
+            pos=self.calculate_cover
+        )
+
+    def _aspect_ratio_approximate(self, size):
+        # return a decimal approximation of an aspect ratio.
+        return Decimal('%.2f' % (float(size[0]) / size[1]))
+
+    def _scale_size(self, size, sizer):
+        # return scaled size based on sizer, where sizer (n, None) scales x
+        # to n and (None, n) scales y to n
+        size_new = list(sizer)
+        i = size_new.index(None)
+        j = i * -1 + 1
+        size_new[i] = (size_new[j] * size[i]) / size[j]
+        return tuple(size_new)
+
+    def calculate_cover(self, *args):
+        # return if no reference size yet
+        if not self.reference_size:
+            return
+        size = self.size
+        origin_appr = self._aspect_ratio_approximate(self.reference_size)
+        crop_appr = self._aspect_ratio_approximate(size)
+        # same aspect ratio
+        if origin_appr == crop_appr:
+            crop_size = self.size
+            offset = (0, 0)
+        # scale x
+        elif origin_appr < crop_appr:
+            crop_size = self._scale_size(self.reference_size, (size[0], None))
+            offset = (0, ((crop_size[1] - size[1]) / 2) * -1)
+        # scale y
+        else:
+            crop_size = self._scale_size(self.reference_size, (None, size[1]))
+            offset = (((crop_size[0] - size[0]) / 2) * -1, 0)
+        # set background size and position
+        self.cover_size = crop_size
+        self.cover_pos = offset

kivy/uix/behaviors/drag.py

@@ -0,0 +1,234 @@
+"""
+Drag Behavior
+=============
+
+The :class:`~kivy.uix.behaviors.drag.DragBehavior`
+`mixin <https://en.wikipedia.org/wiki/Mixin>`_ class provides Drag behavior.
+When combined with a widget, dragging in the rectangle defined by the
+:attr:`~kivy.uix.behaviors.drag.DragBehavior.drag_rectangle` will drag the
+widget.
+
+Example
+-------
+
+The following example creates a draggable label::
+
+    from kivy.uix.label import Label
+    from kivy.app import App
+    from kivy.uix.behaviors import DragBehavior
+    from kivy.lang import Builder
+
+    # You could also put the following in your kv file...
+    kv = '''
+    <DragLabel>:
+        # Define the properties for the DragLabel
+        drag_rectangle: self.x, self.y, self.width, self.height
+        drag_timeout: 10000000
+        drag_distance: 0
+
+    FloatLayout:
+        # Define the root widget
+        DragLabel:
+            size_hint: 0.25, 0.2
+            text: 'Drag me'
+    '''
+
+
+    class DragLabel(DragBehavior, Label):
+        pass
+
+
+    class TestApp(App):
+        def build(self):
+            return Builder.load_string(kv)
+
+    TestApp().run()
+
+"""
+
+__all__ = ('DragBehavior', )
+
+from kivy.clock import Clock
+from kivy.properties import NumericProperty, ReferenceListProperty
+from kivy.config import Config
+from kivy.metrics import sp
+from functools import partial
+
+# When we are generating documentation, Config doesn't exist
+_scroll_timeout = _scroll_distance = 0
+if Config:
+    _scroll_timeout = Config.getint('widgets', 'scroll_timeout')
+    _scroll_distance = Config.getint('widgets', 'scroll_distance')
+
+
+class DragBehavior(object):
+    '''
+    The DragBehavior `mixin <https://en.wikipedia.org/wiki/Mixin>`_ provides
+    Drag behavior. When combined with a widget, dragging in the rectangle
+    defined by :attr:`drag_rectangle` will drag the widget. Please see
+    the :mod:`drag behaviors module <kivy.uix.behaviors.drag>` documentation
+    for more information.
+
+    .. versionadded:: 1.8.0
+    '''
+
+    drag_distance = NumericProperty(_scroll_distance)
+    '''Distance to move before dragging the :class:`DragBehavior`, in pixels.
+    As soon as the distance has been traveled, the :class:`DragBehavior` will
+    start to drag, and no touch event will be dispatched to the children.
+    It is advisable that you base this value on the dpi of your target device's
+    screen.
+
+    :attr:`drag_distance` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to the `scroll_distance` as defined in the user
+    :class:`~kivy.config.Config` (20 pixels by default).
+    '''
+
+    drag_timeout = NumericProperty(_scroll_timeout)
+    '''Timeout allowed to trigger the :attr:`drag_distance`, in milliseconds.
+    If the user has not moved :attr:`drag_distance` within the timeout,
+    dragging will be disabled, and the touch event will be dispatched to the
+    children.
+
+    :attr:`drag_timeout` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to the `scroll_timeout` as defined in the user
+    :class:`~kivy.config.Config` (55 milliseconds by default).
+    '''
+
+    drag_rect_x = NumericProperty(0)
+    '''X position of the axis aligned bounding rectangle where dragging
+    is allowed (in window coordinates).
+
+    :attr:`drag_rect_x` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 0.
+    '''
+
+    drag_rect_y = NumericProperty(0)
+    '''Y position of the axis aligned bounding rectangle where dragging
+    is allowed (in window coordinates).
+
+    :attr:`drag_rect_Y` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 0.
+    '''
+
+    drag_rect_width = NumericProperty(100)
+    '''Width of the axis aligned bounding rectangle where dragging is allowed.
+
+    :attr:`drag_rect_width` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 100.
+    '''
+
+    drag_rect_height = NumericProperty(100)
+    '''Height of the axis aligned bounding rectangle where dragging is allowed.
+
+    :attr:`drag_rect_height` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 100.
+    '''
+
+    drag_rectangle = ReferenceListProperty(drag_rect_x, drag_rect_y,
+                                           drag_rect_width, drag_rect_height)
+    '''Position and size of the axis aligned bounding rectangle where dragging
+    is allowed.
+
+    :attr:`drag_rectangle` is a :class:`~kivy.properties.ReferenceListProperty`
+    of (:attr:`drag_rect_x`, :attr:`drag_rect_y`, :attr:`drag_rect_width`,
+    :attr:`drag_rect_height`) properties.
+    '''
+
+    def __init__(self, **kwargs):
+        self._drag_touch = None
+        super(DragBehavior, self).__init__(**kwargs)
+
+    def _get_uid(self, prefix='sv'):
+        return '{0}.{1}'.format(prefix, self.uid)
+
+    def on_touch_down(self, touch):
+        xx, yy, w, h = self.drag_rectangle
+        x, y = touch.pos
+        if not self.collide_point(x, y):
+            touch.ud[self._get_uid('svavoid')] = True
+            return super(DragBehavior, self).on_touch_down(touch)
+        if self._drag_touch or ('button' in touch.profile and
+                                touch.button.startswith('scroll')) or\
+                not ((xx < x <= xx + w) and (yy < y <= yy + h)):
+            return super(DragBehavior, self).on_touch_down(touch)
+
+        # no mouse scrolling, so the user is going to drag with this touch.
+        self._drag_touch = touch
+        uid = self._get_uid()
+        touch.grab(self)
+        touch.ud[uid] = {
+            'mode': 'unknown',
+            'dx': 0,
+            'dy': 0}
+        Clock.schedule_once(self._change_touch_mode,
+                            self.drag_timeout / 1000.)
+        return True
+
+    def on_touch_move(self, touch):
+        if self._get_uid('svavoid') in touch.ud or\
+                self._drag_touch is not touch:
+            return super(DragBehavior, self).on_touch_move(touch) or\
+                self._get_uid() in touch.ud
+        if touch.grab_current is not self:
+            return True
+
+        uid = self._get_uid()
+        ud = touch.ud[uid]
+        mode = ud['mode']
+        if mode == 'unknown':
+            ud['dx'] += abs(touch.dx)
+            ud['dy'] += abs(touch.dy)
+            if ud['dx'] > sp(self.drag_distance):
+                mode = 'drag'
+            if ud['dy'] > sp(self.drag_distance):
+                mode = 'drag'
+            ud['mode'] = mode
+        if mode == 'drag':
+            self.x += touch.dx
+            self.y += touch.dy
+        return True
+
+    def on_touch_up(self, touch):
+        if self._get_uid('svavoid') in touch.ud:
+            return super(DragBehavior, self).on_touch_up(touch)
+
+        if self._drag_touch and self in [x() for x in touch.grab_list]:
+            touch.ungrab(self)
+            self._drag_touch = None
+            ud = touch.ud[self._get_uid()]
+            if ud['mode'] == 'unknown':
+                super(DragBehavior, self).on_touch_down(touch)
+                Clock.schedule_once(partial(self._do_touch_up, touch), .1)
+        else:
+            if self._drag_touch is not touch:
+                super(DragBehavior, self).on_touch_up(touch)
+        return self._get_uid() in touch.ud
+
+    def _do_touch_up(self, touch, *largs):
+        super(DragBehavior, self).on_touch_up(touch)
+        # don't forget about grab event!
+        for x in touch.grab_list[:]:
+            touch.grab_list.remove(x)
+            x = x()
+            if not x:
+                continue
+            touch.grab_current = x
+            super(DragBehavior, self).on_touch_up(touch)
+        touch.grab_current = None
+
+    def _change_touch_mode(self, *largs):
+        if not self._drag_touch:
+            return
+        uid = self._get_uid()
+        touch = self._drag_touch
+        ud = touch.ud[uid]
+        if ud['mode'] != 'unknown':
+            return
+        touch.ungrab(self)
+        self._drag_touch = None
+        touch.push()
+        touch.apply_transform_2d(self.parent.to_widget)
+        super(DragBehavior, self).on_touch_down(touch)
+        touch.pop()
+        return

kivy/uix/behaviors/emacs.py

@@ -0,0 +1,140 @@
+# -*- encoding: utf-8 -*-
+'''
+Emacs Behavior
+==============
+
+The :class:`~kivy.uix.behaviors.emacs.EmacsBehavior`
+`mixin <https://en.wikipedia.org/wiki/Mixin>`_ allows you to add
+`Emacs <https://www.gnu.org/software/emacs/>`_ keyboard shortcuts for basic
+movement and editing to the :class:`~kivy.uix.textinput.TextInput` widget.
+The shortcuts currently available are listed below:
+
+Emacs shortcuts
+---------------
+=============== ========================================================
+   Shortcut     Description
+--------------- --------------------------------------------------------
+Control + a     Move cursor to the beginning of the line
+Control + e     Move cursor to the end of the line
+Control + f     Move cursor one character to the right
+Control + b     Move cursor one character to the left
+Alt + f         Move cursor to the end of the word to the right
+Alt + b         Move cursor to the start of the word to the left
+Alt + Backspace Delete text left of the cursor to the beginning of word
+Alt + d         Delete text right of the cursor to the end of the word
+Alt + w         Copy selection
+Control + w     Cut selection
+Control + y     Paste selection
+=============== ========================================================
+
+.. warning::
+    If you have the :mod:`~kivy.modules.inspector` module enabled, the
+    shortcut for opening the inspector (Control + e) conflicts with the
+    Emacs shortcut to move to the end of the line (it will still move the
+    cursor to the end of the line, but the inspector will open as well).
+'''
+
+from kivy.properties import StringProperty
+
+
+__all__ = ('EmacsBehavior', )
+
+
+class EmacsBehavior(object):
+    '''
+    A `mixin <https://en.wikipedia.org/wiki/Mixin>`_ that enables Emacs-style
+    keyboard shortcuts for the :class:`~kivy.uix.textinput.TextInput` widget.
+    Please see the :mod:`Emacs behaviors module <kivy.uix.behaviors.emacs>`
+    documentation for more information.
+
+    .. versionadded:: 1.9.1
+    '''
+
+    key_bindings = StringProperty('emacs')
+    '''String name which determines the type of key bindings to use with the
+    :class:`~kivy.uix.textinput.TextInput`. This allows Emacs key bindings to
+    be enabled/disabled programmatically for widgets that inherit from
+    :class:`EmacsBehavior`. If the value is not ``'emacs'``, Emacs bindings
+    will be disabled. Use ``'default'`` for switching to the default key
+    bindings of TextInput.
+
+    :attr:`key_bindings` is a :class:`~kivy.properties.StringProperty`
+    and defaults to ``'emacs'``.
+
+    .. versionadded:: 1.10.0
+    '''
+
+    def __init__(self, **kwargs):
+        super(EmacsBehavior, self).__init__(**kwargs)
+
+        self.bindings = {
+            'ctrl': {
+                'a': lambda: self.do_cursor_movement('cursor_home'),
+                'e': lambda: self.do_cursor_movement('cursor_end'),
+                'f': lambda: self.do_cursor_movement('cursor_right'),
+                'b': lambda: self.do_cursor_movement('cursor_left'),
+                'w': lambda: self._cut(self.selection_text),
+                'y': self.paste,
+            },
+            'alt': {
+                'w': self.copy,
+                'f': lambda: self.do_cursor_movement('cursor_right',
+                                                     control=True),
+                'b': lambda: self.do_cursor_movement('cursor_left',
+                                                     control=True),
+                'd': self.delete_word_right,
+                '\x08': self.delete_word_left,  # alt + backspace
+            },
+        }
+
+    def keyboard_on_key_down(self, window, keycode, text, modifiers):
+
+        key, key_str = keycode
+
+        # join the modifiers e.g. ['alt', 'ctrl']
+        mod = '+'.join(modifiers) if modifiers else None
+        is_emacs_shortcut = False
+
+        if key in range(256) and self.key_bindings == 'emacs':
+            if mod == 'ctrl' and chr(key) in self.bindings['ctrl'].keys():
+                is_emacs_shortcut = True
+            elif mod == 'alt' and chr(key) in self.bindings['alt'].keys():
+                is_emacs_shortcut = True
+            else:  # e.g. ctrl+alt or alt+ctrl (alt-gr key)
+                is_emacs_shortcut = False
+
+        if is_emacs_shortcut:
+            # Look up mod and key
+            emacs_shortcut = self.bindings[mod][chr(key)]
+            emacs_shortcut()
+        else:
+            super(EmacsBehavior, self).keyboard_on_key_down(window, keycode,
+                                                            text, modifiers)
+
+    def delete_word_right(self):
+        '''Delete text right of the cursor to the end of the word'''
+        if self._selection:
+            return
+        start_index = self.cursor_index()
+        start_cursor = self.cursor
+        self.do_cursor_movement('cursor_right', control=True)
+        end_index = self.cursor_index()
+        if start_index != end_index:
+            s = self.text[start_index:end_index]
+            self._set_unredo_delsel(start_index, end_index, s, from_undo=False)
+            self.text = self.text[:start_index] + self.text[end_index:]
+            self._set_cursor(pos=start_cursor)
+
+    def delete_word_left(self):
+        '''Delete text left of the cursor to the beginning of word'''
+        if self._selection:
+            return
+        start_index = self.cursor_index()
+        self.do_cursor_movement('cursor_left', control=True)
+        end_cursor = self.cursor
+        end_index = self.cursor_index()
+        if start_index != end_index:
+            s = self.text[end_index:start_index]
+            self._set_unredo_delsel(end_index, start_index, s, from_undo=False)
+            self.text = self.text[:end_index] + self.text[start_index:]
+            self._set_cursor(pos=end_cursor)