From 61769b5db8268c1350e42b4f6948d57fd8f58259 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=98=D0=B2=D0=B0=D0=BD=D0=BE=D0=B2=20=D0=AE=D1=80=D0=B8?= =?UTF-8?q?=D0=B9?= Date: Fri, 17 May 2024 17:17:30 +0300 Subject: [PATCH] Fix doc strings. --- kivymd/uix/scrollview.py | 141 +++++++++++++++++++++++++++++++++++---- 1 file changed, 129 insertions(+), 12 deletions(-) diff --git a/kivymd/uix/scrollview.py b/kivymd/uix/scrollview.py index 66bba74fc..aaea955d2 100644 --- a/kivymd/uix/scrollview.py +++ b/kivymd/uix/scrollview.py @@ -4,7 +4,8 @@ .. versionadded:: 1.0.0 -:class:`~kivy.uix.scrollview.ScrollView` class equivalent. It implements Material Design's overscorll effect and +:class:`~kivy.uix.scrollview.ScrollView` class equivalent. +It implements Material Design's overscorll effect and simplifies working with some widget properties. For example: ScrollView @@ -28,6 +29,119 @@ MDScrollView: md_bg_color: app.theme_cls.primaryColor + +The stretching effect +--------------------- + +.. code-block:: python + + import os + import sys + + from kivy.core.window import Window + from kivy import __version__ as kv__version__ + from kivy.lang import Builder + from kivy.metrics import dp + + from kivymd.app import MDApp + from kivymd import __version__ + from kivymd.uix.list import ( + MDListItem, + MDListItemHeadlineText, + MDListItemSupportingText, + MDListItemLeadingIcon, + ) + + from materialyoucolor import __version__ as mc__version__ + + from examples.common_app import CommonApp + + MAIN_KV = ''' + MDScreen: + md_bg_color: app.theme_cls.backgroundColor + + MDScrollView: + do_scroll_x: False + + MDBoxLayout: + id: main_scroll + orientation: "vertical" + adaptive_height: True + + MDBoxLayout: + adaptive_height: True + + MDLabel: + theme_font_size: "Custom" + text: "OS Info" + font_size: "55sp" + adaptive_height: True + padding: "10dp", "20dp", 0, 0 + + MDIconButton: + icon: "menu" + on_release: app.open_menu(self) + pos_hint: {"center_y": .5} + ''' + + + class Example(MDApp, CommonApp): + def build(self): + self.theme_cls.theme_style = "Dark" + return Builder.load_string(MAIN_KV) + + def on_start(self): + info = { + "Name": [ + os.name, + ( + "microsoft" + if os.name == "nt" + else ("linux" if os.uname()[0] != "Darwin" else "apple") + ), + ], + "Architecture": [os.uname().machine, "memory"], + "Hostname": [os.uname().nodename, "account"], + "Python Version": ["v" + sys.version, "language-python"], + "Kivy Version": ["v" + kv__version__, "alpha-k-circle-outline"], + "KivyMD Version": ["v" + __version__, "material-design"], + "MaterialYouColor Version": ["v" + mc__version__, "invert-colors"], + "Pillow Version": ["Unknown", "image"], + "Working Directory": [os.getcwd(), "folder"], + "Home Directory": [os.path.expanduser("~"), "folder-account"], + "Environment Variables": [os.environ, "code-json"], + } + + try: + from PIL import __version__ as pil__version_ + + info["Pillow Version"] = ["v" + pil__version_, "image"] + except Exception: + pass + + for info_item in info: + self.root.ids.main_scroll.add_widget( + MDListItem( + MDListItemLeadingIcon( + icon=info[info_item][1], + ), + MDListItemHeadlineText( + text=info_item, + ), + MDListItemSupportingText( + text=str(info[info_item][0]), + ), + pos_hint={"center_x": .5, "center_y": .5}, + ) + ) + + Window.size = [dp(350), dp(600)] + + + Example().run() + +.. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/stretch_over_scroll_stencil.gif + :align: center """ from __future__ import annotations @@ -48,25 +162,27 @@ class StretchOverScrollStencil(ScrollEffect): """ Stretches the view on overscroll and absorbs velocity at start and end to convert to stretch. - .. note:: This effect only works with :class:`kivymd.uix.scrollview.MDScrollView`. + + .. note:: This effect only works with + :class:`kivymd.uix.scrollview.MDScrollView`. + If you need any documentation please look at :class:`~kivy.effects.dampedscrolleffect`. """ - # Android constants + # Android constants. minimum_absorbed_velocity = 0 maximum_velocity = 10000 stretch_intensity = 0.016 exponential_scalar = math.e / (1 / 3) scroll_friction = 0.015 - # Used in `absorb_impact` but for now - # it's not compatible with kivy so we using - # are approx value. + # Used in `absorb_impact` but for now it's not compatible with kivy so we + # using are approx value. # fling_friction = 1.01 approx_normailzer = 2e5 # Duration to normalize scale - # when touch up is recieved and view is stretched + # when touch up is received and view is stretched. duration_normailzer = 10 scroll_view = None # scroll view instance @@ -97,7 +213,8 @@ def on_value(self, stencil, scroll_distance): if self.is_top_or_bottom(): if ( abs(self.velocity) > self.minimum_absorbed_velocity - and self._should_absorb # only first time when reaches top or bottom + and self._should_absorb # only first time when reaches + # top or bottom ): self.absorb_impact() self._should_absorb = False @@ -109,7 +226,7 @@ def get_hw(self): def set_scale_origin(self): # Check if target size is small than scrollview - # if yes don't stretch scroll view + # if yes don't stretch scroll view. if getattr(self.target_widget, self.get_hw()) < getattr( self.scroll_view, self.get_hw() ): @@ -150,7 +267,7 @@ def convert_overscroll(self, touch): and self.velocity == 0 and self.set_scale_origin() # sets stretch direction ): - # Distance travelled by touch divided by size of scrollview + # Distance travelled by touch divided by size of scrollview. distance = ( abs( self.get_component(touch.pos) @@ -158,9 +275,9 @@ def convert_overscroll(self, touch): ) / self.scroll_view.height ) - # constant scale due to distance + # Constant scale due to distance. linear_intensity = self.stretch_intensity * distance - # Far the touch -> less it stretches + # Far the touch -> less it stretches. exponential_intensity = self.stretch_intensity * ( 1 - math.exp(-distance * self.exponential_scalar) )