Table Of Contents
Scroll View¶
New in version 1.0.4.
The ScrollView widget provides a scrollable/pannable viewport that is clipped at the scrollview’s bounding box.
Scrolling Behavior¶
The ScrollView accepts only one child and applies 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 in some other manner - you cannot do both at the same time. To determine if interaction is a scrolling gesture, these properties are used:
- ScrollView.scroll_distance: the minimum distance to travel,
defaults to 20 pixels.
- ScrollView.scroll_timeout: the maximum time period, defaults
to 250 milliseconds.
If a touch travels scroll_distance pixels within the 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
New in version 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 in both the X and Y axes. You can explicitly disable scrolling on an axis by setting ScrollView.do_scroll_x or ScrollView.do_scroll_y to False.
Managing the Content Size and Position¶
ScrollView manages the position of its children similarly to a RelativeLayout (see relativelayout) but not the size. You must carefully specify the size_hint of your content 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 instructions (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)
Effects¶
New in version 1.7.0.
An effect is a subclass of ScrollEffect that will compute informations during the dragging, and apply transformation to the ScrollView. Depending of the effect, more computing can be done for calculating over-scroll, bouncing, etc.
All the effects are located in the kivy.effects.
- class kivy.uix.scrollview.ScrollView(**kwargs)[source]¶
Bases: kivy.uix.stencilview.StencilView
ScrollView class. See module documentation for more information.
Changed in version 1.7.0: auto_scroll, scroll_friction, scroll_moves, scroll_stoptime’ has been deprecated, use :attr:`effect_cls instead.
- bar_color¶
Color of horizontal / vertical scroll bar, in RGBA format.
New in version 1.2.0.
bar_color is a ListProperty and defaults 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_pos¶
Which side of the scroll view to place each of the bars on.
bar_pos is a ReferenceListProperty of (bar_pos_x, bar_pos_y)
- bar_pos_x¶
Which side of the ScrollView the horizontal scroll bar should go on. Possible values are ‘top’ and ‘bottom’.
New in version 1.8.0.
bar_pos_x is an OptionProperty, default to ‘bottom’
- bar_pos_y¶
Which side of the ScrollView the vertical scroll bar should go on. Possible values are ‘left’ and ‘right’.
New in version 1.8.0.
bar_pos_y is an OptionProperty, default to ‘right’
- bar_width¶
Width of the horizontal / vertical scroll bar. The width is interpreted as a height for the horizontal bar.
New in version 1.2.0.
bar_width is a NumericProperty and defaults to 2.
- 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 and defaults to True.
- do_scroll_y¶
Allow scroll on Y axis.
do_scroll_y is a BooleanProperty and defaults to True.
- effect_cls¶
Class effect to instanciate for X and Y axis.
New in version 1.7.0.
effect_cls is an ObjectProperty and defaults to DampedScrollEffect.
Changed in version 1.8.0: If you set a string, the Factory will be used to resolve the class.
- effect_x¶
Effect to apply for the X axis. If None is set, an instance of effect_cls will be created.
New in version 1.7.0.
effect_x is an ObjectProperty and defaults to None.
- effect_y¶
Effect to apply for the Y axis. If None is set, an instance of effect_cls will be created.
New in version 1.7.0.
effect_y is an ObjectProperty and defaults to None, read-only.
- 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 has been traveled, the 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.
scroll_distance is a NumericProperty and defaults to 20 (pixels), according to the default value in user configuration.
- scroll_timeout¶
Timeout allowed to trigger the scroll_distance, in milliseconds. If the user has not moved scroll_distance within the timeout, the scrolling will be disabled, and the touch event will go to the children.
scroll_timeout is a NumericProperty and defaults to 55 (milliseconds) according to the default value in user configuration.
Changed in version 1.5.0: Default value changed from 250 to 55.
- scroll_type¶
Sets the type of scrolling to use for the content of the scrollview. Available options are: [‘content’], [‘bars’], [‘bars’, ‘content’].
New in version 1.8.0.
scroll_type is a OptionProperty, defaults to [‘content’].
- scroll_wheel_distance¶
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.
New in version 1.8.0.
scroll_wheel_distance is a NumericProperty , defaults to 20 pixels.
- 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 and defaults 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 and defaults to 1.
- update_from_scroll(*largs)[source]¶
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.
- viewport_size¶
(internal) Size of the internal viewport. This is the size of your only child in the scrollview.