first commit

kivy_venv/lib/python3.11/site-packages/kivymd/effects/stiffscroll/__init__.py

@@ -0,0 +1 @@
+from .stiffscroll import StiffScrollEffect

kivy_venv/lib/python3.11/site-packages/kivymd/effects/stiffscroll/stiffscroll.py

@@ -0,0 +1,215 @@
+"""
+Effects/StiffScrollEffect
+=========================
+
+An Effect to be used with ScrollView to prevent scrolling beyond
+the bounds, but politely.
+
+A ScrollView constructed with StiffScrollEffect,
+eg. ScrollView(effect_cls=StiffScrollEffect), will get harder to
+scroll as you get nearer to its edges. You can scroll all the way to
+the edge if you want to, but it will take more finger-movement than
+usual.
+
+Unlike DampedScrollEffect, it is impossible to overscroll with
+StiffScrollEffect. That means you cannot push the contents of the
+ScrollView far enough to see what's beneath them. This is appropriate
+if the ScrollView contains, eg., a background image, like a desktop
+wallpaper. Overscrolling may give the impression that there is some
+reason to overscroll, even if just to take a peek beneath, and that
+impression may be misleading.
+
+StiffScrollEffect was written by Zachary Spector. His other stuff is at:
+https://github.com/LogicalDash/
+He can be reached, and possibly hired, at:
+zacharyspector@gmail.com
+
+"""
+
+from time import time
+
+from kivy.animation import AnimationTransition
+from kivy.effects.kinetic import KineticEffect
+from kivy.properties import NumericProperty, ObjectProperty
+from kivy.uix.widget import Widget
+
+
+class StiffScrollEffect(KineticEffect):
+    drag_threshold = NumericProperty("20sp")
+    """Minimum distance to travel before the movement is considered as a
+    drag.
+
+    :attr:`drag_threshold` is an :class:`~kivy.properties.NumericProperty`
+    and defaults to `'20sp'`.
+    """
+
+    min = NumericProperty(0)
+    """Minimum boundary to stop the scrolling at.
+
+    :attr:`min` is an :class:`~kivy.properties.NumericProperty`
+    and defaults to `0`.
+    """
+
+    max = NumericProperty(0)
+    """Maximum boundary to stop the scrolling at.
+
+    :attr:`max` is an :class:`~kivy.properties.NumericProperty`
+    and defaults to `0`.
+    """
+
+    max_friction = NumericProperty(1)
+    """How hard should it be to scroll, at the worst?
+
+    :attr:`max_friction` is an :class:`~kivy.properties.NumericProperty`
+    and defaults to `1`.
+    """
+
+    body = NumericProperty(0.7)
+    """Proportion of the range in which you can scroll unimpeded.
+
+    :attr:`body` is an :class:`~kivy.properties.NumericProperty`
+    and defaults to `0.7`.
+    """
+
+    scroll = NumericProperty(0.0)
+    """Computed value for scrolling
+
+    :attr:`scroll` is an :class:`~kivy.properties.NumericProperty`
+    and defaults to `0.0`.
+    """
+
+    transition_min = ObjectProperty(AnimationTransition.in_cubic)
+    """The AnimationTransition function to use when adjusting the friction
+    near the minimum end of the effect.
+
+    :attr:`transition_min` is an :class:`~kivy.properties.ObjectProperty`
+    and defaults to :class:`kivy.animation.AnimationTransition`.
+    """
+
+    transition_max = ObjectProperty(AnimationTransition.in_cubic)
+    """The AnimationTransition function to use when adjusting the friction
+    near the maximum end of the effect.
+
+    :attr:`transition_max` is an :class:`~kivy.properties.ObjectProperty`
+    and defaults to :class:`kivy.animation.AnimationTransition`.
+    """
+
+    target_widget = ObjectProperty(None, allownone=True, baseclass=Widget)
+    """The widget to apply the effect to.
+
+    :attr:`target_widget` is an :class:`~kivy.properties.ObjectProperty`
+    and defaults to ``None``.
+    """
+
+    displacement = NumericProperty(0)
+    """The absolute distance moved in either direction.
+
+    :attr:`displacement` is an :class:`~kivy.properties.NumericProperty`
+    and defaults to `0`.
+    """
+
+    def __init__(self, **kwargs):
+        """Set ``self.base_friction`` to the value of ``self.friction`` just
+        after instantiation, so that I can reset to that value later.
+        """
+
+        super().__init__(**kwargs)
+        self.base_friction = self.friction
+
+    def update_velocity(self, dt):
+        """Before actually updating my velocity, meddle with ``self.friction``
+        to make it appropriate to where I'm at, currently.
+        """
+
+        hard_min = self.min
+        hard_max = self.max
+        if hard_min > hard_max:
+            hard_min, hard_max = hard_max, hard_min
+
+        margin = (1.0 - self.body) * (hard_max - hard_min)
+        soft_min = hard_min + margin
+        soft_max = hard_max - margin
+
+        if self.value < soft_min:
+            try:
+                prop = (soft_min - self.value) / (soft_min - hard_min)
+                self.friction = self.base_friction + abs(
+                    self.max_friction - self.base_friction
+                ) * self.transition_min(prop)
+            except ZeroDivisionError:
+                pass
+        elif self.value > soft_max:
+            try:
+                # normalize how far past soft_max I've gone as a
+                # proportion of the distance between soft_max and hard_max
+                prop = (self.value - soft_max) / (hard_max - soft_max)
+                self.friction = self.base_friction + abs(
+                    self.max_friction - self.base_friction
+                ) * self.transition_min(prop)
+            except ZeroDivisionError:
+                pass
+        else:
+            self.friction = self.base_friction
+
+        return super().update_velocity(dt)
+
+    def on_value(self, *args):
+        """Prevent moving beyond my bounds, and update ``self.scroll``"""
+
+        if self.value > self.min:
+            self.velocity = 0
+            self.scroll = self.min
+        elif self.value < self.max:
+            self.velocity = 0
+            self.scroll = self.max
+        else:
+            self.scroll = self.value
+
+    def start(self, val, t=None):
+        """Start movement with ``self.friction`` = ``self.base_friction``"""
+
+        self.is_manual = True
+        t = t or time()
+        self.velocity = self.displacement = 0
+        self.friction = self.base_friction
+        self.history = [(t, val)]
+
+    def update(self, val, t=None):
+        """Reduce the impact of whatever change has been made to me, in
+        proportion with my current friction.
+        """
+
+        t = t or time()
+        hard_min = self.min
+        hard_max = self.max
+        if hard_min > hard_max:
+            hard_min, hard_max = hard_max, hard_min
+
+        gamut = hard_max - hard_min
+        margin = (1.0 - self.body) * gamut
+        soft_min = hard_min + margin
+        soft_max = hard_max - margin
+        distance = val - self.history[-1][1]
+        reach = distance + self.value
+
+        if (distance < 0 and reach < soft_min) or (
+            distance > 0 and soft_max < reach
+        ):
+            distance -= distance * self.friction
+        self.apply_distance(distance)
+        self.history.append((t, val))
+
+        if len(self.history) > self.max_history:
+            self.history.pop(0)
+        self.displacement += abs(distance)
+        self.trigger_velocity_update()
+
+    def stop(self, val, t=None):
+        """Work out whether I've been flung."""
+
+        self.is_manual = False
+        self.displacement += abs(val - self.history[-1][1])
+        if self.displacement <= self.drag_threshold:
+            self.velocity = 0
+
+        return super().stop(val, t)