Scroll View¶
New in version 1.0.4.
The ScrollView widget provides a scrollable/pannable viewport that is clipped at the ScrollViews bounding box.
Scrolling behavior¶
The ScrollView accepts only one child, and controls a viewport/window to it according to the scroll_x and scroll_y properties. Touches are analyzed to determine if the user wants to scroll or control the child - you cannot do both at the same time. To determine if interaction is a scrolling gesture, these properties are used:
- ScrollView.scroll_distance a minimum distance to travel, default to 20 pixels.
- ScrollView.scroll_timeout a maximum time period, default to 250 milliseconds.
If a touch travels scroll_distance pixels within the scroll_timeout period, it is recognized as a scrolling gesture and translatation (scroll/pan) will begin. If the timeout occurs, the touch down event is dispatched to the child instead (no translation).
New in version 1.1.1.
Limiting to X or Y axis¶
By default, the ScrollView allows scrolling both the X and Y axis. You can explicitly disable scrolling on one of the axis by setting ScrollView.do_scroll_x or ScrollView.do_scroll_y to False.
Managing the content size¶
The ScrollView manages the position of the child content, not the size. You must carefully specify the ScrollView.size_hint property to get the desired scroll/pan effect.
By default, 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 (x or y) of the child to enable scrolling.
To scroll a GridLayout on Y-axis/vertically, set the child’s width identical to that of the ScrollView (size_hint_x=1, default), and set the size_hint_y property to None
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(30):
btn = Button(text=str(i), size_hint_y=None, height=40)
layout.add_widget(btn)
root = ScrollView(size_hint=(None, None), size=(400, 400))
root.add_widget(layout)
Controlling timeout, distance and trigger¶
New in version 1.0.8.
In your configuration file, you can some default values for this widget:
[widgets]
scroll_timeout = 250
scroll_distance = 20
scroll_friction = 1.
If you want to reduce the default timeout, you can set:
[widgets]
scroll_timeout = 150
- class kivy.uix.scrollview.ScrollView(**kwargs)¶
Bases: kivy.uix.stencilview.StencilView
ScrollView class. See module documentation for more information.
- auto_scroll¶
Automatic scrolling is the movement activated after a swipe. When you release a touch, it will start to move the list, according to the lastest touch movement. If you don’t want that behavior, just set the auto_scroll to False.
auto_scroll is a BooleanProperty, default to True
- bar_color¶
Color of horizontal / vertical scroll bar, in RGBA format.
New in version 1.2.0.
bar_color is a ListProperty, default to [.7, .7, .7, .9].
- bar_margin¶
Margin between the bottom / right side of the scrollview when drawing the horizontal / vertical scroll bar.
New in version 1.2.0.
bar_margin is a NumericProperty, default to 0
- bar_width¶
Width of the horizontal / vertical scroll bar. The width is interpreted as an height for the horizontal bar.
New in version 1.2.0.
bar_width is a NumericProperty, default to 2
- convert_distance_to_scroll(dx, dy)¶
Convert a distance in pixel to a scroll distance, depending of the content size and the scrollview size.
The result will be a tuple of scroll distance, that can be added to scroll_x and scroll_y
- do_scroll¶
Allow scroll on X or Y axis
do_scroll is a AliasProperty of (do_scroll_x + do_scroll_y)
- do_scroll_x¶
Allow scroll on X axis
do_scroll_x is a BooleanProperty, default to True.
- do_scroll_y¶
Allow scroll on Y axis
do_scroll_y is a BooleanProperty, default to True.
- hbar¶
Return a tuple of (position, size) of the horizontal scrolling bar.
New in version 1.2.0.
The position and size are normalized between 0-1, and represent a percentage of the current scrollview height. This property is used internally for drawing the little horizontal bar when you’re scrolling.
vbar is a AliasProperty, readonly.
- scroll_distance¶
Distance to move before scrolling the ScrollView, in pixels. As soon as the distance have been traveled, the ScrollView will start to scroll, and no touch event will go to children.
scroll_distance is a NumericProperty, default to 20 (pixels), according to the default value in user configuration.
- scroll_friction¶
Friction is a factor for reducing the scrolling when the list is not moved by a touch. When you do a swipe, the movement speed is calculated, and is used to move automatically the list when you touch up. The speed is reducing from this equation:
2 ^ (t * f) # t is the time from the touch up # f is the friction
By default, the friction factor is 1, it will reduce the speed by a factor or 2 each seconds. If you set the friction to 0, the list speed will never stop. If you set to a bigger value, the list movement will stop faster.
scroll_friction is a NumericProperty, default to 1, according to the default value in user configuration.
- scroll_timeout¶
Timeout allowed to trigger the scroll_distance, in milliseconds. If the timeout is reach, the scrolling will be disabled, and the touch event will go to the children.
scroll_timeout is a NumericProperty, default to 250 (milliseconds), according to the default value in user configuration.
- scroll_x¶
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 controled by ScrollView only if do_scroll_x is True.
scroll_x is a NumericProperty, default to 0.
- scroll_y¶
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 controled by ScrollView only if do_scroll_y is True.
scroll_y is a NumericProperty, default to 1.
- update_from_scroll(*largs)¶
Force the reposition of the content, according to current value of scroll_x and scroll_y.
This method is automatically called when one of the scroll_x, scroll_y, pos or size properties change, or if the size of the content changes.
- vbar¶
Return a tuple of (position, size) of the vertical scrolling bar.
New in version 1.2.0.
The position and size are normalized between 0-1, and represent a percentage of the current scrollview height. This property is used internally for drawing the little vertical bar when you’re scrolling.
vbar is a AliasProperty, readonly.