Skip to main content

Detect common touch gestures in Kivy apps

Project description

Gestures for Kivy

Detect common touch gestures in Kivy apps

Now with an all new, simpler, input device independent api. The classic api is still implemented, but will be depreciated.

Install

Desktop OS:

pip3 install gestures4kivy

Android:

Add gestures4kivy to buildozer.spec requirements.

iOS:

toolchain pip3 install gestures4kivy

Usage

Import using:

from gestures4kivy import CommonGestures

The 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 class CommonGestures detects 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 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 cgb_horizontal_page(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 implement behaviors.

API

CommonGestures implements 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 from CommonGestures. These values are contained in the self._SOME_NAME variables declared in the __init__() method of CommonGestures.

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 event

    def cgb_primary(self, touch, focus_x, focus_y):
        pass
  • Mouse - Left button click
  • Touchpad - one finger tap
  • Mobile - one finger tap

Secondary event

    def cgb_secondary(self, touch, focus_x, focus_y):
        pass
  • Mouse - Right button click
  • Touchpad - two finger tap
  • Mobile - two finger tap

Select

    def cgb_select(self, touch, focus_x, focus_y, long_press):
        # If long_press == True
        # Then on a mobile device set visual feedback.
        pass

    def cgb_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.
        pass
  • Mouse - double click
  • Touchpad - double tap, or long deep press
  • Mobile - double tap, long press

cgb_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.

Drag

    def cgb_drag(self, touch, focus_x, focus_y, delta_x, delta_y):
        pass
  • Mouse - hold mouse button and move mouse
  • Touchpad - deep press (or one and a half taps) and move finger
  • Mobile - long press (provide visual feeback) and move finger

Scroll

    def cgb_scroll(self, touch, focus_x, focus_y, delta_y, velocity):
        pass
  • Mouse - rotate scroll wheel
  • Touchpad - two finger vertical motion
  • Mobile - one finger vertical motion

A 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.

Pan

    def cgb_pan(self, touch, focus_x, focus_y, delta_x, velocity):
        pass
  • Mouse - Press Shift key, and rotate scroll wheel
  • Touchpad - two finger horizontal motion
  • Mobile - one finger horizontal motion

A 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.

Zoom

    def cgb_zoom(self, touch0, touch1, focus_x, focus_y, delta_scale):
        pass
  • Mouse - Press Ctrl key, and rotate scroll wheel
  • Touchpad - two finger pinch/spread
  • Mobile - two finger pinch/spread

On a Mac, the Command key is the convention for zoom, either Command or Ctrl can be used.

The touch1 parameter may be None.

Rotate

    def cgb_rotate(self, touch0, touch1, focus_x, focus_y, delta_angle):
        pass
  • Mouse - Press Alt key, and rotate scroll wheel
  • Touchpad - Press Alt key, plus two finger vertical motion
  • Mobile - two finger twist

On a Mac, Alt is the key labeled Option

On Linux, Alt is not available as a modifier, use the sequence CapsLock,Scroll,CapsLock.

The touch1 parameter may be None.

Horizontal Page

    def cgb_horizontal_page(self, touch, left_to_right):
        pass
  • Mouse - hold mouse button and fast horizontal move mouse
  • Touchpad - fast two finger horizontal motion
  • Mobile - fast one finger horizontal motion

See Pan for possible interactions.

Vertical Page

    def cgb_vertical_page(self, touch, bottom_to_top):
        pass
  • Mouse - hold mouse button and fast vertical move mouse
  • Touchpad - fast two finger vertical motion
  • Mobile - fast one finger vertical motion

See Scroll for possible interactions.

Known Issues:

Kivy Multitouch

Kivy 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')

Mac

Trackpap two finger pinch/spread is not available. Use Command or Ctrl and Scroll. This is apparently an SDl2 issue.

Linux

Alt is not a keyboard modifier on Linux. For the rotate operation set CapsLock, scroll, and unset CapsLock.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gestures4kivy-0.1.0.tar.gz (11.4 kB view details)

Uploaded Source

Built Distribution

gestures4kivy-0.1.0-py3-none-any.whl (9.9 kB view details)

Uploaded Python 3

File details

Details for the file gestures4kivy-0.1.0.tar.gz.

File metadata

  • Download URL: gestures4kivy-0.1.0.tar.gz
  • Upload date:
  • Size: 11.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.10.1

File hashes

Hashes for gestures4kivy-0.1.0.tar.gz
Algorithm Hash digest
SHA256 59b555f7a3cc4c83438e5ee924eeba9eb1eaf15e9328a2336af45b860cc2c022
MD5 62514689ce9c71aaa9009816718f79c4
BLAKE2b-256 6004c146e0b0bde9fa01c2b020291524d64becf990702d60e28bc9148f827498

See more details on using hashes here.

File details

Details for the file gestures4kivy-0.1.0-py3-none-any.whl.

File metadata

File hashes

Hashes for gestures4kivy-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 1a20de58d4a515c546adbd8f9d386a23511755888cb36e6a6496d02581483d42
MD5 c197ce0b648503df844adff1c77f559a
BLAKE2b-256 70ef9b0c18ca4328eaf07fcc80c348311f3259f322be9aa4ba57584cfebbb16d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page