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)

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.

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.