Motion Event

The MotionEvent is the base class used for every touch and no-touch event. This class define all the properties and methods needed to handle 2D and 3D position, but may have more capabilities.

Note

You never create the MotionEvent yourself, this is the role of the ~kivy.input.providers.

Motion Event and Touch

We differentiate Motion Event and Touch event. A Touch event is a MotionEvent with the pos profile. Only theses event are dispatched all over the widget tree.

  1. The MotionEvent are gathered from input providers

  2. All the MotionEvent are dispatched in

    on_motion().

  3. If a MotionEvent have a pos profile, we dispatch them in

    on_touch_down(),move,up.

Listen to Motion Event

If you want to receive all Motion Event, Touch or not, you can bind motion event from Window to your own callbacks

def on_motion(self, etype, motionevent):
    # will receive all motion event.
    pass

Window.bind(on_motion=on_motion)

Profiles

A capability is the ability of a MotionEvent to store a new information, or a way to indicate what is supported by the Motion Event. For example, you can receive a Motion Event that have an angle, a fiducial ID, or even a shape. You can check the profile attribute to check what is currently supported by the Motion Event, and how to access on it.

This is a tiny list of the supported profiles by default. Check other input providers to know if they are other profiles available.

Profile name Description
angle 2D angle. Use property a
markerid Marker or Fiducial ID. Use property fid
pos 2D position. Use properties x, y
pos3d 3D position. Use properties x, y, z
pressure Pressure of the contact. Use property pressure
shape Contact shape. Use property shape

If yo want to know if the current MotionEvent have an angle

def on_touch_move(self, touch):
    if 'angle' in touch.profile:
        print 'The touch angle is', touch.a

If you want to select only the fiducials

def on_touch_move(self, touch):
    if 'markerid' not in touch.profile:
        return
class kivy.input.motionevent.MotionEvent(device, id, args)

Bases: object

Abstract class to represent a touch and no-touch object.

Parameters :
id : str

uniq ID of the Motion Event

args : list

list of parameters, passed to depack() function

apply_transform_2d(transform)

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

copy_to(to)

Copy some attribute to another touch object.

depack(args)

Depack args into attributes in class

device

Device used for creating this touch

distance(other_touch)

Return the distance between the current touch and another touch.

double_tap_time

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

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

dsy

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

dsz

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

dx

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

dy

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

dz

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

grab(class_instance, exclusive=False)

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

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

def on_touch_move(self, touch):
    if touch.grab_current == self:
        # i receive my grabbed touch
    else:
        # it's a normal touch

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

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

id

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

Indicate if the touch is a double tap or not

is_touch

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

move(args)

Move the touch to another position

opos

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

osx

Origin X position, in 0-1 range.

osy

Origin Y position, in 0-1 range.

osz

Origin Z position, in 0-1 range.

ox

Origin X position, in window range

oy

Origin Y position, in window range

oz

Origin Z position, in window range

pop()

Pop attributes values from the stack

pos

Return position of the touch in the screen coordinate system (self.x, self.y)

ppos

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

profile

Profiles currently used in the touch

psx

Previous X position, in 0-1 range.

psy

Previous Y position, in 0-1 range.

psz

Previous Z position, in 0-1 range.

push(attrs=None)

Push attributes values in attrs in the stack

push_attrs_stack

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

px

Previous X position, in window range

py

Previous Y position, in window range

pz

Previous Z position, in window range

scale_for_screen(w, h, p=None, rotation=0)

Scale position for the screen

shape

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

X position, in 0-1 range

sy

Y position, in 0-1 range

sz

Z position, in 0-1 range

time_start

Initial time of the touch creation

ud

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

uid

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

ungrab(class_instance)

Ungrab a previous grabbed touch

x

X position, in window range

y

Y position, in window range

z

Z position, in window range