RouletteScrollEffect#

This is a subclass of kivy.effects.ScrollEffect that simulates the motion of a roulette, or a notched wheel (think Wheel of Fortune). It is primarily designed for emulating the effect of the iOS and android date pickers.

Usage#

Here’s an example of using RouletteScrollEffect for a kivy.uix.scrollview.ScrollView:

from kivy.uix.gridlayout import GridLayout
from kivy.uix.button import Button
from kivy.uix.scrollview import ScrollView

# Preparing a `GridLayout` inside a `ScrollView`.
layout = GridLayout(cols=1, padding=10, size_hint=(None, None), width=500)
layout.bind(minimum_height=layout.setter('height'))

for i in range(30):
    btn = Button(text=str(i), size=(480, 40), size_hint=(None, None))
    layout.add_widget(btn)

root = ScrollView(
    size_hint=(None, None),
    size=(500, 320),
    pos_hint={'center_x': .5, 'center_y': .5},
    do_scroll_x=False,
    )
root.add_widget(layout)

# Preparation complete. Now add the new scroll effect.
root.effect_y = RouletteScrollEffect(anchor=20, interval=40)
runTouchApp(root)

Here the ScrollView scrolls through a series of buttons with height 40. We then attached a RouletteScrollEffect with interval 40, corresponding to the button heights. This allows the scrolling to stop at the same offset no matter where it stops. The RouletteScrollEffect.anchor adjusts this offset.

Customizations#

Other settings that can be played with include:

RouletteScrollEffect.pull_duration, RouletteScrollEffect.coasting_alpha, RouletteScrollEffect.pull_back_velocity, and RouletteScrollEffect.terminal_velocity.

See their module documentations for details.

RouletteScrollEffect has one event on_coasted_to_stop that is fired when the roulette stops, “making a selection”. It can be listened to for handling or cleaning up choice making.

API - `kivymd.effects.roulettescroll.roulettescroll`#

class kivymd.effects.roulettescroll.roulettescroll.RouletteScrollEffect(**kwargs)#

New in version 0.104.2.

drag_threshold#

Overrides ScrollEffect.drag_threshold to abolish drag threshold.

Note

If using this with a Roulette or other Tickline subclasses, what matters is Tickline.drag_threshold, which is passed to this attribute in the end.

drag_threshold is an NumericProperty and defaults to 0.

min#

max#

interval#

The interval of the values of the “roulette”.

interval is an NumericProperty and defaults to 50.

anchor#

One of the valid stopping values.

anchor is an NumericProperty and defaults to 0.

pull_duration#

When movement slows around a stopping value, an animation is used to pull it toward the nearest value. pull_duration is the duration used for such an animation.

pull_duration is an NumericProperty and defaults to 0.2.

coasting_alpha#

When within coasting_alpha * interval of the next notch and velocity is below terminal_velocity, coasting begins and will end on the next notch.

coasting_alpha is an NumericProperty and defaults to 0.5.

pull_back_velocity#

The velocity below which the scroll value will be drawn to the nearest notch instead of the next notch in the direction travelled.

pull_back_velocity is an NumericProperty and defaults to 50sp.

terminal_velocity#

If velocity falls between pull_back_velocity and terminal velocity then the movement will start to coast to the next coming stopping value.

terminal_velocity is computed from a set formula given interval, coasting_alpha, pull_duration, and friction. Setting terminal_velocity has the effect of setting pull_duration.

get_term_vel(self)#

set_term_vel(self, val)#

start(self, val, t=None)#

Start the movement.

Parameters:

val: float or int: Value of the movement
t: float, defaults to None: Time when the movement happen. If no time is set, it will use time.time()

on_notch(self, *args)#

nearest_notch(self, *args)#

next_notch(self, *args)#

near_notch(self, d=0.01)#

near_next_notch(self, d=None)#

update_velocity(self, dt)#: (internal) Update the velocity according to the frametime and friction.

on_coasted_to_stop(self, *args)#: This event fires when the roulette has stopped, making a selection.

RouletteScrollEffect#

Usage#

Customizations#

API - kivymd.effects.roulettescroll.roulettescroll#

API - `kivymd.effects.roulettescroll.roulettescroll`#