A Gestures api in place of (and depending on) the Kivy touch api
For a desktop OS:
pip3 install git+https://github.com/Android-for-Python/gestures4kivy.git
For Android add this to buildozer.spec requirements:
git+https://github.com/Android-for-Python/gestures4kivy.git
This is required at the top of the app's main.py to disable a Kivy feature:
# Dispose of that nasty red dot.
Config.set('input', 'mouse', 'mouse, disable_multitouch')
Import with:
from gestures4kivy import CommonGestures
The class CommonGestures detects the common gestures for scale, move, swipe, long press move, long press, tap, and double tap. A long press move is initiated with a long press. On the desktop the class also detects mouse wheel and the touchpad equivalent two finger move.
Designed for use on Android, the gestures can be used on any Kivy supported platform and input device. To be clear these are Android style gestures that are available across platforms and input devices.
In addition, for platforms with a mouse scroll wheel the usual conventions are detected: scroll wheel can be used for vertical scroll, shift-scroll wheel can be used for horizontal scroll, and ctrl-scroll wheel can be used for zoom. Also on touch pads, vertical or horizontal two finger movement emulates a mouse scroll wheel. In addition a mouse right click, or pad two finger tap is detected.
Each gesture results in a callback, which will contain the required action. These gestures can be added to Kivy widgets by subclassing a Kivy Widget and CommonGestures, and then including the methods for the required gestures.
A minimal example is SwipeScreen, where we implement one callback method:
### A swipe sensitive Screen
class SwipeScreen(Screen, CommonGestures):
def cg_swipe_horizontal(self, touch, right):
# here we add the user defined behavior for the gesture
# this method controls the ScreenManager in response to a swipe
App.get_running_app().swipe_screen(right)
Where the swipe_screen() method configures the screen manager. This is fully implemented along with the other gestures here.
CommonGestures callback methods detect gestures, they do not define behaviors.
CommonGestures implements these gesture callbacks, a child class may use any subset:
############################################
# User Events
# define some subset in the derived class
############################################
############# Tap and Long Press
def cg_tap(self, touch, x, y):
pass
def cg_two_finger_tap(self, touch, x, y):
# also a mouse right click, desktop only
pass
def cg_double_tap(self, touch, x, y):
pass
def cg_long_press(self, touch, x, y):
pass
def cg_long_press_end(self, touch, x, y):
pass
############## Move
def cg_move_start(self, touch, x, y):
pass
def cg_move_to(self, touch, x, y, velocity):
# velocity is average of the last 0.2 sec, in inches/sec :)
pass
def cg_move_end(self, touch, x, y):
pass
############### Move preceded by a long press
def cg_long_press_move_start(self, touch, x, y):
pass
def cg_long_press_move_to(self, touch, x, y, velocity):
# velocity is average of the last 0.2 sec, in inches/sec :)
pass
def cg_long_press_move_end(self, touch, x, y):
pass
############### fast horizontal movement
def cg_swipe_horizontal(self, touch, left_to_right):
pass
def cg_swipe_vertical(self, touch, bottom_to_top):
pass
############### pinch/spread
def cg_scale_start(self, touch0, touch1, x, y):
pass
def cg_scale(self, touch0, touch1, scale, x, y):
pass
def cg_scale_end(self, touch0, touch1):
pass
############# Mouse Wheel, or Windows touch pad two finger vertical move
############# a common shortcut for scroll
def cg_wheel(self, touch, scale, x, y):
pass
############# a common shortcut for pinch/spread
def cg_ctrl_wheel(self, touch, scale, x, y):
pass
############# a common shortcut for horizontal scroll
def cg_shift_wheel(self, touch, scale, x, y):
pass
Pinch/spread focus is the mid point between two fingers. The mouse wheel callbacks are not generated.
Mobile users are not used to a double tap, so use long press. If you do use double tap, the Kivy default detection time is too short for reliable detection of finger taps. You can change this from the default 250mS, for example:
from kivy.config import Config
Config.set('postproc', 'double_tap_time', '500')
On some touchpads pinch/spread will not be detected the if 'mouse, disable_multitouch' feature is not disabled.
Some touch pads report a pinch/spread as a finger movement cg_scale(), and some detect the gesture internally and report it as a cg_ctrl_wheel(). The safe thing to do is handle both cases.
As usual, Move, Long Press Move, Swipe, and Long Press are initiated with press the left mouse button, and end when the press ends. The right mouse button generates a cg_two_finger_tap() callback.
Mouse wheel movement generates t cg_wheel(), cg_shift_wheel(), and cg_ctrl_wheel() callbacks.
As usual, Move, Long Press Move, Swipe, and Long Press are initiated with 'one and a half taps', or a press on the bottom left corner of the trackpad.
Two finger pinch/spread uses the cursor location as focus. Note that the cursor may move significantly during a pinch/spread.
A two finger move is interpreted by a touch pad as the equivalent mouse wheel event. A two finger tap generates a cg_two_finger_tap() callback.
Two finger pinch/spread is not available. Use Command and vertical scroll.
Force Click (deep press) is reported as a long press, this is a happy coincidence and not by design.
Not tested
Not tested
Not tested
A big thank you to Elliot for his analysis, constructive suggestions, and testing.