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

kivy/uix/anchorlayout.py

@@ -0,0 +1,122 @@
+'''
+Anchor Layout
+=============
+
+.. only:: html
+
+    .. image:: images/anchorlayout.gif
+        :align: right
+
+.. only:: latex
+
+    .. image:: images/anchorlayout.png
+        :align: right
+
+The :class:`AnchorLayout` aligns its children to a border (top, bottom,
+left, right) or center.
+
+
+To draw a button in the lower-right corner::
+
+    layout = AnchorLayout(
+        anchor_x='right', anchor_y='bottom')
+    btn = Button(text='Hello World')
+    layout.add_widget(btn)
+
+'''
+
+__all__ = ('AnchorLayout', )
+
+from kivy.uix.layout import Layout
+from kivy.properties import OptionProperty, VariableListProperty
+
+
+class AnchorLayout(Layout):
+    '''Anchor layout class. See the module documentation for more information.
+    '''
+
+    padding = VariableListProperty([0, 0, 0, 0])
+    '''Padding between the widget box and its children, in pixels:
+    [padding_left, padding_top, padding_right, padding_bottom].
+
+    padding also accepts a two argument form [padding_horizontal,
+    padding_vertical] and a one argument form [padding].
+
+    :attr:`padding` is a :class:`~kivy.properties.VariableListProperty` and
+    defaults to [0, 0, 0, 0].
+    '''
+
+    anchor_x = OptionProperty('center', options=(
+        'left', 'center', 'right'))
+    '''Horizontal anchor.
+
+    :attr:`anchor_x` is an :class:`~kivy.properties.OptionProperty` and
+    defaults to 'center'. It accepts values of 'left', 'center' or
+    'right'.
+    '''
+
+    anchor_y = OptionProperty('center', options=(
+        'top', 'center', 'bottom'))
+    '''Vertical anchor.
+
+    :attr:`anchor_y` is an :class:`~kivy.properties.OptionProperty` and
+    defaults to 'center'. It accepts values of 'top', 'center' or
+    'bottom'.
+    '''
+
+    def __init__(self, **kwargs):
+        super(AnchorLayout, self).__init__(**kwargs)
+        fbind = self.fbind
+        update = self._trigger_layout
+        fbind('children', update)
+        fbind('parent', update)
+        fbind('padding', update)
+        fbind('anchor_x', update)
+        fbind('anchor_y', update)
+        fbind('size', update)
+        fbind('pos', update)
+
+    def do_layout(self, *largs):
+        _x, _y = self.pos
+        width = self.width
+        height = self.height
+        anchor_x = self.anchor_x
+        anchor_y = self.anchor_y
+        pad_left, pad_top, pad_right, pad_bottom = self.padding
+
+        for c in self.children:
+            x, y = _x, _y
+            cw, ch = c.size
+            shw, shh = c.size_hint
+            shw_min, shh_min = c.size_hint_min
+            shw_max, shh_max = c.size_hint_max
+
+            if shw is not None:
+                cw = shw * (width - pad_left - pad_right)
+                if shw_min is not None and cw < shw_min:
+                    cw = shw_min
+                elif shw_max is not None and cw > shw_max:
+                    cw = shw_max
+
+            if shh is not None:
+                ch = shh * (height - pad_top - pad_bottom)
+                if shh_min is not None and ch < shh_min:
+                    ch = shh_min
+                elif shh_max is not None and ch > shh_max:
+                    ch = shh_max
+
+            if anchor_x == 'left':
+                x = x + pad_left
+            elif anchor_x == 'right':
+                x = x + width - (cw + pad_right)
+            else:
+                x = x + (width - pad_right + pad_left - cw) / 2
+            if anchor_y == 'bottom':
+                y = y + pad_bottom
+            elif anchor_y == 'top':
+                y = y + height - (ch + pad_top)
+            else:
+                y = y + (height - pad_top + pad_bottom - ch) / 2
+
+            c.pos = x, y
+            c.size = cw, ch

kivy/uix/behaviors/__init__.py

@@ -0,0 +1,95 @@
+'''
+Behaviors
+=========
+
+.. versionadded:: 1.8.0
+
+Behavior mixin classes
+----------------------
+
+This module implements behaviors that can be
+`mixed in <https://en.wikipedia.org/wiki/Mixin>`_
+with existing base widgets. The idea behind these classes is to encapsulate
+properties and events associated with certain types of widgets.
+
+Isolating these properties and events in a mixin class allows you to define
+your own implementation for standard kivy widgets that can act as drop-in
+replacements. This means you can re-style and re-define widgets as desired
+without breaking compatibility: as long as they implement the behaviors
+correctly, they can simply replace the standard widgets.
+
+Adding behaviors
+----------------
+
+Say you want to add :class:`~kivy.uix.button.Button` capabilities to an
+:class:`~kivy.uix.image.Image`, you could do::
+
+    class IconButton(ButtonBehavior, Image):
+        pass
+
+This would give you an :class:`~kivy.uix.image.Image` with the events and
+properties inherited from :class:`ButtonBehavior`. For example, the *on_press*
+and *on_release* events would be fired when appropriate::
+
+    class IconButton(ButtonBehavior, Image):
+        def on_press(self):
+            print("on_press")
+
+Or in kv:
+
+.. code-block:: kv
+
+    IconButton:
+        on_press: print('on_press')
+
+Naturally, you could also bind to any property changes the behavior class
+offers:
+
+.. code-block:: python
+
+        def state_changed(*args):
+            print('state changed')
+
+        button = IconButton()
+        button.bind(state=state_changed)
+
+
+.. note::
+
+    The behavior class must always be _before_ the widget class. If you don't
+    specify the inheritance in this order, the behavior will not work because
+    the behavior methods are overwritten by the class method listed first.
+
+    Similarly, if you combine a behavior class with a class which
+    requires the use of the methods also defined by the behavior class, the
+    resulting class may not function properly. For example, when combining the
+    :class:`ButtonBehavior` with a :class:`~kivy.uix.slider.Slider`, both of
+    which use the :meth:`~kivy.uix.widget.Widget.on_touch_up` method,
+    the resulting class may not work properly.
+
+.. versionchanged:: 1.9.1
+
+    The individual behavior classes, previously in one big `behaviors.py`
+    file, has been split into a single file for each class under the
+    :mod:`~kivy.uix.behaviors` module. All the behaviors are still imported
+    in the :mod:`~kivy.uix.behaviors` module so they are accessible as before
+    (e.g. both `from kivy.uix.behaviors import ButtonBehavior` and
+    `from kivy.uix.behaviors.button import ButtonBehavior` work).
+
+'''
+
+__all__ = ('ButtonBehavior', 'ToggleButtonBehavior', 'DragBehavior',
+           'FocusBehavior', 'CompoundSelectionBehavior',
+           'CodeNavigationBehavior', 'EmacsBehavior', 'CoverBehavior',
+           'TouchRippleBehavior', 'TouchRippleButtonBehavior')
+
+from kivy.uix.behaviors.button import ButtonBehavior
+from kivy.uix.behaviors.togglebutton import ToggleButtonBehavior
+from kivy.uix.behaviors.drag import DragBehavior
+from kivy.uix.behaviors.focus import FocusBehavior
+from kivy.uix.behaviors.compoundselection import CompoundSelectionBehavior
+from kivy.uix.behaviors.codenavigation import CodeNavigationBehavior
+from kivy.uix.behaviors.emacs import EmacsBehavior
+from kivy.uix.behaviors.cover import CoverBehavior
+from kivy.uix.behaviors.touchripple import TouchRippleBehavior
+from kivy.uix.behaviors.touchripple import TouchRippleButtonBehavior

kivy/uix/behaviors/button.py

@@ -0,0 +1,212 @@
+'''
+Button Behavior
+===============
+
+The :class:`~kivy.uix.behaviors.button.ButtonBehavior`
+`mixin <https://en.wikipedia.org/wiki/Mixin>`_ class provides
+:class:`~kivy.uix.button.Button` behavior. You can combine this class with
+other widgets, such as an :class:`~kivy.uix.image.Image`, to provide
+alternative buttons that preserve Kivy button behavior.
+
+For an overview of behaviors, please refer to the :mod:`~kivy.uix.behaviors`
+documentation.
+
+Example
+-------
+
+The following example adds button behavior to an image to make a checkbox that
+behaves like a button::
+
+    from kivy.app import App
+    from kivy.uix.image import Image
+    from kivy.uix.behaviors import ButtonBehavior
+
+
+    class MyButton(ButtonBehavior, Image):
+        def __init__(self, **kwargs):
+            super(MyButton, self).__init__(**kwargs)
+            self.source = 'atlas://data/images/defaulttheme/checkbox_off'
+
+        def on_press(self):
+            self.source = 'atlas://data/images/defaulttheme/checkbox_on'
+
+        def on_release(self):
+            self.source = 'atlas://data/images/defaulttheme/checkbox_off'
+
+
+    class SampleApp(App):
+        def build(self):
+            return MyButton()
+
+
+    SampleApp().run()
+
+See :class:`~kivy.uix.behaviors.ButtonBehavior` for details.
+'''
+
+__all__ = ('ButtonBehavior', )
+
+from kivy.clock import Clock
+from kivy.config import Config
+from kivy.properties import OptionProperty, ObjectProperty, \
+    BooleanProperty, NumericProperty
+from time import time
+
+
+class ButtonBehavior(object):
+    '''
+    This `mixin <https://en.wikipedia.org/wiki/Mixin>`_ class provides
+    :class:`~kivy.uix.button.Button` behavior. Please see the
+    :mod:`button behaviors module <kivy.uix.behaviors.button>` documentation
+    for more information.
+
+    :Events:
+        `on_press`
+            Fired when the button is pressed.
+        `on_release`
+            Fired when the button is released (i.e. the touch/click that
+            pressed the button goes away).
+
+    '''
+
+    state = OptionProperty('normal', options=('normal', 'down'))
+    '''The state of the button, must be one of 'normal' or 'down'.
+    The state is 'down' only when the button is currently touched/clicked,
+    otherwise its 'normal'.
+
+    :attr:`state` is an :class:`~kivy.properties.OptionProperty` and defaults
+    to 'normal'.
+    '''
+
+    last_touch = ObjectProperty(None)
+    '''Contains the last relevant touch received by the Button. This can
+    be used in `on_press` or `on_release` in order to know which touch
+    dispatched the event.
+
+    .. versionadded:: 1.8.0
+
+    :attr:`last_touch` is a :class:`~kivy.properties.ObjectProperty` and
+    defaults to `None`.
+    '''
+
+    min_state_time = NumericProperty(0)
+    '''The minimum period of time which the widget must remain in the
+    `'down'` state.
+
+    .. versionadded:: 1.9.1
+
+    :attr:`min_state_time` is a float and defaults to 0.035. This value is
+    taken from :class:`~kivy.config.Config`.
+    '''
+
+    always_release = BooleanProperty(False)
+    '''This determines whether or not the widget fires an `on_release` event if
+    the touch_up is outside the widget.
+
+    .. versionadded:: 1.9.0
+
+    .. versionchanged:: 1.10.0
+        The default value is now False.
+
+    :attr:`always_release` is a :class:`~kivy.properties.BooleanProperty` and
+    defaults to `False`.
+    '''
+
+    def __init__(self, **kwargs):
+        self.register_event_type('on_press')
+        self.register_event_type('on_release')
+        if 'min_state_time' not in kwargs:
+            self.min_state_time = float(Config.get('graphics',
+                                                   'min_state_time'))
+        super(ButtonBehavior, self).__init__(**kwargs)
+        self.__state_event = None
+        self.__touch_time = None
+        self.fbind('state', self.cancel_event)
+
+    def _do_press(self):
+        self.state = 'down'
+
+    def _do_release(self, *args):
+        self.state = 'normal'
+
+    def cancel_event(self, *args):
+        if self.__state_event:
+            self.__state_event.cancel()
+            self.__state_event = None
+
+    def on_touch_down(self, touch):
+        if super(ButtonBehavior, self).on_touch_down(touch):
+            return True
+        if touch.is_mouse_scrolling:
+            return False
+        if not self.collide_point(touch.x, touch.y):
+            return False
+        if self in touch.ud:
+            return False
+        touch.grab(self)
+        touch.ud[self] = True
+        self.last_touch = touch
+        self.__touch_time = time()
+        self._do_press()
+        self.dispatch('on_press')
+        return True
+
+    def on_touch_move(self, touch):
+        if touch.grab_current is self:
+            return True
+        if super(ButtonBehavior, self).on_touch_move(touch):
+            return True
+        return self in touch.ud
+
+    def on_touch_up(self, touch):
+        if touch.grab_current is not self:
+            return super(ButtonBehavior, self).on_touch_up(touch)
+        assert self in touch.ud
+        touch.ungrab(self)
+        self.last_touch = touch
+
+        if (not self.always_release and
+                not self.collide_point(*touch.pos)):
+            self._do_release()
+            return
+
+        touchtime = time() - self.__touch_time
+        if touchtime < self.min_state_time:
+            self.__state_event = Clock.schedule_once(
+                self._do_release, self.min_state_time - touchtime)
+        else:
+            self._do_release()
+        self.dispatch('on_release')
+        return True
+
+    def on_press(self):
+        pass
+
+    def on_release(self):
+        pass
+
+    def trigger_action(self, duration=0.1):
+        '''Trigger whatever action(s) have been bound to the button by calling
+        both the on_press and on_release callbacks.
+
+        This is similar to a quick button press without using any touch events,
+        but note that like most kivy code, this is not guaranteed to be safe to
+        call from external threads. If needed use
+        :class:`Clock <kivy.clock.Clock>` to safely schedule this function and
+        the resulting callbacks to be called from the main thread.
+
+        Duration is the length of the press in seconds. Pass 0 if you want
+        the action to happen instantly.
+
+        .. versionadded:: 1.8.0
+        '''
+        self._do_press()
+        self.dispatch('on_press')
+
+        def trigger_release(dt):
+            self._do_release()
+            self.dispatch('on_release')
+        if not duration:
+            trigger_release(0)
+        else:
+            Clock.schedule_once(trigger_release, duration)

kivy/uix/behaviors/codenavigation.py

@@ -0,0 +1,167 @@
+'''
+Code Navigation Behavior
+========================
+
+The :class:`~kivy.uix.bahviors.CodeNavigationBehavior` modifies navigation
+behavior in the :class:`~kivy.uix.textinput.TextInput`, making it work like an
+IDE instead of a word processor.
+
+Using this mixin gives the TextInput the ability to recognize whitespace,
+punctuation and case variations (e.g. CamelCase) when moving over text. It
+is currently used by the :class:`~kivy.uix.codeinput.CodeInput` widget.
+'''
+
+__all__ = ('CodeNavigationBehavior', )
+
+from kivy.event import EventDispatcher
+import string
+
+
+class CodeNavigationBehavior(EventDispatcher):
+    '''Code navigation behavior. Modifies the navigation behavior in TextInput
+    to work like an IDE instead of a word processor. Please see the
+    :mod:`code navigation behaviors module <kivy.uix.behaviors.codenavigation>`
+    documentation for more information.
+
+    .. versionadded:: 1.9.1
+    '''
+
+    def _move_cursor_word_left(self, index=None):
+        pos = index or self.cursor_index()
+        pos -= 1
+
+        if pos == 0:
+            return 0, 0
+
+        col, row = self.get_cursor_from_index(pos)
+        lines = self._lines
+
+        ucase = string.ascii_uppercase
+        lcase = string.ascii_lowercase
+        ws = string.whitespace
+        punct = string.punctuation
+
+        mode = 'normal'
+
+        rline = lines[row]
+        c = rline[col] if len(rline) > col else '\n'
+        if c in ws:
+            mode = 'ws'
+        elif c == '_':
+            mode = 'us'
+        elif c in punct:
+            mode = 'punct'
+        elif c not in ucase:
+            mode = 'camel'
+
+        while True:
+            if col == -1:
+                if row == 0:
+                    return 0, 0
+                row -= 1
+                rline = lines[row]
+                col = len(rline)
+            lc = c
+            c = rline[col] if len(rline) > col else '\n'
+            if c == '\n':
+                if lc not in ws:
+                    col += 1
+                break
+            if mode in ('normal', 'camel') and c in ws:
+                col += 1
+                break
+            if mode in ('normal', 'camel') and c in punct:
+                col += 1
+                break
+            if mode == 'camel' and c in ucase:
+                break
+            if mode == 'punct' and (c == '_' or c not in punct):
+                col += 1
+                break
+            if mode == 'us' and c != '_' and (c in punct or c in ws):
+                col += 1
+                break
+
+            if mode == 'us' and c != '_':
+                mode = ('normal' if c in ucase
+                        else 'ws' if c in ws
+                else 'camel')
+            elif mode == 'ws' and c not in ws:
+                mode = ('normal' if c in ucase
+                        else 'us' if c == '_'
+                else 'punct' if c in punct
+                else 'camel')
+
+            col -= 1
+
+        if col > len(rline):
+            if row == len(lines) - 1:
+                return row, len(lines[row])
+            row += 1
+            col = 0
+
+        return col, row
+
+    def _move_cursor_word_right(self, index=None):
+        pos = index or self.cursor_index()
+        col, row = self.get_cursor_from_index(pos)
+        lines = self._lines
+        mrow = len(lines) - 1
+
+        if row == mrow and col == len(lines[row]):
+            return col, row
+
+        ucase = string.ascii_uppercase
+        lcase = string.ascii_lowercase
+        ws = string.whitespace
+        punct = string.punctuation
+
+        mode = 'normal'
+
+        rline = lines[row]
+        c = rline[col] if len(rline) > col else '\n'
+        if c in ws:
+            mode = 'ws'
+        elif c == '_':
+            mode = 'us'
+        elif c in punct:
+            mode = 'punct'
+        elif c in lcase:
+            mode = 'camel'
+
+        while True:
+            if mode in ('normal', 'camel', 'punct') and c in ws:
+                mode = 'ws'
+            elif mode in ('normal', 'camel') and c == '_':
+                mode = 'us'
+            elif mode == 'normal' and c not in ucase:
+                mode = 'camel'
+
+            if mode == 'us':
+                if c in ws:
+                    mode = 'ws'
+                elif c != '_':
+                    break
+            if mode == 'ws' and c not in ws:
+                break
+            if mode == 'camel' and c in ucase:
+                break
+            if mode == 'punct' and (c == '_' or c not in punct):
+                break
+            if mode != 'punct' and c != '_' and c in punct:
+                break
+
+            col += 1
+
+            if col > len(rline):
+                if row == mrow:
+                    return len(rline), mrow
+                row += 1
+                rline = lines[row]
+                col = 0
+
+            c = rline[col] if len(rline) > col else '\n'
+            if c == '\n':
+                break
+
+        return col, row