Package: gestures4kivy
Gestures for KivyDetect common touch gestures in Kivy apps2023-11-13 This repository is archived.Now with an all new, simpler, input device independent api. The classic api is still implemented, but will be depreciated.InstallDesktop OS:pip3 install gestures4kivyAndroid:Addgestures4kivytobuildozer.specrequirements.iOS:toolchain pip3 install gestures4kivyUsageImport using:from gestures4kivy import CommonGesturesThe following is required at the top of the app's main.py to disable Kivy's multitouch emulation feature:Config.set('input', 'mouse', 'mouse, disable_multitouch')The classCommonGesturesdetects the common gestures for primary event, secondary event, select, drag, scroll, pan, zoom, rotate, and page. These are reported in an input device independent way, see below for details.Each gesture results in a callback, which defines the required action. These gestures can beaddedto Kivy widgets by subclassing a Kivy Widget andCommonGestures, and then including the methods for the required gestures.A minimal example isSwipeScreen, where we implement one callback method:# A swipe sensitive ScreenclassSwipeScreen(Screen,CommonGestures):defcgb_horizontal_page(self,touch,right):# here we add the user defined behavior for the gesture# this method controls the ScreenManager in response to a swipeApp.get_running_app().swipe_screen(right)Where theswipe_screen()method configures the screen manager. This is fully implemented along with the other gestureshere.CommonGesturescallback methods detect gestures; they do not implement behaviors.Widget InteractionIn the example above gesture detection isaddedto the Widget, however some Kivy widgets consume events so they are not passed to CommonGestures. For exampleScrollViewconsumes mouse wheel events so acgb_panis not detected.classHScrollView(ScrollView,CommonGestures):defcgb_pan(self,touch,focus_x,focus_y,delta_x,velocity):print('pan')# this is never calledIf this is not the required behavior, change the module resolution order. CommonGestures and ScrollView events will be called.classHScrollView(CommonGestures,ScrollView):defcgb_pan(self,touch,focus_x,focus_y,delta_x,velocity):print('pan')# this is always calledAPICommonGesturesimplements the following gesture callbacks, a child class may use any subset. The callbacks are initiated by input device events as described below.Callback arguments report the original Kivy touch event(s), the focus of a gesture (the location of a cursor, finger, or mid point between two fingers) in Widget coordinates, and parameters representing the change described by a gesture.Gesture sensitivities can be adjusted by setting values in the class that inherits fromCommonGestures. These values are contained in theself._SOME_NAMEvariables declared in the__init__()method ofCommonGestures.For backwards compatibility a legacy api is implemented (method names begin with 'cg_' not 'cgb_'). The legacy api will eventually be depreciated, and is not documented.Primary eventdefcgb_primary(self,touch,focus_x,focus_y):passMouse - Left button clickTouchpad - one finger tapMobile  - one finger tapSecondary eventdefcgb_secondary(self,touch,focus_x,focus_y):passMouse - Right button clickTouchpad - two finger tapMobile  - two finger tapSelectdefcgb_select(self,touch,focus_x,focus_y,long_press):# If long_press == True# Then on a mobile device set visual feedback.passdefcgb_long_press_end(self,touch,focus_x,focus_y):# Only called if cgb_select() long_press argument was True# On mobile device reset visual feedback.passMouse - double clickTouchpad - double tap, or long deep pressMobile  - double tap, long presscgb_long_press_end()is called when a user raises a finger after a long press. This may occur after a select or after a drag initiated by a long press.Dragdefcgb_drag(self,touch,focus_x,focus_y,delta_x,delta_y):passMouse - hold mouse button and move mouseTouchpad - deep press (or one and a half taps) and move fingerMobile  - long press (provide visual feeback) and move fingerScrolldefcgb_scroll(self,touch,focus_x,focus_y,delta_y,velocity):passMouse - rotate scroll wheelTouchpad - two finger vertical motionMobile  - one finger vertical motionA scroll gesture is very similar to a vertical page gesture, using the two in the same layout may be a challenge particularly on a touchpad.Pandefcgb_pan(self,touch,focus_x,focus_y,delta_x,velocity):passMouse - Press Shift key, and rotate scroll wheelTouchpad - two finger horizontal motionMobile  - one finger horizontal motionA pan gesture is very similar to a horizontal page gesture, using the two in the same layout may be a challenge particularly on a touchpad.Zoomdefcgb_zoom(self,touch0,touch1,focus_x,focus_y,delta_scale):passMouse - Press Ctrl key, and rotate scroll wheelTouchpad - two finger pinch/spreadMobile  - two finger  pinch/spreadOn a Mac, the Command key is the convention for zoom, either Command or Ctrl can be used.The touch1 parameter may beNone.Rotatedefcgb_rotate(self,touch0,touch1,focus_x,focus_y,delta_angle):passMouse - Press Alt key, and rotate scroll wheelTouchpad - Press Alt key, plus two finger vertical motionMobile  - two finger twistOn a Mac, Alt is the key labeled OptionOn Linux, Alt is not available as a modifier, use the sequence CapsLock,Scroll,CapsLock.The touch1 parameter may beNone.Horizontal Pagedefcgb_horizontal_page(self,touch,left_to_right):passMouse - hold mouse button and fast horizontal move mouseTouchpad - fast two finger horizontal motionMobile  - fast one finger horizontal motionSeePanfor possible interactions.Vertical Pagedefcgb_vertical_page(self,touch,bottom_to_top):passMouse - hold mouse button and fast vertical move mouseTouchpad - fast two finger vertical motionMobile  - fast one finger vertical motionSeeScrollfor possible interactions.Known Issues:Kivy MultitouchKivy multitouch must be disabled. A ctrl-scroll with a mouse (the common convention for zoom), a pinch-spread with a touchpad, a right click, or a two finger tap will place an orange dot on the screen and inhibit zoom functionality.Config.set('input','mouse','mouse, disable_multitouch')MacTrackpap two finger pinch/spread is not available. UseCommandorCtrlandScroll. This is apparently an SDl2 issue.LinuxAlt is not a keyboard modifier on Linux. For the rotate operation set CapsLock, scroll, and unset CapsLock.