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

kivy/input/__init__.py

@@ -0,0 +1,39 @@
+# pylint: disable=W0611
+'''
+Input management
+================
+
+Our input system is wide and simple at the same time. We are currently able to
+natively support :
+
+* Windows multitouch events (pencil and finger)
+* OS X touchpads
+* Linux multitouch events (kernel and mtdev)
+* Linux wacom drivers (pencil and finger)
+* TUIO
+
+All the input management is configurable in the Kivy :mod:`~kivy.config`. You
+can easily use many multitouch devices in one Kivy application.
+
+When the events have been read from the devices, they are dispatched through
+a post processing module before being sent to your application. We also have
+several default modules for :
+
+* Double tap detection
+* Decreasing jittering
+* Decreasing the inaccuracy of touch on "bad" DIY hardware
+* Ignoring regions
+'''
+
+
+from kivy.input.motionevent import MotionEvent
+from kivy.input.postproc import kivy_postproc_modules
+from kivy.input.provider import MotionEventProvider
+from kivy.input.factory import MotionEventFactory
+import kivy.input.providers
+
+__all__ = (
+    MotionEvent.__name__,
+    MotionEventProvider.__name__,
+    MotionEventFactory.__name__,
+    'kivy_postproc_modules')

kivy/input/factory.py

@@ -0,0 +1,35 @@
+'''
+Motion Event Factory
+====================
+
+Factory of :class:`~kivy.input.motionevent.MotionEvent` providers.
+'''
+
+__all__ = ('MotionEventFactory', )
+
+
+class MotionEventFactory:
+    '''MotionEvent factory is a class that registers all availables input
+    factories. If you create a new input factory, you need to register
+    it here::
+
+        MotionEventFactory.register('myproviderid', MyInputProvider)
+
+    '''
+    __providers__ = {}
+
+    @staticmethod
+    def register(name, classname):
+        '''Register a input provider in the database'''
+        MotionEventFactory.__providers__[name] = classname
+
+    @staticmethod
+    def list():
+        '''Get a list of all available providers'''
+        return MotionEventFactory.__providers__
+
+    @staticmethod
+    def get(name):
+        '''Get a provider class from the provider id'''
+        if name in MotionEventFactory.__providers__:
+            return MotionEventFactory.__providers__[name]

kivy/input/motionevent.py

@@ -0,0 +1,587 @@
+'''
+.. _motionevent:
+
+Motion Event
+============
+
+The :class:`MotionEvent` is the base class used for events provided by
+pointing devices (touch and non-touch). This class defines all the properties
+and methods needed to handle 2D and 3D movements but has many more
+capabilities.
+
+Usually you would never need to create the :class:`MotionEvent` yourself as
+this is the role of the :mod:`~kivy.input.providers`.
+
+Flow of the motion events
+-------------------------
+
+1. The :class:`MotionEvent` 's are gathered from input providers by
+   :class:`~kivy.base.EventLoopBase`.
+2. Post processing is performed by registered processors
+   :mod:`~kivy.input.postproc`.
+3. :class:`~kivy.base.EventLoopBase` dispatches all motion events using
+   `on_motion` event to all registered listeners including the
+   :class:`~kivy.core.window.WindowBase`.
+4. Once received in :meth:`~kivy.core.window.WindowBase.on_motion` events
+   (touch or non-touch) are all registered managers. If a touch event is not
+   handled by at least one manager, then it is dispatched through
+   :meth:`~kivy.core.window.WindowBase.on_touch_down`,
+   :meth:`~kivy.core.window.WindowBase.on_touch_move` and
+   :meth:`~kivy.core.window.WindowBase.on_touch_up`.
+5. Widgets receive events in :meth:`~kivy.uix.widget.Widget.on_motion` method
+   (if passed by a manager) or on `on_touch_xxx` methods.
+
+Motion events and event managers
+--------------------------------
+
+A motion event is a touch event if its :attr:`MotionEvent.is_touch` is set to
+`True`. Beside `is_touch` attribute, :attr:`MotionEvent.type_id` can be used to
+check for event's general type. Currently two types are dispatched by
+input providers: "touch" and "hover".
+
+Event managers can be used to dispatch any motion event throughout the widget
+tree and a manager uses `type_id` to specify which event types it want to
+receive. See :mod:`~kivy.eventmanager` to learn how to define and register
+an event manager.
+
+A manager can also assign a new `type_id` to
+:attr:`MotionEvent.type_id` before dispatching it to the widgets. This useful
+when dispatching a specific event::
+
+    class MouseTouchManager(EventManagerBase):
+
+        type_ids = ('touch',)
+
+        def dispatch(self, etype, me):
+            accepted = False
+            if me.device == 'mouse':
+                me.push() # Save current type_id and other values
+                me.type_id = 'mouse_touch'
+                self.window.transform_motion_event_2d(me)
+                # Dispatch mouse touch event to widgets which registered
+                # to receive 'mouse_touch'
+                for widget in self.window.children[:]:
+                    if widget.dispatch('on_motion', etype, me):
+                        accepted = True
+                        break
+                me.pop() # Restore
+            return accepted
+
+Listening to a motion event
+---------------------------
+
+If you want to receive all motion events, touch or not, you can bind the
+MotionEvent from the :class:`~kivy.core.window.Window` to your own callback::
+
+    def on_motion(self, etype, me):
+        # will receive all motion events.
+        pass
+
+    Window.bind(on_motion=on_motion)
+
+You can also listen to changes of the mouse position by watching
+:attr:`~kivy.core.window.WindowBase.mouse_pos`.
+
+Profiles
+--------
+
+The :class:`MotionEvent` stores device specific information in various
+properties listed in the :attr:`~MotionEvent.profile`.
+For example, you can receive a MotionEvent that has an angle, a fiducial
+ID, or even a shape. You can check the :attr:`~MotionEvent.profile`
+attribute to see what is currently supported by the MotionEvent provider.
+
+This is a short list of the profile values supported by default. Please check
+the :attr:`MotionEvent.profile` property to see what profile values are
+available.
+
+============== ================================================================
+Profile value   Description
+-------------- ----------------------------------------------------------------
+angle          2D angle. Accessed via the `a` property.
+button         Mouse button ('left', 'right', 'middle', 'scrollup' or
+               'scrolldown'). Accessed via the `button` property.
+markerid       Marker or Fiducial ID. Accessed via the `fid` property.
+pos            2D position. Accessed via the `x`, `y` or `pos` properties.
+pos3d          3D position. Accessed via the `x`, `y` or `z` properties.
+pressure       Pressure of the contact. Accessed via the `pressure` property.
+shape          Contact shape. Accessed via the `shape` property .
+============== ================================================================
+
+If you want to know whether the current :class:`MotionEvent` has an angle::
+
+    def on_touch_move(self, touch):
+        if 'angle' in touch.profile:
+            print('The touch angle is', touch.a)
+
+If you want to select only the fiducials::
+
+    def on_touch_move(self, touch):
+        if 'markerid' not in touch.profile:
+            return
+
+'''
+
+__all__ = ('MotionEvent', )
+
+import weakref
+from inspect import isroutine
+from copy import copy
+from time import time
+
+from kivy.eventmanager import MODE_DEFAULT_DISPATCH
+from kivy.vector import Vector
+
+
+class EnhancedDictionary(dict):
+
+    def __getattr__(self, attr):
+        try:
+            return self.__getitem__(attr)
+        except KeyError:
+            return super(EnhancedDictionary, self).__getattr__(attr)
+
+    def __setattr__(self, attr, value):
+        self.__setitem__(attr, value)
+
+
+class MotionEventMetaclass(type):
+
+    def __new__(mcs, name, bases, attrs):
+        __attrs__ = []
+        for base in bases:
+            if hasattr(base, '__attrs__'):
+                __attrs__.extend(base.__attrs__)
+        if '__attrs__' in attrs:
+            __attrs__.extend(attrs['__attrs__'])
+        attrs['__attrs__'] = tuple(__attrs__)
+        return super(MotionEventMetaclass, mcs).__new__(mcs, name,
+                                                        bases, attrs)
+
+
+MotionEventBase = MotionEventMetaclass('MotionEvent', (object, ), {})
+
+
+class MotionEvent(MotionEventBase):
+    '''Abstract class that represents an input event.
+
+    :Parameters:
+        `id`: str
+            unique ID of the MotionEvent
+        `args`: list
+            list of parameters, passed to the depack() function
+    '''
+
+    __uniq_id = 0
+    __attrs__ = \
+        ('device', 'push_attrs', 'push_attrs_stack',
+         'is_touch', 'type_id', 'id', 'dispatch_mode', 'shape', 'profile',
+         # current position, in 0-1 range
+         'sx', 'sy', 'sz',
+         # first position set, in 0-1 range
+         'osx', 'osy', 'osz',
+         # last position set, in 0-1 range
+         'psx', 'psy', 'psz',
+         # delta from the last position and current one, in 0-1 range
+         'dsx', 'dsy', 'dsz',
+         # current position, in screen range
+         'x', 'y', 'z',
+         # first position set, in screen range
+         'ox', 'oy', 'oz',
+         # last position set, in 0-1 range
+         'px', 'py', 'pz',
+         # delta from the last position and current one, in screen range
+         'dx', 'dy', 'dz',
+         'time_start',
+         'is_double_tap', 'double_tap_time',
+         'is_triple_tap', 'triple_tap_time',
+         'ud')
+
+    def __init__(self, device, id, args, is_touch=False, type_id=None):
+        if self.__class__ == MotionEvent:
+            raise NotImplementedError('class MotionEvent is abstract')
+        MotionEvent.__uniq_id += 1
+
+        #: True if the MotionEvent is a touch.
+        self.is_touch = is_touch
+
+        #: (Experimental) String to identify event type.
+        #:
+        #: .. versionadded:: 2.1.0
+        self.type_id = type_id
+
+        #: (Experimental) Used by a event manager or a widget to assign
+        #: the dispatching mode. Defaults to
+        #: :const:`~kivy.eventmanager.MODE_DEFAULT_DISPATCH`. See
+        #: :mod:`~kivy.eventmanager` for available modes.
+        #:
+        #: .. versionadded:: 2.1.0
+        self.dispatch_mode = MODE_DEFAULT_DISPATCH
+
+        #: Attributes to push by default, when we use :meth:`push` : x, y, z,
+        #: dx, dy, dz, ox, oy, oz, px, py, pz.
+        self.push_attrs_stack = []
+        self.push_attrs = ('x', 'y', 'z', 'dx', 'dy', 'dz', 'ox', 'oy', 'oz',
+                           'px', 'py', 'pz', 'pos', 'type_id', 'dispatch_mode')
+
+        #: Uniq ID of the event. You can safely use this property, it will be
+        #: never the same across all existing events.
+        self.uid = MotionEvent.__uniq_id
+
+        #: Device used for creating this event.
+        self.device = device
+
+        # For grab
+        self.grab_list = []
+        self.grab_exclusive_class = None
+        self.grab_state = False
+
+        #: Used to determine which widget the event is being dispatched to.
+        #: Check the :meth:`grab` function for more information.
+        self.grab_current = None
+
+        #: Currently pressed button.
+        self.button = None
+
+        #: Profiles currently used in the event.
+        self.profile = []
+
+        #: Id of the event, not unique. This is generally the Id set by the
+        #: input provider, like ID in TUIO. If you have multiple TUIO sources,
+        #: then same id can be used. Prefer to use :attr:`uid` attribute
+        #: instead.
+        self.id = id
+
+        #: Shape of the touch event, subclass of
+        #: :class:`~kivy.input.shape.Shape`.
+        #: By default, the property is set to None.
+        self.shape = None
+
+        #: X position, in 0-1 range.
+        self.sx = 0.0
+        #: Y position, in 0-1 range.
+        self.sy = 0.0
+        #: Z position, in 0-1 range.
+        self.sz = 0.0
+        #: Origin X position, in 0-1 range.
+        self.osx = None
+        #: Origin Y position, in 0-1 range.
+        self.osy = None
+        #: Origin Z position, in 0-1 range.
+        self.osz = None
+        #: Previous X position, in 0-1 range.
+        self.psx = None
+        #: Previous Y position, in 0-1 range.
+        self.psy = None
+        #: Previous Z position, in 0-1 range.
+        self.psz = None
+        #: Delta between self.sx and self.psx, in 0-1 range.
+        self.dsx = None
+        #: Delta between self.sy and self.psy, in 0-1 range.
+        self.dsy = None
+        #: Delta between self.sz and self.psz, in 0-1 range.
+        self.dsz = None
+        #: X position, in window range.
+        self.x = 0.0
+        #: Y position, in window range.
+        self.y = 0.0
+        #: Z position, in window range.
+        self.z = 0.0
+        #: Origin X position, in window range.
+        self.ox = None
+        #: Origin Y position, in window range.
+        self.oy = None
+        #: Origin Z position, in window range.
+        self.oz = None
+        #: Previous X position, in window range.
+        self.px = None
+        #: Previous Y position, in window range.
+        self.py = None
+        #: Previous Z position, in window range.
+        self.pz = None
+        #: Delta between self.x and self.px, in window range.
+        self.dx = None
+        #: Delta between self.y and self.py, in window range.
+        self.dy = None
+        #: Delta between self.z and self.pz, in window range.
+        self.dz = None
+        #: Position (X, Y), in window range.
+        self.pos = (0.0, 0.0)
+
+        #: Initial time of the event creation.
+        self.time_start = time()
+
+        #: Time of the last update.
+        self.time_update = self.time_start
+
+        #: Time of the end event (last event usage).
+        self.time_end = -1
+
+        #: Indicate if the touch event is a double tap or not.
+        self.is_double_tap = False
+
+        #: Indicate if the touch event is a triple tap or not.
+        #:
+        #: .. versionadded:: 1.7.0
+        self.is_triple_tap = False
+
+        #: If the touch is a :attr:`is_double_tap`, this is the time
+        #: between the previous tap and the current touch.
+        self.double_tap_time = 0
+
+        #: If the touch is a :attr:`is_triple_tap`, this is the time
+        #: between the first tap and the current touch.
+        #:
+        #: .. versionadded:: 1.7.0
+        self.triple_tap_time = 0
+
+        #: User data dictionary. Use this dictionary to save your own data on
+        #: the event.
+        self.ud = EnhancedDictionary()
+
+        #: If set to `True` (default) keeps first previous position
+        #: (X, Y, Z in 0-1 range) and ignore all other until
+        #: :meth:`MotionEvent.dispatch_done` is called from the `EventLoop`.
+        #:
+        #: This attribute is needed because event provider can make many calls
+        #: to :meth:`MotionEvent.move`, but for all those calls event is
+        #: dispatched to the listeners only once. Assigning `False` will keep
+        #: latest previous position. See :meth:`MotionEvent.move`.
+        #:
+        #: .. versionadded:: 2.1.0
+        self.sync_with_dispatch = True
+
+        #: Keep first previous position if :attr:`sync_with_dispatch` is
+        #: `True`.
+        self._keep_prev_pos = True
+
+        #: Flag that first dispatch of this event is done.
+        self._first_dispatch_done = False
+
+        self.depack(args)
+
+    def depack(self, args):
+        '''Depack `args` into attributes of the class'''
+        if self.osx is None \
+                or self.sync_with_dispatch and not self._first_dispatch_done:
+            # Sync origin/previous/current positions until the first
+            # dispatch (etype == 'begin') is done.
+            self.osx = self.psx = self.sx
+            self.osy = self.psy = self.sy
+            self.osz = self.psz = self.sz
+        # update the delta
+        self.dsx = self.sx - self.psx
+        self.dsy = self.sy - self.psy
+        self.dsz = self.sz - self.psz
+
+    def grab(self, class_instance, exclusive=False):
+        '''Grab this motion event.
+
+        If this event is a touch you can grab it if you want to receive
+        subsequent :meth:`~kivy.uix.widget.Widget.on_touch_move` and
+        :meth:`~kivy.uix.widget.Widget.on_touch_up` events, even if the touch
+        is not dispatched by the parent:
+
+        .. code-block:: python
+
+            def on_touch_down(self, touch):
+                touch.grab(self)
+
+            def on_touch_move(self, touch):
+                if touch.grab_current is self:
+                    # I received my grabbed touch
+                else:
+                    # it's a normal touch
+
+            def on_touch_up(self, touch):
+                if touch.grab_current is self:
+                    # I receive my grabbed touch, I must ungrab it!
+                    touch.ungrab(self)
+                else:
+                    # it's a normal touch
+                    pass
+
+        .. versionchanged:: 2.1.0
+            Allowed grab for non-touch events.
+        '''
+        if self.grab_exclusive_class is not None:
+            raise Exception('Event is exclusive and cannot be grabbed')
+        class_instance = weakref.ref(class_instance.__self__)
+        if exclusive:
+            self.grab_exclusive_class = class_instance
+        self.grab_list.append(class_instance)
+
+    def ungrab(self, class_instance):
+        '''Ungrab a previously grabbed motion event.
+        '''
+        class_instance = weakref.ref(class_instance.__self__)
+        if self.grab_exclusive_class == class_instance:
+            self.grab_exclusive_class = None
+        if class_instance in self.grab_list:
+            self.grab_list.remove(class_instance)
+
+    def dispatch_done(self):
+        '''Notify that dispatch to the listeners is done.
+
+        Called by the :meth:`EventLoopBase.post_dispatch_input`.
+
+        .. versionadded:: 2.1.0
+        '''
+        self._keep_prev_pos = True
+        self._first_dispatch_done = True
+
+    def move(self, args):
+        '''Move to another position.
+        '''
+        if self.sync_with_dispatch:
+            if self._keep_prev_pos:
+                self.psx, self.psy, self.psz = self.sx, self.sy, self.sz
+                self._keep_prev_pos = False
+        else:
+            self.psx, self.psy, self.psz = self.sx, self.sy, self.sz
+        self.time_update = time()
+        self.depack(args)
+
+    def scale_for_screen(self, w, h, p=None, rotation=0,
+                         smode='None', kheight=0):
+        '''Scale position for the screen.
+
+        .. versionchanged:: 2.1.0
+            Max value for `x`, `y` and `z` is changed respectively to `w` - 1,
+            `h` - 1 and `p` - 1.
+        '''
+        x_max, y_max = max(0, w - 1), max(0, h - 1)
+        absolute = self.to_absolute_pos
+        self.x, self.y = absolute(self.sx, self.sy, x_max, y_max, rotation)
+        self.ox, self.oy = absolute(self.osx, self.osy, x_max, y_max, rotation)
+        self.px, self.py = absolute(self.psx, self.psy, x_max, y_max, rotation)
+        z_max = 0 if p is None else max(0, p - 1)
+        self.z = self.sz * z_max
+        self.oz = self.osz * z_max
+        self.pz = self.psz * z_max
+        if smode:
+            # Adjust y for keyboard height
+            if smode == 'pan' or smode == 'below_target':
+                self.y -= kheight
+                self.oy -= kheight
+                self.py -= kheight
+            elif smode == 'scale':
+                offset = kheight * (self.y - h) / (h - kheight)
+                self.y += offset
+                self.oy += offset
+                self.py += offset
+        # Update delta values
+        self.dx = self.x - self.px
+        self.dy = self.y - self.py
+        self.dz = self.z - self.pz
+        # Cache position
+        self.pos = self.x, self.y
+
+    def to_absolute_pos(self, nx, ny, x_max, y_max, rotation):
+        '''Transforms normalized (0-1) coordinates `nx` and `ny` to absolute
+        coordinates using `x_max`, `y_max` and `rotation`.
+
+        :raises:
+            `ValueError`: If `rotation` is not one of: 0, 90, 180 or 270
+
+        .. versionadded:: 2.1.0
+        '''
+        if rotation == 0:
+            return nx * x_max, ny * y_max
+        elif rotation == 90:
+            return ny * y_max, (1 - nx) * x_max
+        elif rotation == 180:
+            return (1 - nx) * x_max, (1 - ny) * y_max
+        elif rotation == 270:
+            return (1 - ny) * y_max, nx * x_max
+        raise ValueError('Invalid rotation %s, '
+                         'valid values are 0, 90, 180 or 270' % rotation)
+
+    def push(self, attrs=None):
+        '''Push attribute values in `attrs` onto the stack.
+        '''
+        if attrs is None:
+            attrs = self.push_attrs
+        values = [getattr(self, x) for x in attrs]
+        self.push_attrs_stack.append((attrs, values))
+
+    def pop(self):
+        '''Pop attributes values from the stack.
+        '''
+        attrs, values = self.push_attrs_stack.pop()
+        for i in range(len(attrs)):
+            setattr(self, attrs[i], values[i])
+
+    def apply_transform_2d(self, transform):
+        '''Apply a transformation on x, y, z, px, py, pz,
+        ox, oy, oz, dx, dy, dz.
+        '''
+        self.x, self.y = self.pos = transform(self.x, self.y)
+        self.px, self.py = transform(self.px, self.py)
+        self.ox, self.oy = transform(self.ox, self.oy)
+        self.dx = self.x - self.px
+        self.dy = self.y - self.py
+
+    def copy_to(self, to):
+        '''Copy some attribute to another motion event object.'''
+        for attr in self.__attrs__:
+            to.__setattr__(attr, copy(self.__getattribute__(attr)))
+
+    def distance(self, other_touch):
+        '''Return the distance between the two events.
+        '''
+        return Vector(self.pos).distance(other_touch.pos)
+
+    def update_time_end(self):
+        self.time_end = time()
+
+    # facilities
+    @property
+    def dpos(self):
+        '''Return delta between last position and current position, in the
+        screen coordinate system (self.dx, self.dy).'''
+        return self.dx, self.dy
+
+    @property
+    def opos(self):
+        '''Return the initial position of the motion event in the screen
+        coordinate system (self.ox, self.oy).'''
+        return self.ox, self.oy
+
+    @property
+    def ppos(self):
+        '''Return the previous position of the motion event in the screen
+        coordinate system (self.px, self.py).'''
+        return self.px, self.py
+
+    @property
+    def spos(self):
+        '''Return the position in the 0-1 coordinate system (self.sx, self.sy).
+        '''
+        return self.sx, self.sy
+
+    def __str__(self):
+        basename = str(self.__class__)
+        classname = basename.split('.')[-1].replace('>', '').replace('\'', '')
+        return '<%s spos=%s pos=%s>' % (classname, self.spos, self.pos)
+
+    def __repr__(self):
+        out = []
+        for x in dir(self):
+            v = getattr(self, x)
+            if x[0] == '_':
+                continue
+            if isroutine(v):
+                continue
+            out.append('%s="%s"' % (x, v))
+        return '<%s %s>' % (
+            self.__class__.__name__,
+            ' '.join(out))
+
+    @property
+    def is_mouse_scrolling(self, *args):
+        '''Returns True if the touch event is a mousewheel scrolling
+
+        .. versionadded:: 1.6.0
+        '''
+        return 'button' in self.profile and 'scroll' in self.button

kivy/input/postproc/__init__.py

@@ -0,0 +1,27 @@
+'''
+Input Postprocessing
+====================
+
+'''
+
+__all__ = ('kivy_postproc_modules', )
+
+import os
+from kivy.input.postproc.doubletap import InputPostprocDoubleTap
+from kivy.input.postproc.tripletap import InputPostprocTripleTap
+from kivy.input.postproc.ignorelist import InputPostprocIgnoreList
+from kivy.input.postproc.retaintouch import InputPostprocRetainTouch
+from kivy.input.postproc.dejitter import InputPostprocDejitter
+from kivy.input.postproc.calibration import InputPostprocCalibration
+
+# Mapping of ID to module
+kivy_postproc_modules = {}
+
+# Don't go further if we generate documentation
+if 'KIVY_DOC' not in os.environ:
+    kivy_postproc_modules['calibration'] = InputPostprocCalibration()
+    kivy_postproc_modules['retaintouch'] = InputPostprocRetainTouch()
+    kivy_postproc_modules['ignorelist'] = InputPostprocIgnoreList()
+    kivy_postproc_modules['doubletap'] = InputPostprocDoubleTap()
+    kivy_postproc_modules['tripletap'] = InputPostprocTripleTap()
+    kivy_postproc_modules['dejitter'] = InputPostprocDejitter()