Kivy - Touch Ripple

In the Kivy framework, the "Touch Ripple" is not really a widget or any concrete class. Instead, the TouchRippleBehavior mixin adds a touch ripple visual effect to a layout or an individual widget. Normally, Kivy has a default press/release visualization. This class adds the ripple effect from Google Material Design.

This mixin class is defined in the "kivy.uix.behaviors.touchripple" module.

from kivy.uix.behaviors.touchripple import TouchRippleBehavior

The Ripple behavior does not trigger automatically. A concrete class needs to implement this behavior mixin and explicitly call ripple_show() respective ripple_fade() methods manually.

To customize the ripple effects, use the following properties −

  • ripple_duration_in − Animation duration taken to show the overlay. It's a NumericProperty and defaults to 0.5.

  • ripple_duration_out − A NumericProperty defaulting to 0.2 sets the animation duration taken to fade the overlay.

  • ripple_fade_from_alpha − Alpha channel for ripple color the animation starts with. Default value is 0.5.

  • ripple_fade_to_alpha − Alpha channel for ripple color the animation targets to, defaults to 0.8.

  • ripple_rad_default − Default radius the animation starts from. It is a NumericProperty and defaults to 10.

  • ripple_scale − Max scale of the animation overlay calculated from max(width/height) of the decorated widget.

  • The ripple_show() method begins ripple animation on current widget. You need to pass a touch event as argument.

  • The ripple_fade() method is called to finish ripple animation on current widget.

  • The ripple_func_in and ripple_funcion_out are animation callbacks for showing and hiding the overlay.

Example

In the following example, we have used kv script that puts a label inside a grid layout, and processes the touch_down and touch_up events.

The on_touch_down() method calls the ripple_show() method to generate ripple effect with a duration of 3 seconds.

The on_touch_up() methods finishes the ripple effect by calling the ripple_fade() method.

from kivy.app import App
from kivy.uix.gridlayout import GridLayout
from kivy.uix.behaviors.touchripple import TouchRippleBehavior
from kivy.core.window import Window

Window.size = (720,300)

class RippleLabel(TouchRippleBehavior, GridLayout):
   def __init__(self, **kwargs):
      super(RippleLabel, self).__init__(**kwargs)

   def on_touch_down(self, touch):
      collide_point = self.collide_point(touch.x, touch.y)
      if collide_point:
         touch.grab(self)
         self.ripple_duration_in=3
         self.ripple_show(touch)
         return True
      return False

   def on_touch_up(self, touch):
      if touch.grab_current is self:
         touch.ungrab(self)
         self.ripple_duration_out=3
         self.ripple_fade()
         return True
      return False

class MyRippleApp(App):
   def build(self):
      return RippleLabel(cols=1)

MyRippleApp().run()

The "kv" script −

<RippleLabel>:
   GridLayout:
      cols:1
      Label:
         size:(root.width, root.height)
         pos_hint:{'center_x':.5, 'center_y':.5}
         
         text:'OK'
         font_size:100
         color:(1,0,0,1)

Output

Run the program and click the "OK" label. It will produce ripple waves on the window surface. Increase the duration to see the effect.

Kivy Touch Ripple
Advertisements