Table Of Contents

• Motion Event
  • Motion Event and Touch
  • Listening to a Motion Event
  • Profiles

Motion Event

The MotionEvent is the base class used for events provided by pointing devices (touch and non-touch). This class defines all the properties and methods needed to handle 2D and 3D movements but has many more capabilities.

Note

You never create the MotionEvent yourself: this is the role of the providers.

Motion Event and Touch

We differentiate between a Motion Event and Touch event. A Touch event is a MotionEvent with the pos profile. Only these events are dispatched throughout the widget tree.

1. The MotionEvent ‘s are gathered from input providers.

2. All the MotionEvent ‘s are dispatched from

   on_motion().

3. If a MotionEvent has a pos profile, we dispatch it through

   on_touch_down(), on_touch_move() and on_touch_up().

Listening to a Motion Event

If you want to receive all MotionEvents, Touch or not, you can bind the MotionEvent from the Window to your own callback:

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

Window.bind(on_motion=on_motion)

You can also listen to changes of the mouse position by watching mouse_pos.

Profiles

The MotionEvent stores device specific information in various properties listed in the profile. For example, you can receive a MotionEvent that has an angle, a fiducial ID, or even a shape. You can check the profile attribute to see what is currently supported by the MotionEvent provider.

This is a short list of the profile values supported by default. Please check the MotionEvent.profile property to see what profile values are available.

Profile value	Description
angle	2D angle. Accessed via the a property.
button	Mouse button (‘left’, ‘right’, ‘middle’, ‘scrollup’ or ‘scrolldown’). Accessed via the button property.
markerid	Marker or Fiducial ID. Accessed via the fid property.
pos	2D position. Accessed via the x, y or pos properties.
pos3d	3D position. Accessed via the x, y or z properties.
pressure	Pressure of the contact. Accessed via the pressure property.
shape	Contact shape. Accessed via the shape property .

If you want to know whether the current MotionEvent has 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: 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)

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 of the 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.

property 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 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

Used to determine which widget the touch is being dispatched to. Check the 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

property is_mouse_scrolling

Returns True if the touch is a mousewheel scrolling

New in version 1.6.0.

is_touch

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

is_triple_tap

Indicate if the touch is a triple tap or not

New in version 1.7.0.

move(args)

Move the touch to another position

property 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

Position (X, Y), in window range

property 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 attribute values in attrs onto 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, smode='None', kheight=0)

Scale position for the screen

shape

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

property 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_end

Time of the end event (last touch usage)

time_start

Initial time of the touch creation

time_update

Time of the last update

triple_tap_time

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

User data dictionary. Use this dictionary 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 previously grabbed touch

x

X position, in window range

y

Y position, in window range

z

Z position, in window range

« Input recorder

Motion Event Factory »