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

kivy/uix/scrollview.py

@@ -0,0 +1,1288 @@
+'''
+ScrollView
+==========
+
+.. versionadded:: 1.0.4
+
+The :class:`ScrollView` widget provides a scrollable/pannable viewport that is
+clipped at the scrollview's bounding box.
+
+.. note::
+    Use :class:`~kivy.uix.recycleview.RecycleView` for generating large
+    numbers of widgets in order to display many data items.
+
+
+Scrolling Behavior
+------------------
+
+The ScrollView accepts only one child and applies a viewport/window to
+it according to the :attr:`~ScrollView.scroll_x` and
+:attr:`~ScrollView.scroll_y` properties. Touches are analyzed to
+determine if the user wants to scroll or control the child in some
+other manner: you cannot do both at the same time. To determine if
+interaction is a scrolling gesture, these properties are used:
+
+    - :attr:`~ScrollView.scroll_distance`: the minimum distance to travel,
+      defaults to 20 pixels.
+    - :attr:`~ScrollView.scroll_timeout`: the maximum time period, defaults
+      to 55 milliseconds.
+
+If a touch travels :attr:`~ScrollView.scroll_distance` pixels within the
+:attr:`~ScrollView.scroll_timeout` period, it is recognized as a scrolling
+gesture and translation (scroll/pan) will begin. If the timeout occurs, the
+touch down event is dispatched to the child instead (no translation).
+
+The default value for those settings can be changed in the configuration file::
+
+    [widgets]
+    scroll_timeout = 250
+    scroll_distance = 20
+
+.. versionadded:: 1.1.1
+
+    ScrollView now animates scrolling in Y when a mousewheel is used.
+
+
+Limiting to the X or Y Axis
+---------------------------
+
+By default, the ScrollView allows scrolling along both the X and Y axes. You
+can explicitly disable scrolling on an axis by setting the
+:attr:`~ScrollView.do_scroll_x` or :attr:`~ScrollView.do_scroll_y` properties
+to False.
+
+
+Managing the Content Size and Position
+--------------------------------------
+
+The ScrollView manages the position of its children similarly to a
+:class:`~kivy.uix.relativelayout.RelativeLayout` but does not use the
+:attr:`~kivy.uix.widget.Widget.size_hint`. You must
+carefully specify the :attr:`~kivy.uix.widget.Widget.size` of your content to
+get the desired scroll/pan effect.
+
+By default, the :attr:`~kivy.uix.widget.Widget.size_hint` is (1, 1), so the
+content size will fit your ScrollView
+exactly (you will have nothing to scroll). You must deactivate at least one of
+the size_hint instructions (x or y) of the child to enable scrolling.
+Setting :attr:`~kivy.uix.widget.Widget.size_hint_min` to not be None will
+also enable scrolling for that dimension when the :class:`ScrollView` is
+smaller than the minimum size.
+
+To scroll a :class:`~kivy.uix.gridlayout.GridLayout` on it's Y-axis/vertically,
+set the child's width  to that of the ScrollView (size_hint_x=1), and set
+the size_hint_y property to None::
+
+    from kivy.uix.gridlayout import GridLayout
+    from kivy.uix.button import Button
+    from kivy.uix.scrollview import ScrollView
+    from kivy.core.window import Window
+    from kivy.app import runTouchApp
+
+    layout = GridLayout(cols=1, spacing=10, size_hint_y=None)
+    # Make sure the height is such that there is something to scroll.
+    layout.bind(minimum_height=layout.setter('height'))
+    for i in range(100):
+        btn = Button(text=str(i), size_hint_y=None, height=40)
+        layout.add_widget(btn)
+    root = ScrollView(size_hint=(1, None), size=(Window.width, Window.height))
+    root.add_widget(layout)
+
+    runTouchApp(root)
+
+
+Kv Example::
+
+    ScrollView:
+        do_scroll_x: False
+        do_scroll_y: True
+
+        Label:
+            size_hint_y: None
+            height: self.texture_size[1]
+            text_size: self.width, None
+            padding: 10, 10
+            text:
+                'really some amazing text\\n' * 100
+
+Overscroll Effects
+------------------
+
+.. versionadded:: 1.7.0
+
+When scrolling would exceed the bounds of the :class:`ScrollView`, it
+uses a :class:`~kivy.effects.scroll.ScrollEffect` to handle the
+overscroll. These effects can perform actions like bouncing back,
+changing opacity, or simply preventing scrolling beyond the normal
+boundaries. Note that complex effects may perform many computations,
+which can be slow on weaker hardware.
+
+You can change what effect is being used by setting
+:attr:`~ScrollView.effect_cls` to any effect class. Current options
+include:
+
+    - :class:`~kivy.effects.scroll.ScrollEffect`: Does not allow
+      scrolling beyond the :class:`ScrollView` boundaries.
+    - :class:`~kivy.effects.dampedscroll.DampedScrollEffect`: The
+      current default. Allows the user to scroll beyond the normal
+      boundaries, but has the content spring back once the
+      touch/click is released.
+    - :class:`~kivy.effects.opacityscroll.OpacityScrollEffect`: Similar
+      to the :class:`~kivy.effect.dampedscroll.DampedScrollEffect`, but
+      also reduces opacity during overscroll.
+
+You can also create your own scroll effect by subclassing one of these,
+then pass it as the :attr:`~ScrollView.effect_cls` in the same way.
+
+Alternatively, you can set :attr:`~ScrollView.effect_x` and/or
+:attr:`~ScrollView.effect_y` to an *instance* of the effect you want to
+use. This will override the default effect set in
+:attr:`~ScrollView.effect_cls`.
+
+All the effects are located in the :mod:`kivy.effects`.
+
+'''
+
+__all__ = ('ScrollView', )
+
+from functools import partial
+from kivy.animation import Animation
+from kivy.compat import string_types
+from kivy.config import Config
+from kivy.clock import Clock
+from kivy.factory import Factory
+from kivy.uix.stencilview import StencilView
+from kivy.metrics import dp
+from kivy.effects.dampedscroll import DampedScrollEffect
+from kivy.properties import NumericProperty, BooleanProperty, AliasProperty, \
+    ObjectProperty, ListProperty, ReferenceListProperty, OptionProperty, \
+    ColorProperty
+from kivy.uix.behaviors import FocusBehavior
+
+
+# When we are generating documentation, Config doesn't exist
+_scroll_timeout = _scroll_distance = 0
+if Config:
+    _scroll_timeout = Config.getint('widgets', 'scroll_timeout')
+    _scroll_distance = '{}sp'.format(Config.getint('widgets',
+                                                   'scroll_distance'))
+
+
+class ScrollView(StencilView):
+    '''ScrollView class. See module documentation for more information.
+
+    :Events:
+        `on_scroll_start`
+            Generic event fired when scrolling starts from touch.
+        `on_scroll_move`
+            Generic event fired when scrolling move from touch.
+        `on_scroll_stop`
+            Generic event fired when scrolling stops from touch.
+
+    .. versionchanged:: 1.9.0
+        `on_scroll_start`, `on_scroll_move` and `on_scroll_stop` events are
+        now dispatched when scrolling to handle nested ScrollViews.
+
+    .. versionchanged:: 1.7.0
+        `auto_scroll`, `scroll_friction`, `scroll_moves`, `scroll_stoptime' has
+        been deprecated, use :attr:`effect_cls` instead.
+    '''
+
+    scroll_distance = NumericProperty(_scroll_distance)
+    '''Distance to move before scrolling the :class:`ScrollView`, in pixels. As
+    soon as the distance has been traveled, the :class:`ScrollView` will start
+    to scroll, and no touch event will go to children.
+    It is advisable that you base this value on the dpi of your target device's
+    screen.
+
+    :attr:`scroll_distance` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 20 (pixels), according to the default value in user
+    configuration.
+    '''
+
+    scroll_wheel_distance = NumericProperty('20sp')
+    '''Distance to move when scrolling with a mouse wheel.
+    It is advisable that you base this value on the dpi of your target device's
+    screen.
+
+    .. versionadded:: 1.8.0
+
+    :attr:`scroll_wheel_distance` is a
+    :class:`~kivy.properties.NumericProperty` , defaults to 20 pixels.
+    '''
+
+    scroll_timeout = NumericProperty(_scroll_timeout)
+    '''Timeout allowed to trigger the :attr:`scroll_distance`, in milliseconds.
+    If the user has not moved :attr:`scroll_distance` within the timeout,
+    the scrolling will be disabled, and the touch event will go to the
+    children.
+
+    :attr:`scroll_timeout` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 55 (milliseconds) according to the default value in user
+    configuration.
+
+    .. versionchanged:: 1.5.0
+        Default value changed from 250 to 55.
+    '''
+
+    scroll_x = NumericProperty(0.)
+    '''X scrolling value, between 0 and 1. If 0, the content's left side will
+    touch the left side of the ScrollView. If 1, the content's right side will
+    touch the right side.
+
+    This property is controlled by :class:`ScrollView` only if
+    :attr:`do_scroll_x` is True.
+
+    :attr:`scroll_x` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 0.
+    '''
+
+    scroll_y = NumericProperty(1.)
+    '''Y scrolling value, between 0 and 1. If 0, the content's bottom side will
+    touch the bottom side of the ScrollView. If 1, the content's top side will
+    touch the top side.
+
+    This property is controlled by :class:`ScrollView` only if
+    :attr:`do_scroll_y` is True.
+
+    :attr:`scroll_y` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 1.
+    '''
+
+    do_scroll_x = BooleanProperty(True)
+    '''Allow scroll on X axis.
+
+    :attr:`do_scroll_x` is a :class:`~kivy.properties.BooleanProperty` and
+    defaults to True.
+    '''
+
+    do_scroll_y = BooleanProperty(True)
+    '''Allow scroll on Y axis.
+
+    :attr:`do_scroll_y` is a :class:`~kivy.properties.BooleanProperty` and
+    defaults to True.
+    '''
+
+    def _get_do_scroll(self):
+        return (self.do_scroll_x, self.do_scroll_y)
+
+    def _set_do_scroll(self, value):
+        if isinstance(value, (list, tuple)):
+            self.do_scroll_x, self.do_scroll_y = value
+        else:
+            self.do_scroll_x = self.do_scroll_y = bool(value)
+
+    do_scroll = AliasProperty(_get_do_scroll, _set_do_scroll,
+                              bind=('do_scroll_x', 'do_scroll_y'),
+                              cache=True)
+    '''Allow scroll on X or Y axis.
+
+    :attr:`do_scroll` is a :class:`~kivy.properties.AliasProperty` of
+    (:attr:`do_scroll_x` + :attr:`do_scroll_y`)
+    '''
+
+    always_overscroll = BooleanProperty(True)
+    '''Make sure user can overscroll even if there is not enough content
+    to require scrolling.
+
+    This is useful if you want to trigger some action on overscroll, but
+    there is not always enough content to trigger it.
+
+    :attr:`always_overscroll` is a
+    :class:`~kivy.properties.BooleanProperty` and defaults to `True`.
+
+    .. versionadded:: 2.0.0
+
+    The option was added and enabled by default, set to False to get the
+    previous behavior of only allowing to overscroll when there is
+    enough content to allow scrolling.
+    '''
+
+    def _get_vbar(self):
+        # must return (y, height) in %
+        # calculate the viewport size / scrollview size %
+        if self._viewport is None:
+            return 0, 1.
+        vh = self._viewport.height
+        h = self.height
+        if vh < h or vh == 0:
+            return 0, 1.
+        ph = max(0.01, h / float(vh))
+        sy = min(1.0, max(0.0, self.scroll_y))
+        py = (1. - ph) * sy
+        return (py, ph)
+
+    vbar = AliasProperty(_get_vbar,
+                         bind=('scroll_y', '_viewport', 'viewport_size',
+                               'height'),
+                         cache=True)
+    '''Return a tuple of (position, size) of the vertical scrolling bar.
+
+    .. versionadded:: 1.2.0
+
+    The position and size are normalized between 0-1, and represent a
+    proportion of the current scrollview height. This property is used
+    internally for drawing the little vertical bar when you're scrolling.
+
+    :attr:`vbar` is a :class:`~kivy.properties.AliasProperty`, readonly.
+    '''
+
+    def _get_hbar(self):
+        # must return (x, width) in %
+        # calculate the viewport size / scrollview size %
+        if self._viewport is None:
+            return 0, 1.
+        vw = self._viewport.width
+        w = self.width
+        if vw < w or vw == 0:
+            return 0, 1.
+        pw = max(0.01, w / float(vw))
+        sx = min(1.0, max(0.0, self.scroll_x))
+        px = (1. - pw) * sx
+        return (px, pw)
+
+    hbar = AliasProperty(_get_hbar,
+                         bind=('scroll_x', '_viewport', 'viewport_size',
+                               'width'),
+                         cache=True)
+    '''Return a tuple of (position, size) of the horizontal scrolling bar.
+
+    .. versionadded:: 1.2.0
+
+    The position and size are normalized between 0-1, and represent a
+    proportion of the current scrollview height. This property is used
+    internally for drawing the little horizontal bar when you're scrolling.
+
+    :attr:`hbar` is a :class:`~kivy.properties.AliasProperty`, readonly.
+    '''
+
+    bar_color = ColorProperty([.7, .7, .7, .9])
+    '''Color of horizontal / vertical scroll bar, in RGBA format.
+
+    .. versionadded:: 1.2.0
+
+    :attr:`bar_color` is a :class:`~kivy.properties.ColorProperty` and defaults
+    to [.7, .7, .7, .9].
+
+    .. versionchanged:: 2.0.0
+        Changed from :class:`~kivy.properties.ListProperty` to
+        :class:`~kivy.properties.ColorProperty`.
+    '''
+
+    bar_inactive_color = ColorProperty([.7, .7, .7, .2])
+    '''Color of horizontal / vertical scroll bar (in RGBA format), when no
+    scroll is happening.
+
+    .. versionadded:: 1.9.0
+
+    :attr:`bar_inactive_color` is a
+    :class:`~kivy.properties.ColorProperty` and defaults to [.7, .7, .7, .2].
+
+    .. versionchanged:: 2.0.0
+        Changed from :class:`~kivy.properties.ListProperty` to
+        :class:`~kivy.properties.ColorProperty`.
+    '''
+
+    bar_width = NumericProperty('2dp')
+    '''Width of the horizontal / vertical scroll bar. The width is interpreted
+    as a height for the horizontal bar.
+
+    .. versionadded:: 1.2.0
+
+    :attr:`bar_width` is a :class:`~kivy.properties.NumericProperty` and
+    defaults to 2.
+    '''
+
+    bar_pos_x = OptionProperty('bottom', options=('top', 'bottom'))
+    '''Which side of the ScrollView the horizontal scroll bar should go
+    on. Possible values are 'top' and 'bottom'.
+
+    .. versionadded:: 1.8.0
+
+    :attr:`bar_pos_x` is an :class:`~kivy.properties.OptionProperty`,
+    defaults to 'bottom'.
+
+    '''
+
+    bar_pos_y = OptionProperty('right', options=('left', 'right'))
+    '''Which side of the ScrollView the vertical scroll bar should go
+    on. Possible values are 'left' and 'right'.
+
+    .. versionadded:: 1.8.0
+
+    :attr:`bar_pos_y` is an :class:`~kivy.properties.OptionProperty` and
+    defaults to 'right'.
+
+    '''
+
+    bar_pos = ReferenceListProperty(bar_pos_x, bar_pos_y)
+    '''Which side of the scroll view to place each of the bars on.
+
+    :attr:`bar_pos` is a :class:`~kivy.properties.ReferenceListProperty` of
+    (:attr:`bar_pos_x`, :attr:`bar_pos_y`)
+    '''
+
+    bar_margin = NumericProperty(0)
+    '''Margin between the bottom / right side of the scrollview when drawing
+    the horizontal / vertical scroll bar.
+
+    .. versionadded:: 1.2.0
+
+    :attr:`bar_margin` is a :class:`~kivy.properties.NumericProperty`, default
+    to 0
+    '''
+
+    effect_cls = ObjectProperty(DampedScrollEffect, allownone=True)
+    '''Class effect to instantiate for X and Y axis.
+
+    .. versionadded:: 1.7.0
+
+    :attr:`effect_cls` is an :class:`~kivy.properties.ObjectProperty` and
+    defaults to :class:`DampedScrollEffect`.
+
+    .. versionchanged:: 1.8.0
+        If you set a string, the :class:`~kivy.factory.Factory` will be used to
+        resolve the class.
+
+    '''
+
+    effect_x = ObjectProperty(None, allownone=True)
+    '''Effect to apply for the X axis. If None is set, an instance of
+    :attr:`effect_cls` will be created.
+
+    .. versionadded:: 1.7.0
+
+    :attr:`effect_x` is an :class:`~kivy.properties.ObjectProperty` and
+    defaults to None.
+    '''
+
+    effect_y = ObjectProperty(None, allownone=True)
+    '''Effect to apply for the Y axis. If None is set, an instance of
+    :attr:`effect_cls` will be created.
+
+    .. versionadded:: 1.7.0
+
+    :attr:`effect_y` is an :class:`~kivy.properties.ObjectProperty` and
+    defaults to None, read-only.
+    '''
+
+    viewport_size = ListProperty([0, 0])
+    '''(internal) Size of the internal viewport. This is the size of your only
+    child in the scrollview.
+    '''
+
+    scroll_type = OptionProperty(['content'], options=(['content'], ['bars'],
+                                 ['bars', 'content'], ['content', 'bars']))
+    '''Sets the type of scrolling to use for the content of the scrollview.
+    Available options are: ['content'], ['bars'], ['bars', 'content'].
+
+    +---------------------+------------------------------------------------+
+    | ['content']         | Content is scrolled by dragging or swiping the |
+    |                     | content directly.                              |
+    +---------------------+------------------------------------------------+
+    | ['bars']            | Content is scrolled by dragging or swiping the |
+    |                     | scroll bars.                                   |
+    +---------------------+------------------------------------------------+
+    | ['bars', 'content'] | Content is scrolled by either of the above     |
+    |                     | methods.                                       |
+    +---------------------+------------------------------------------------+
+
+    .. versionadded:: 1.8.0
+
+    :attr:`scroll_type` is an :class:`~kivy.properties.OptionProperty` and
+    defaults to ['content'].
+    '''
+
+    smooth_scroll_end = NumericProperty(None, allownone=True)
+    '''Whether smooth scroll end should be used when scrolling with the
+    mouse-wheel and the factor of transforming the scroll distance to
+    velocity. This option also enables velocity addition meaning if you
+    scroll more, you will scroll faster and further. The recommended value
+    is `10`. The velocity is calculated as :attr:`scroll_wheel_distance` *
+    :attr:`smooth_scroll_end`.
+
+    .. versionadded:: 1.11.0
+
+    :attr:`smooth_scroll_end` is a :class:`~kivy.properties.NumericProperty`
+    and defaults to None.
+    '''
+
+    # private, for internal use only
+
+    _viewport = ObjectProperty(None, allownone=True)
+    _bar_color = ListProperty([0, 0, 0, 0])
+    _effect_x_start_width = None
+    _effect_y_start_height = None
+    _update_effect_bounds_ev = None
+    _bind_inactive_bar_color_ev = None
+
+    def _set_viewport_size(self, instance, value):
+        self.viewport_size = value
+
+    def on__viewport(self, instance, value):
+        if value:
+            value.bind(size=self._set_viewport_size)
+            self.viewport_size = value.size
+
+    __events__ = ('on_scroll_start', 'on_scroll_move', 'on_scroll_stop')
+
+    def __init__(self, **kwargs):
+        self._touch = None
+        self._trigger_update_from_scroll = Clock.create_trigger(
+            self.update_from_scroll, -1)
+        # create a specific canvas for the viewport
+        from kivy.graphics import PushMatrix, Translate, PopMatrix, Canvas
+        self.canvas_viewport = Canvas()
+        self.canvas = Canvas()
+        with self.canvas_viewport.before:
+            PushMatrix()
+            self.g_translate = Translate(0, 0)
+        with self.canvas_viewport.after:
+            PopMatrix()
+
+        super(ScrollView, self).__init__(**kwargs)
+
+        self.register_event_type('on_scroll_start')
+        self.register_event_type('on_scroll_move')
+        self.register_event_type('on_scroll_stop')
+
+        # now add the viewport canvas to our canvas
+        self.canvas.add(self.canvas_viewport)
+
+        effect_cls = self.effect_cls
+        if isinstance(effect_cls, string_types):
+            effect_cls = Factory.get(effect_cls)
+        if self.effect_x is None and effect_cls is not None:
+            self.effect_x = effect_cls(target_widget=self._viewport)
+        if self.effect_y is None and effect_cls is not None:
+            self.effect_y = effect_cls(target_widget=self._viewport)
+
+        trigger_update_from_scroll = self._trigger_update_from_scroll
+        update_effect_widget = self._update_effect_widget
+        update_effect_x_bounds = self._update_effect_x_bounds
+        update_effect_y_bounds = self._update_effect_y_bounds
+        fbind = self.fbind
+        fbind('width', update_effect_x_bounds)
+        fbind('height', update_effect_y_bounds)
+        fbind('viewport_size', self._update_effect_bounds)
+        fbind('_viewport', update_effect_widget)
+        fbind('scroll_x', trigger_update_from_scroll)
+        fbind('scroll_y', trigger_update_from_scroll)
+        fbind('pos', trigger_update_from_scroll)
+        fbind('size', trigger_update_from_scroll)
+
+        trigger_update_from_scroll()
+        update_effect_widget()
+        update_effect_x_bounds()
+        update_effect_y_bounds()
+
+    def on_effect_x(self, instance, value):
+        if value:
+            value.bind(scroll=self._update_effect_x)
+            value.target_widget = self._viewport
+
+    def on_effect_y(self, instance, value):
+        if value:
+            value.bind(scroll=self._update_effect_y)
+            value.target_widget = self._viewport
+
+    def on_effect_cls(self, instance, cls):
+        if isinstance(cls, string_types):
+            cls = Factory.get(cls)
+        self.effect_x = cls(target_widget=self._viewport)
+        self.effect_x.bind(scroll=self._update_effect_x)
+        self.effect_y = cls(target_widget=self._viewport)
+        self.effect_y.bind(scroll=self._update_effect_y)
+
+    def _update_effect_widget(self, *args):
+        if self.effect_x:
+            self.effect_x.target_widget = self._viewport
+        if self.effect_y:
+            self.effect_y.target_widget = self._viewport
+
+    def _update_effect_x_bounds(self, *args):
+        if not self._viewport or not self.effect_x:
+            return
+        scrollable_width = self.width - self.viewport_size[0]
+        self.effect_x.min = 0
+        self.effect_x.max = min(0, scrollable_width)
+        self.effect_x.value = scrollable_width * self.scroll_x
+
+    def _update_effect_y_bounds(self, *args):
+        if not self._viewport or not self.effect_y:
+            return
+        scrollable_height = self.height - self.viewport_size[1]
+        self.effect_y.min = 0 if scrollable_height < 0 else scrollable_height
+        self.effect_y.max = scrollable_height
+        self.effect_y.value = self.effect_y.max * self.scroll_y
+
+    def _update_effect_bounds(self, *args):
+        self._update_effect_x_bounds()
+        self._update_effect_y_bounds()
+
+    def _update_effect_x(self, *args):
+        vp = self._viewport
+        if not vp or not self.effect_x:
+            return
+
+        if self.effect_x.is_manual:
+            sw = vp.width - self._effect_x_start_width
+        else:
+            sw = vp.width - self.width
+        if sw < 1 and not (self.always_overscroll and self.do_scroll_x):
+            return
+        if sw != 0:
+            sx = self.effect_x.scroll / sw
+            self.scroll_x = -sx
+        self._trigger_update_from_scroll()
+
+    def _update_effect_y(self, *args):
+        vp = self._viewport
+        if not vp or not self.effect_y:
+            return
+        if self.effect_y.is_manual:
+            sh = vp.height - self._effect_y_start_height
+        else:
+            sh = vp.height - self.height
+
+        if sh < 1 and not (self.always_overscroll and self.do_scroll_y):
+            return
+        if sh != 0:
+            sy = self.effect_y.scroll / sh
+            self.scroll_y = -sy
+        self._trigger_update_from_scroll()
+
+    def to_local(self, x, y, **k):
+        tx, ty = self.g_translate.xy
+        return x - tx, y - ty
+
+    def to_parent(self, x, y, **k):
+        tx, ty = self.g_translate.xy
+        return x + tx, y + ty
+
+    def _apply_transform(self, m, pos=None):
+        tx, ty = self.g_translate.xy
+        m.translate(tx, ty, 0)
+        return super(ScrollView, self)._apply_transform(m, (0, 0))
+
+    def simulate_touch_down(self, touch):
+        # at this point the touch is in parent coords
+        touch.push()
+        touch.apply_transform_2d(self.to_local)
+        ret = super(ScrollView, self).on_touch_down(touch)
+        touch.pop()
+        return ret
+
+    def on_motion(self, etype, me):
+        if me.type_id in self.motion_filter and 'pos' in me.profile:
+            me.push()
+            me.apply_transform_2d(self.to_local)
+            ret = super().on_motion(etype, me)
+            me.pop()
+            return ret
+        return super().on_motion(etype, me)
+
+    def on_touch_down(self, touch):
+        if self.dispatch('on_scroll_start', touch):
+            self._touch = touch
+            touch.grab(self)
+            return True
+
+    def _touch_in_handle(self, pos, size, touch):
+        x, y = pos
+        width, height = size
+        return x <= touch.x <= x + width and y <= touch.y <= y + height
+
+    def on_scroll_start(self, touch, check_children=True):
+        if check_children:
+            touch.push()
+            touch.apply_transform_2d(self.to_local)
+            if self.dispatch_children('on_scroll_start', touch):
+                touch.pop()
+                return True
+            touch.pop()
+
+        if not self.collide_point(*touch.pos):
+            touch.ud[self._get_uid('svavoid')] = True
+            return
+        if self.disabled:
+            return True
+        if self._touch or (not (self.do_scroll_x or self.do_scroll_y)):
+            return self.simulate_touch_down(touch)
+
+        # handle mouse scrolling, only if the viewport size is bigger than the
+        # scrollview size, and if the user allowed to do it
+        vp = self._viewport
+        if not vp:
+            return True
+        scroll_type = self.scroll_type
+        ud = touch.ud
+        scroll_bar = 'bars' in scroll_type
+
+        # check if touch is in bar_x(horizontal) or bar_y(vertical)
+        # width_enable_overscroll or vp.width > self.width
+        width_scrollable = (
+            (self.always_overscroll and self.do_scroll_x)
+            or vp.width > self.width
+        )
+        height_scrollable = (
+            (self.always_overscroll and self.do_scroll_y)
+            or vp.height > self.height
+        )
+
+        d = {'bottom': touch.y - self.y - self.bar_margin,
+             'top': self.top - touch.y - self.bar_margin,
+             'left': touch.x - self.x - self.bar_margin,
+             'right': self.right - touch.x - self.bar_margin}
+
+        ud['in_bar_x'] = (scroll_bar and width_scrollable and
+                          (0 <= d[self.bar_pos_x] <= self.bar_width))
+        ud['in_bar_y'] = (scroll_bar and height_scrollable and
+                          (0 <= d[self.bar_pos_y] <= self.bar_width))
+
+        if 'button' in touch.profile and touch.button.startswith('scroll'):
+            btn = touch.button
+            m = self.scroll_wheel_distance
+            e = None
+
+            if (
+                (btn == 'scrolldown' and self.scroll_y >= 1)
+                or (btn == 'scrollup' and self.scroll_y <= 0)
+                or (btn == 'scrollleft' and self.scroll_x >= 1)
+                or (btn == 'scrollright' and self.scroll_x <= 0)
+            ):
+                return False
+
+            if (
+                self.effect_x
+                and self.do_scroll_y
+                and height_scrollable
+                and btn in ('scrolldown', 'scrollup')
+            ):
+                e = self.effect_x if ud['in_bar_x'] else self.effect_y
+
+            elif (
+                self.effect_y
+                and self.do_scroll_x
+                and width_scrollable
+                and btn in ('scrollleft', 'scrollright')
+            ):
+                e = self.effect_y if ud['in_bar_y'] else self.effect_x
+
+            if e:
+                # make sure the effect's value is synced to scroll value
+                self._update_effect_bounds()
+                if btn in ('scrolldown', 'scrollleft'):
+                    if self.smooth_scroll_end:
+                        e.velocity -= m * self.smooth_scroll_end
+                    else:
+                        if self.always_overscroll:
+                            e.value = e.value - m
+                        else:
+                            e.value = max(e.value - m, e.max)
+                        e.velocity = 0
+                elif btn in ('scrollup', 'scrollright'):
+                    if self.smooth_scroll_end:
+                        e.velocity += m * self.smooth_scroll_end
+                    else:
+                        if self.always_overscroll:
+                            e.value = e.value + m
+                        else:
+                            e.value = min(e.value + m, e.min)
+                        e.velocity = 0
+                touch.ud[self._get_uid('svavoid')] = True
+                e.trigger_velocity_update()
+            return True
+
+        in_bar = ud['in_bar_x'] or ud['in_bar_y']
+        if scroll_type == ['bars'] and not in_bar:
+            return self.simulate_touch_down(touch)
+
+        if in_bar:
+            if (ud['in_bar_y'] and not
+                    self._touch_in_handle(
+                        self._handle_y_pos, self._handle_y_size, touch)):
+                self.scroll_y = (touch.y - self.y) / self.height
+            elif (ud['in_bar_x'] and not
+                    self._touch_in_handle(
+                        self._handle_x_pos, self._handle_x_size, touch)):
+                self.scroll_x = (touch.x - self.x) / self.width
+
+        # no mouse scrolling, so the user is going to drag the scrollview with
+        # this touch.
+        self._touch = touch
+        uid = self._get_uid()
+
+        ud[uid] = {
+            'mode': 'unknown',
+            'dx': 0,
+            'dy': 0,
+            'user_stopped': in_bar,
+            'frames': Clock.frames,
+            'time': touch.time_start,
+        }
+
+        if (self.do_scroll_x and self.effect_x and not ud['in_bar_x']
+                and not ud['in_bar_y']):
+            # make sure the effect's value is synced to scroll value
+            self._update_effect_bounds()
+
+            self._effect_x_start_width = self.width
+            self.effect_x.start(touch.x)
+            self._scroll_x_mouse = self.scroll_x
+
+        if (self.do_scroll_y and self.effect_y and not ud['in_bar_x']
+                and not ud['in_bar_y']):
+            # make sure the effect's value is synced to scroll value
+            self._update_effect_bounds()
+
+            self._effect_y_start_height = self.height
+            self.effect_y.start(touch.y)
+            self._scroll_y_mouse = self.scroll_y
+
+        if not in_bar:
+            Clock.schedule_once(self._change_touch_mode,
+                                self.scroll_timeout / 1000.)
+        return True
+
+    def on_touch_move(self, touch):
+        if self._touch is not touch:
+            # don't pass on touch to children if outside the sv
+            if self.collide_point(*touch.pos):
+                # touch is in parent
+                touch.push()
+                touch.apply_transform_2d(self.to_local)
+                super(ScrollView, self).on_touch_move(touch)
+                touch.pop()
+            return self._get_uid() in touch.ud
+        if touch.grab_current is not self:
+            return True
+
+        if not any(isinstance(key, str) and key.startswith('sv.')
+                   for key in touch.ud):
+            # don't pass on touch to children if outside the sv
+            if self.collide_point(*touch.pos):
+                # touch is in window coordinates
+                touch.push()
+                touch.apply_transform_2d(self.to_local)
+                res = super(ScrollView, self).on_touch_move(touch)
+                touch.pop()
+                return res
+            return False
+
+        touch.ud['sv.handled'] = {'x': False, 'y': False}
+        if self.dispatch('on_scroll_move', touch):
+            return True
+
+    def on_scroll_move(self, touch):
+        if self._get_uid('svavoid') in touch.ud:
+            return False
+
+        touch.push()
+        touch.apply_transform_2d(self.to_local)
+        if self.dispatch_children('on_scroll_move', touch):
+            touch.pop()
+            return True
+        touch.pop()
+
+        rv = True
+
+        # By default this touch can be used to defocus currently focused
+        # widget, like any touch outside of ScrollView.
+        touch.ud['sv.can_defocus'] = True
+
+        uid = self._get_uid()
+        if uid not in touch.ud:
+            self._touch = False
+            return self.on_scroll_start(touch, False)
+        ud = touch.ud[uid]
+
+        # check if the minimum distance has been travelled
+        if ud['mode'] == 'unknown':
+            if not (self.do_scroll_x or self.do_scroll_y):
+                # touch is in parent, but _change expects window coords
+                touch.push()
+                touch.apply_transform_2d(self.to_local)
+                touch.apply_transform_2d(self.to_window)
+                self._change_touch_mode()
+                touch.pop()
+                return
+            ud['dx'] += abs(touch.dx)
+            ud['dy'] += abs(touch.dy)
+            if ((ud['dx'] > self.scroll_distance and self.do_scroll_x) or
+                    (ud['dy'] > self.scroll_distance and self.do_scroll_y)):
+                ud['mode'] = 'scroll'
+
+        if ud['mode'] == 'scroll':
+            not_in_bar = not touch.ud.get('in_bar_x', False) and \
+                not touch.ud.get('in_bar_y', False)
+
+            if not touch.ud['sv.handled']['x'] and self.do_scroll_x \
+                    and self.effect_x:
+                width = self.width
+                if touch.ud.get('in_bar_x', False):
+                    if self.hbar[1] != 1:
+                        dx = touch.dx / float(width - width * self.hbar[1])
+                        self.scroll_x = min(max(self.scroll_x + dx, 0.), 1.)
+                        self._trigger_update_from_scroll()
+                elif not_in_bar:
+                    self.effect_x.update(touch.x)
+
+                if self.scroll_x < 0 or self.scroll_x > 1:
+                    rv = False
+                else:
+                    touch.ud['sv.handled']['x'] = True
+                # Touch resulted in scroll should not defocus focused widget
+                touch.ud['sv.can_defocus'] = False
+            if not touch.ud['sv.handled']['y'] and self.do_scroll_y \
+                    and self.effect_y:
+                height = self.height
+                if touch.ud.get('in_bar_y', False) and self.vbar[1] != 1.0:
+                    dy = touch.dy / float(height - height * self.vbar[1])
+                    self.scroll_y = min(max(self.scroll_y + dy, 0.), 1.)
+                    self._trigger_update_from_scroll()
+                elif not_in_bar:
+                    self.effect_y.update(touch.y)
+
+                if self.scroll_y < 0 or self.scroll_y > 1:
+                    rv = False
+                else:
+                    touch.ud['sv.handled']['y'] = True
+                # Touch resulted in scroll should not defocus focused widget
+                touch.ud['sv.can_defocus'] = False
+            ud['dt'] = touch.time_update - ud['time']
+            ud['time'] = touch.time_update
+            ud['user_stopped'] = True
+        return rv
+
+    def on_touch_up(self, touch):
+        uid = self._get_uid('svavoid')
+        if self._touch is not touch and uid not in touch.ud:
+            # don't pass on touch to children if outside the sv
+            if self.collide_point(*touch.pos):
+                # touch is in parents
+                touch.push()
+                touch.apply_transform_2d(self.to_local)
+                if super(ScrollView, self).on_touch_up(touch):
+                    touch.pop()
+                    return True
+                touch.pop()
+            return False
+
+        if self.dispatch('on_scroll_stop', touch):
+            touch.ungrab(self)
+            if not touch.ud.get('sv.can_defocus', True):
+                # Focused widget should stay focused
+                FocusBehavior.ignored_touch.append(touch)
+            return True
+
+    def on_scroll_stop(self, touch, check_children=True):
+        self._touch = None
+
+        if check_children:
+            touch.push()
+            touch.apply_transform_2d(self.to_local)
+            if self.dispatch_children('on_scroll_stop', touch):
+                touch.pop()
+                return True
+            touch.pop()
+
+        if self._get_uid('svavoid') in touch.ud:
+            return
+        if self._get_uid() not in touch.ud:
+            return False
+
+        self._touch = None
+        uid = self._get_uid()
+        ud = touch.ud[uid]
+        not_in_bar = not touch.ud.get('in_bar_x', False) and \
+            not touch.ud.get('in_bar_y', False)
+        if self.do_scroll_x and self.effect_x and not_in_bar:
+            self.effect_x.stop(touch.x)
+        if self.do_scroll_y and self.effect_y and not_in_bar:
+            self.effect_y.stop(touch.y)
+        if ud['mode'] == 'unknown':
+            # we must do the click at least..
+            # only send the click if it was not a click to stop
+            # autoscrolling
+            if not ud['user_stopped']:
+                self.simulate_touch_down(touch)
+            Clock.schedule_once(partial(self._do_touch_up, touch), .2)
+
+        ev = self._update_effect_bounds_ev
+        if ev is None:
+            ev = self._update_effect_bounds_ev = Clock.create_trigger(
+                self._update_effect_bounds)
+        ev()
+
+        # if we do mouse scrolling, always accept it
+        if 'button' in touch.profile and touch.button.startswith('scroll'):
+            return True
+
+        return self._get_uid() in touch.ud
+
+    def scroll_to(self, widget, padding=10, animate=True):
+        '''Scrolls the viewport to ensure that the given widget is visible,
+        optionally with padding and animation. If animate is True (the
+        default), then the default animation parameters will be used.
+        Otherwise, it should be a dict containing arguments to pass to
+        :class:`~kivy.animation.Animation` constructor.
+
+        .. versionadded:: 1.9.1
+        '''
+        if not self.parent:
+            return
+
+        # if _viewport is layout and has pending operation, reschedule
+        if hasattr(self._viewport, 'do_layout'):
+            if self._viewport._trigger_layout.is_triggered:
+                Clock.schedule_once(
+                     lambda *dt: self.scroll_to(widget, padding, animate))
+                return
+
+        if isinstance(padding, (int, float)):
+            padding = (padding, padding)
+
+        pos = self.parent.to_widget(*widget.to_window(*widget.pos))
+        cor = self.parent.to_widget(*widget.to_window(widget.right,
+                                                      widget.top))
+
+        dx = dy = 0
+
+        if pos[1] < self.y:
+            dy = self.y - pos[1] + dp(padding[1])
+        elif cor[1] > self.top:
+            dy = self.top - cor[1] - dp(padding[1])
+
+        if pos[0] < self.x:
+            dx = self.x - pos[0] + dp(padding[0])
+        elif cor[0] > self.right:
+            dx = self.right - cor[0] - dp(padding[0])
+
+        dsx, dsy = self.convert_distance_to_scroll(dx, dy)
+        sxp = min(1, max(0, self.scroll_x - dsx))
+        syp = min(1, max(0, self.scroll_y - dsy))
+
+        if animate:
+            if animate is True:
+                animate = {'d': 0.2, 't': 'out_quad'}
+            Animation.stop_all(self, 'scroll_x', 'scroll_y')
+            Animation(scroll_x=sxp, scroll_y=syp, **animate).start(self)
+        else:
+            self.scroll_x = sxp
+            self.scroll_y = syp
+
+    def convert_distance_to_scroll(self, dx, dy):
+        '''Convert a distance in pixels to a scroll distance, depending on the
+        content size and the scrollview size.
+
+        The result will be a tuple of scroll distance that can be added to
+        :data:`scroll_x` and :data:`scroll_y`
+        '''
+        if not self._viewport:
+            return 0, 0
+        vp = self._viewport
+        if vp.width > self.width:
+            sw = vp.width - self.width
+            sx = dx / float(sw)
+        else:
+            sx = 0
+        if vp.height > self.height:
+            sh = vp.height - self.height
+            sy = dy / float(sh)
+        else:
+            sy = 1
+        return sx, sy
+
+    def update_from_scroll(self, *largs):
+        '''Force the reposition of the content, according to current value of
+        :attr:`scroll_x` and :attr:`scroll_y`.
+
+        This method is automatically called when one of the :attr:`scroll_x`,
+        :attr:`scroll_y`, :attr:`pos` or :attr:`size` properties change, or
+        if the size of the content changes.
+        '''
+        if not self._viewport:
+            self.g_translate.xy = self.pos
+            return
+        vp = self._viewport
+
+        # update from size_hint
+        if vp.size_hint_x is not None:
+            w = vp.size_hint_x * self.width
+            if vp.size_hint_min_x is not None:
+                w = max(w, vp.size_hint_min_x)
+            if vp.size_hint_max_x is not None:
+                w = min(w, vp.size_hint_max_x)
+            vp.width = w
+
+        if vp.size_hint_y is not None:
+            h = vp.size_hint_y * self.height
+            if vp.size_hint_min_y is not None:
+                h = max(h, vp.size_hint_min_y)
+            if vp.size_hint_max_y is not None:
+                h = min(h, vp.size_hint_max_y)
+            vp.height = h
+
+        if vp.width > self.width or self.always_overscroll:
+            sw = vp.width - self.width
+            x = self.x - self.scroll_x * sw
+        else:
+            x = self.x
+
+        if vp.height > self.height or self.always_overscroll:
+            sh = vp.height - self.height
+            y = self.y - self.scroll_y * sh
+        else:
+            y = self.top - vp.height
+
+        # from 1.8.0, we now use a matrix by default, instead of moving the
+        # widget position behind. We set it here, but it will be a no-op most
+        # of the time.
+        vp.pos = 0, 0
+        self.g_translate.xy = x, y
+
+        # New in 1.2.0, show bar when scrolling happens and (changed in 1.9.0)
+        # fade to bar_inactive_color when no scroll is happening.
+        ev = self._bind_inactive_bar_color_ev
+        if ev is None:
+            ev = self._bind_inactive_bar_color_ev = Clock.create_trigger(
+                self._bind_inactive_bar_color, .5)
+        self.funbind('bar_inactive_color', self._change_bar_color)
+        Animation.stop_all(self, '_bar_color')
+        self.fbind('bar_color', self._change_bar_color)
+        self._bar_color = self.bar_color
+        ev()
+
+    def _bind_inactive_bar_color(self, *l):
+        self.funbind('bar_color', self._change_bar_color)
+        self.fbind('bar_inactive_color', self._change_bar_color)
+        Animation(
+            _bar_color=self.bar_inactive_color,
+            d=.5, t='out_quart').start(self)
+
+    def _change_bar_color(self, inst, value):
+        self._bar_color = value
+
+    def add_widget(self, widget, *args, **kwargs):
+        if self._viewport:
+            raise Exception('ScrollView accept only one widget')
+        canvas = self.canvas
+        self.canvas = self.canvas_viewport
+        super(ScrollView, self).add_widget(widget, *args, **kwargs)
+        self.canvas = canvas
+        self._viewport = widget
+        widget.bind(size=self._trigger_update_from_scroll,
+                    size_hint_min=self._trigger_update_from_scroll)
+        self._trigger_update_from_scroll()
+
+    def remove_widget(self, widget, *args, **kwargs):
+        canvas = self.canvas
+        self.canvas = self.canvas_viewport
+        super(ScrollView, self).remove_widget(widget, *args, **kwargs)
+        self.canvas = canvas
+        if widget is self._viewport:
+            self._viewport = None
+
+    def _get_uid(self, prefix='sv'):
+        return '{0}.{1}'.format(prefix, self.uid)
+
+    def _change_touch_mode(self, *largs):
+        if not self._touch:
+            return
+        uid = self._get_uid()
+        touch = self._touch
+        if uid not in touch.ud:
+            self._touch = False
+            return
+        ud = touch.ud[uid]
+        if ud['mode'] != 'unknown' or ud['user_stopped']:
+            return
+        diff_frames = Clock.frames - ud['frames']
+
+        # in order to be able to scroll on very slow devices, let at least 3
+        # frames displayed to accumulate some velocity. And then, change the
+        # touch mode. Otherwise, we might never be able to compute velocity,
+        # and no way to scroll it. See #1464 and #1499
+        if diff_frames < 3:
+            Clock.schedule_once(self._change_touch_mode, 0)
+            return
+
+        if self.do_scroll_x and self.effect_x:
+            self.effect_x.cancel()
+        if self.do_scroll_y and self.effect_y:
+            self.effect_y.cancel()
+        # XXX the next line was in the condition. But this stop
+        # the possibility to "drag" an object out of the scrollview in the
+        # non-used direction: if you have an horizontal scrollview, a
+        # vertical gesture will not "stop" the scroll view to look for an
+        # horizontal gesture, until the timeout is done.
+        # and touch.dx + touch.dy == 0:
+        touch.ungrab(self)
+        self._touch = None
+        # touch is in window coords
+        touch.push()
+        touch.apply_transform_2d(self.to_widget)
+        touch.apply_transform_2d(self.to_parent)
+        self.simulate_touch_down(touch)
+        touch.pop()
+        return
+
+    def _do_touch_up(self, touch, *largs):
+        # touch is in window coords
+        touch.push()
+        touch.apply_transform_2d(self.to_widget)
+        super(ScrollView, self).on_touch_up(touch)
+        touch.pop()
+        # don't forget about grab event!
+        for x in touch.grab_list[:]:
+            touch.grab_list.remove(x)
+            x = x()
+            if not x:
+                continue
+            touch.grab_current = x
+            # touch is in window coords
+            touch.push()
+            touch.apply_transform_2d(self.to_widget)
+            super(ScrollView, self).on_touch_up(touch)
+            touch.pop()
+        touch.grab_current = None
+
+
+if __name__ == '__main__':
+    from kivy.app import App
+
+    from kivy.uix.gridlayout import GridLayout
+    from kivy.uix.button import Button
+
+    class ScrollViewApp(App):
+
+        def build(self):
+            layout1 = GridLayout(cols=4, spacing=10, size_hint=(None, None))
+            layout1.bind(minimum_height=layout1.setter('height'),
+                         minimum_width=layout1.setter('width'))
+            for i in range(40):
+                btn = Button(text=str(i), size_hint=(None, None),
+                             size=(200, 100))
+                layout1.add_widget(btn)
+            scrollview1 = ScrollView(bar_width='2dp', smooth_scroll_end=10)
+            scrollview1.add_widget(layout1)
+
+            layout2 = GridLayout(cols=4, spacing=10, size_hint=(None, None))
+            layout2.bind(minimum_height=layout2.setter('height'),
+                         minimum_width=layout2.setter('width'))
+            for i in range(40):
+                btn = Button(text=str(i), size_hint=(None, None),
+                             size=(200, 100))
+                layout2.add_widget(btn)
+            scrollview2 = ScrollView(scroll_type=['bars'],
+                                     bar_width='9dp',
+                                     scroll_wheel_distance=100)
+            scrollview2.add_widget(layout2)
+
+            root = GridLayout(cols=2)
+            root.add_widget(scrollview1)
+            root.add_widget(scrollview2)
+            return root
+
+    ScrollViewApp().run()