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

kivy/uix/behaviors/togglebutton.py

@@ -0,0 +1,156 @@
+'''
+ToggleButton Behavior
+=====================
+
+The :class:`~kivy.uix.behaviors.togglebutton.ToggleButtonBehavior`
+`mixin <https://en.wikipedia.org/wiki/Mixin>`_ class provides
+:class:`~kivy.uix.togglebutton.ToggleButton` behavior. You can combine this
+class with other widgets, such as an :class:`~kivy.uix.image.Image`, to provide
+alternative togglebuttons that preserve Kivy togglebutton behavior.
+
+For an overview of behaviors, please refer to the :mod:`~kivy.uix.behaviors`
+documentation.
+
+Example
+-------
+
+The following example adds togglebutton behavior to an image to make a checkbox
+that behaves like a togglebutton::
+
+    from kivy.app import App
+    from kivy.uix.image import Image
+    from kivy.uix.behaviors import ToggleButtonBehavior
+
+
+    class MyButton(ToggleButtonBehavior, Image):
+        def __init__(self, **kwargs):
+            super(MyButton, self).__init__(**kwargs)
+            self.source = 'atlas://data/images/defaulttheme/checkbox_off'
+
+        def on_state(self, widget, value):
+            if value == 'down':
+                self.source = 'atlas://data/images/defaulttheme/checkbox_on'
+            else:
+                self.source = 'atlas://data/images/defaulttheme/checkbox_off'
+
+
+    class SampleApp(App):
+        def build(self):
+            return MyButton()
+
+
+    SampleApp().run()
+'''
+
+__all__ = ('ToggleButtonBehavior', )
+
+from kivy.properties import ObjectProperty, BooleanProperty
+from kivy.uix.behaviors.button import ButtonBehavior
+from weakref import ref
+
+
+class ToggleButtonBehavior(ButtonBehavior):
+    '''This `mixin <https://en.wikipedia.org/wiki/Mixin>`_ class provides
+    :mod:`~kivy.uix.togglebutton` behavior. Please see the
+    :mod:`togglebutton behaviors module <kivy.uix.behaviors.togglebutton>`
+    documentation for more information.
+
+    .. versionadded:: 1.8.0
+    '''
+
+    __groups = {}
+
+    group = ObjectProperty(None, allownone=True)
+    '''Group of the button. If `None`, no group will be used (the button will be
+    independent). If specified, :attr:`group` must be a hashable object, like
+    a string. Only one button in a group can be in a 'down' state.
+
+    :attr:`group` is a :class:`~kivy.properties.ObjectProperty` and defaults to
+    `None`.
+    '''
+
+    allow_no_selection = BooleanProperty(True)
+    '''This specifies whether the widgets in a group allow no selection i.e.
+    everything to be deselected.
+
+    .. versionadded:: 1.9.0
+
+    :attr:`allow_no_selection` is a :class:`BooleanProperty` and defaults to
+    `True`
+    '''
+
+    def __init__(self, **kwargs):
+        self._previous_group = None
+        super(ToggleButtonBehavior, self).__init__(**kwargs)
+
+    def on_group(self, *largs):
+        groups = ToggleButtonBehavior.__groups
+        if self._previous_group:
+            group = groups[self._previous_group]
+            for item in group[:]:
+                if item() is self:
+                    group.remove(item)
+                    break
+        group = self._previous_group = self.group
+        if group not in groups:
+            groups[group] = []
+        r = ref(self, ToggleButtonBehavior._clear_groups)
+        groups[group].append(r)
+
+    def _release_group(self, current):
+        if self.group is None:
+            return
+        group = self.__groups[self.group]
+        for item in group[:]:
+            widget = item()
+            if widget is None:
+                group.remove(item)
+            if widget is current:
+                continue
+            widget.state = 'normal'
+
+    def _do_press(self):
+        if (not self.allow_no_selection and
+                self.group and self.state == 'down'):
+            return
+
+        self._release_group(self)
+        self.state = 'normal' if self.state == 'down' else 'down'
+
+    def _do_release(self, *args):
+        pass
+
+    @staticmethod
+    def _clear_groups(wk):
+        # auto flush the element when the weak reference have been deleted
+        groups = ToggleButtonBehavior.__groups
+        for group in list(groups.values()):
+            if wk in group:
+                group.remove(wk)
+                break
+
+    @staticmethod
+    def get_widgets(groupname):
+        '''Return a list of the widgets contained in a specific group. If the
+        group doesn't exist, an empty list will be returned.
+
+        .. note::
+
+            Always release the result of this method! Holding a reference to
+            any of these widgets can prevent them from being garbage collected.
+            If in doubt, do::
+
+                l = ToggleButtonBehavior.get_widgets('mygroup')
+                # do your job
+                del l
+
+        .. warning::
+
+            It's possible that some widgets that you have previously
+            deleted are still in the list. The garbage collector might need
+            to release other objects before flushing them.
+        '''
+        groups = ToggleButtonBehavior.__groups
+        if groupname not in groups:
+            return []
+        return [x() for x in groups[groupname] if x()][:]

kivy/uix/behaviors/touchripple.py

@@ -0,0 +1,318 @@
+'''
+Touch Ripple
+============
+
+.. versionadded:: 1.10.1
+
+.. warning::
+    This code is still experimental, and its API is subject to change in a
+    future version.
+
+This module contains `mixin <https://en.wikipedia.org/wiki/Mixin>`_ classes
+to add a touch ripple visual effect known from `Google Material Design
+<https://en.wikipedia.org/wiki/Material_Design>_` to widgets.
+
+For an overview of behaviors, please refer to the :mod:`~kivy.uix.behaviors`
+documentation.
+
+The class :class:`~kivy.uix.behaviors.touchripple.TouchRippleBehavior` provides
+rendering the ripple animation.
+
+The class :class:`~kivy.uix.behaviors.touchripple.TouchRippleButtonBehavior`
+basically provides the same functionality as
+:class:`~kivy.uix.behaviors.button.ButtonBehavior` but rendering the ripple
+animation instead of default press/release visualization.
+'''
+from kivy.animation import Animation
+from kivy.clock import Clock
+from kivy.graphics import CanvasBase, Color, Ellipse, ScissorPush, ScissorPop
+from kivy.properties import BooleanProperty, ListProperty, NumericProperty, \
+    ObjectProperty, StringProperty
+from kivy.uix.relativelayout import RelativeLayout
+
+
+__all__ = (
+    'TouchRippleBehavior',
+    'TouchRippleButtonBehavior'
+)
+
+
+class TouchRippleBehavior(object):
+    '''Touch ripple behavior.
+
+    Supposed to be used as mixin on widget classes.
+
+    Ripple behavior does not trigger automatically, concrete implementation
+    needs to call :func:`ripple_show` respective :func:`ripple_fade` manually.
+
+    Example
+    -------
+
+    Here we create a Label which renders the touch ripple animation on
+    interaction::
+
+        class RippleLabel(TouchRippleBehavior, Label):
+
+            def __init__(self, **kwargs):
+                super(RippleLabel, self).__init__(**kwargs)
+
+            def on_touch_down(self, touch):
+                collide_point = self.collide_point(touch.x, touch.y)
+                if collide_point:
+                    touch.grab(self)
+                    self.ripple_show(touch)
+                    return True
+                return False
+
+            def on_touch_up(self, touch):
+                if touch.grab_current is self:
+                    touch.ungrab(self)
+                    self.ripple_fade()
+                    return True
+                return False
+    '''
+
+    ripple_rad_default = NumericProperty(10)
+    '''Default radius the animation starts from.
+
+    :attr:`ripple_rad_default` is a :class:`~kivy.properties.NumericProperty`
+    and defaults to `10`.
+    '''
+
+    ripple_duration_in = NumericProperty(.5)
+    '''Animation duration taken to show the overlay.
+
+    :attr:`ripple_duration_in` is a :class:`~kivy.properties.NumericProperty`
+    and defaults to `0.5`.
+    '''
+
+    ripple_duration_out = NumericProperty(.2)
+    '''Animation duration taken to fade the overlay.
+
+    :attr:`ripple_duration_out` is a :class:`~kivy.properties.NumericProperty`
+    and defaults to `0.2`.
+    '''
+
+    ripple_fade_from_alpha = NumericProperty(.5)
+    '''Alpha channel for ripple color the animation starts with.
+
+    :attr:`ripple_fade_from_alpha` is a
+    :class:`~kivy.properties.NumericProperty` and defaults to `0.5`.
+    '''
+
+    ripple_fade_to_alpha = NumericProperty(.8)
+    '''Alpha channel for ripple color the animation targets to.
+
+    :attr:`ripple_fade_to_alpha` is a :class:`~kivy.properties.NumericProperty`
+    and defaults to `0.8`.
+    '''
+
+    ripple_scale = NumericProperty(2.)
+    '''Max scale of the animation overlay calculated from max(width/height) of
+    the decorated widget.
+
+    :attr:`ripple_scale` is a :class:`~kivy.properties.NumericProperty`
+    and defaults to `2.0`.
+    '''
+
+    ripple_func_in = StringProperty('in_cubic')
+    '''Animation callback for showing the overlay.
+
+    :attr:`ripple_func_in` is a :class:`~kivy.properties.StringProperty`
+    and defaults to `in_cubic`.
+    '''
+
+    ripple_func_out = StringProperty('out_quad')
+    '''Animation callback for hiding the overlay.
+
+    :attr:`ripple_func_out` is a :class:`~kivy.properties.StringProperty`
+    and defaults to `out_quad`.
+    '''
+
+    ripple_rad = NumericProperty(10)
+    ripple_pos = ListProperty([0, 0])
+    ripple_color = ListProperty((1., 1., 1., .5))
+
+    def __init__(self, **kwargs):
+        super(TouchRippleBehavior, self).__init__(**kwargs)
+        self.ripple_pane = CanvasBase()
+        self.canvas.add(self.ripple_pane)
+        self.bind(
+            ripple_color=self._ripple_set_color,
+            ripple_pos=self._ripple_set_ellipse,
+            ripple_rad=self._ripple_set_ellipse
+        )
+        self.ripple_ellipse = None
+        self.ripple_col_instruction = None
+
+    def ripple_show(self, touch):
+        '''Begin ripple animation on current widget.
+
+        Expects touch event as argument.
+        '''
+        Animation.cancel_all(self, 'ripple_rad', 'ripple_color')
+        self._ripple_reset_pane()
+        x, y = self.to_window(*self.pos)
+        width, height = self.size
+        if isinstance(self, RelativeLayout):
+            self.ripple_pos = ripple_pos = (touch.x - x, touch.y - y)
+        else:
+            self.ripple_pos = ripple_pos = (touch.x, touch.y)
+        rc = self.ripple_color
+        ripple_rad = self.ripple_rad
+        self.ripple_color = [rc[0], rc[1], rc[2], self.ripple_fade_from_alpha]
+        with self.ripple_pane:
+            ScissorPush(
+                x=int(round(x)),
+                y=int(round(y)),
+                width=int(round(width)),
+                height=int(round(height))
+            )
+            self.ripple_col_instruction = Color(rgba=self.ripple_color)
+            self.ripple_ellipse = Ellipse(
+                size=(ripple_rad, ripple_rad),
+                pos=(
+                    ripple_pos[0] - ripple_rad / 2.,
+                    ripple_pos[1] - ripple_rad / 2.
+                )
+            )
+            ScissorPop()
+        anim = Animation(
+            ripple_rad=max(width, height) * self.ripple_scale,
+            t=self.ripple_func_in,
+            ripple_color=[rc[0], rc[1], rc[2], self.ripple_fade_to_alpha],
+            duration=self.ripple_duration_in
+        )
+        anim.start(self)
+
+    def ripple_fade(self):
+        '''Finish ripple animation on current widget.
+        '''
+        Animation.cancel_all(self, 'ripple_rad', 'ripple_color')
+        width, height = self.size
+        rc = self.ripple_color
+        duration = self.ripple_duration_out
+        anim = Animation(
+            ripple_rad=max(width, height) * self.ripple_scale,
+            ripple_color=[rc[0], rc[1], rc[2], 0.],
+            t=self.ripple_func_out,
+            duration=duration
+        )
+        anim.bind(on_complete=self._ripple_anim_complete)
+        anim.start(self)
+
+    def _ripple_set_ellipse(self, instance, value):
+        ellipse = self.ripple_ellipse
+        if not ellipse:
+            return
+        ripple_pos = self.ripple_pos
+        ripple_rad = self.ripple_rad
+        ellipse.size = (ripple_rad, ripple_rad)
+        ellipse.pos = (
+            ripple_pos[0] - ripple_rad / 2.,
+            ripple_pos[1] - ripple_rad / 2.
+        )
+
+    def _ripple_set_color(self, instance, value):
+        if not self.ripple_col_instruction:
+            return
+        self.ripple_col_instruction.rgba = value
+
+    def _ripple_anim_complete(self, anim, instance):
+        self._ripple_reset_pane()
+
+    def _ripple_reset_pane(self):
+        self.ripple_rad = self.ripple_rad_default
+        self.ripple_pane.clear()
+
+
+class TouchRippleButtonBehavior(TouchRippleBehavior):
+    '''
+    This `mixin <https://en.wikipedia.org/wiki/Mixin>`_ class provides
+    a similar behavior to :class:`~kivy.uix.behaviors.button.ButtonBehavior`
+    but provides touch ripple animation instead of button pressed/released as
+    visual effect.
+
+    :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).
+    '''
+
+    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.
+
+    :attr:`last_touch` is a :class:`~kivy.properties.ObjectProperty` and
+    defaults to `None`.
+    '''
+
+    always_release = BooleanProperty(False)
+    '''This determines whether or not the widget fires an `on_release` event if
+    the touch_up is outside the widget.
+
+    :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')
+        super(TouchRippleButtonBehavior, self).__init__(**kwargs)
+
+    def on_touch_down(self, touch):
+        if super(TouchRippleButtonBehavior, 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.ripple_show(touch)
+        self.dispatch('on_press')
+        return True
+
+    def on_touch_move(self, touch):
+        if touch.grab_current is self:
+            return True
+        if super(TouchRippleButtonBehavior, 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(TouchRippleButtonBehavior, self).on_touch_up(touch)
+        assert self in touch.ud
+        touch.ungrab(self)
+        self.last_touch = touch
+        if self.disabled:
+            return
+        self.ripple_fade()
+        if not self.always_release and not self.collide_point(*touch.pos):
+            return
+
+        # defer on_release until ripple_fade has completed
+        def defer_release(dt):
+            self.dispatch('on_release')
+        Clock.schedule_once(defer_release, self.ripple_duration_out)
+        return True
+
+    def on_disabled(self, instance, value):
+        # ensure ripple animation completes if disabled gets set to True
+        if value:
+            self.ripple_fade()
+        return super(TouchRippleButtonBehavior, self).on_disabled(
+            instance, value)
+
+    def on_press(self):
+        pass
+
+    def on_release(self):
+        pass