Version

Quick search

Table Of Contents

Input management

Our input system is wide and simple at the same time. We are currently able to natively support :

  • Windows multitouch events (pencil and finger)
  • OS X touchpads
  • Linux multitouch events (kernel and mtdev)
  • Linux wacom drivers (pencil and finger)
  • TUIO

All the input management is configurable in the Kivy config. You can easily use many multitouch devices in one Kivy application.

When the events have been read from the devices, they are dispatched through a post processing module before being sent to your application. We also have several default modules for :

  • Double tap detection
  • Decreasing jittering
  • Decreasing the inaccuracy of touch on “bad” DIY hardware
  • Ignoring regions
class kivy.input.MotionEvent(device, id, args)[source]

Bases: kivy.input.motionevent.MotionEvent

Abstract class that represents an input event (touch or non-touch).

Parameters:
id: str

unique ID of the MotionEvent

args: list

list of parameters, passed to the depack() function

apply_transform_2d(transform)[source]

Apply a transformation on x, y, z, px, py, pz, ox, oy, oz, dx, dy, dz

copy_to(to)[source]

Copy some attribute to another touch object.

depack(args)[source]

Depack args into attributes of the class

device = None

Device used for creating this touch

distance(other_touch)[source]

Return the distance between the current touch and another touch.

double_tap_time = None

If the touch is a is_double_tap, this is the time between the previous tap and the current touch.

dpos

Return delta between last position and current position, in the screen coordinate system (self.dx, self.dy)

dsx = None

Delta between self.sx and self.psx, in 0-1 range.

dsy = None

Delta between self.sy and self.psy, in 0-1 range.

dsz = None

Delta between self.sz and self.psz, in 0-1 range.

dx = None

Delta between self.x and self.px, in window range

dy = None

Delta between self.y and self.py, in window range

dz = None

Delta between self.z and self.pz, in window range

grab(class_instance, exclusive=False)[source]

Grab this motion event. You can grab a touch if you want to receive subsequent on_touch_move() and on_touch_up() events, even if the touch is not dispatched by the parent:

def on_touch_down(self, touch):
    touch.grab(self)

def on_touch_move(self, touch):
    if touch.grab_current is self:
        # I received my grabbed touch
    else:
        # it's a normal touch

def on_touch_up(self, touch):
    if touch.grab_current is self:
        # I receive my grabbed touch, I must ungrab it!
        touch.ungrab(self)
    else:
        # it's a normal touch
        pass
grab_current = None

Used to determine which widget the touch is being dispatched to. Check the grab() function for more information.

id = None

Id of the touch, not uniq. This is generally the Id set by the input provider, like ID in TUIO. If you have multiple TUIO source, the same id can be used. Prefer to use uid attribute instead.

is_double_tap = None

Indicate if the touch is a double tap or not

is_mouse_scrolling

Returns True if the touch is a mousewheel scrolling

New in version 1.6.0.

is_touch = None

True if the Motion Event is a Touch. Can be also verified is pos is profile.

is_triple_tap = None

Indicate if the touch is a triple tap or not

New in version 1.7.0.

move(args)[source]

Move the touch to another position

opos

Return the initial position of the touch in the screen coordinate system (self.ox, self.oy)

osx = None

Origin X position, in 0-1 range.

osy = None

Origin Y position, in 0-1 range.

osz = None

Origin Z position, in 0-1 range.

ox = None

Origin X position, in window range

oy = None

Origin Y position, in window range

oz = None

Origin Z position, in window range

pop()[source]

Pop attributes values from the stack

pos = None

Position (X, Y), in window range

ppos

Return the previous position of the touch in the screen coordinate system (self.px, self.py)

profile = None

Profiles currently used in the touch

psx = None

Previous X position, in 0-1 range.

psy = None

Previous Y position, in 0-1 range.

psz = None

Previous Z position, in 0-1 range.

push(attrs=None)[source]

Push attribute values in attrs onto the stack

push_attrs_stack = None

Attributes to push by default, when we use push() : x, y, z, dx, dy, dz, ox, oy, oz, px, py, pz.

px = None

Previous X position, in window range

py = None

Previous Y position, in window range

pz = None

Previous Z position, in window range

scale_for_screen(w, h, p=None, rotation=0, smode='None', kheight=0)[source]

Scale position for the screen

shape = None

Shape of the touch, subclass of Shape. By default, the property is set to None

spos

Return the position in the 0-1 coordinate system (self.sx, self.sy)

sx = None

X position, in 0-1 range

sy = None

Y position, in 0-1 range

sz = None

Z position, in 0-1 range

time_end = None

Time of the end event (last touch usage)

time_start = None

Initial time of the touch creation

time_update = None

Time of the last update

triple_tap_time = None

If the touch is a is_triple_tap, this is the time between the first tap and the current touch.

New in version 1.7.0.

ud = None

User data dictionary. Use this dictionary to save your own data on the touch.

uid = None

Uniq ID of the touch. You can safely use this property, it will be never the same accross all existing touches.

ungrab(class_instance)[source]

Ungrab a previously grabbed touch

x = None

X position, in window range

y = None

Y position, in window range

z = None

Z position, in window range

class kivy.input.MotionEventProvider(device, args)[source]

Bases: builtins.object

Base class for a provider.

start()[source]

Start the provider. This method is automatically called when the application is started and if the configuration uses the current provider.

stop()[source]

Stop the provider.

update(dispatch_fn)[source]

Update the provider and dispatch all the new touch events though the dispatch_fn argument.

class kivy.input.MotionEventFactory[source]

Bases: builtins.object

MotionEvent factory is a class that registers all availables input factories. If you create a new input factory, you need to register it here:

MotionEventFactory.register('myproviderid', MyInputProvider)
static get(name)[source]

Get a provider class from the provider id

static list()[source]

Get a list of all available providers

static register(name, classname)[source]

Register a input provider in the database