Version

Quick search

Table Of Contents

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.

Usually you would never need to create the MotionEvent yourself as this is the role of the providers.

Flow of the motion events

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

  2. Post processing is performed by registered processors postproc.

  3. EventLoopBase dispatches all motion events using on_motion event to all registered listeners including the WindowBase.

  4. Once received in on_motion() events (touch or non-touch) are all registered managers. If a touch event is not handled by at least one manager, then it is dispatched through on_touch_down(), on_touch_move() and on_touch_up().

  5. Widgets receive events in on_motion() method (if passed by a manager) or on on_touch_xxx methods.

Motion events and event managers

A motion event is a touch event if its MotionEvent.is_touch is set to True. Beside is_touch attribute, MotionEvent.type_id can be used to check for event’s general type. Currently two types are dispatched by input providers: “touch” and “hover”.

Event managers can be used to dispatch any motion event throughout the widget tree and a manager uses type_id to specify which event types it want to receive. See eventmanager to learn how to define and register an event manager.

A manager can also assign a new type_id to MotionEvent.type_id before dispatching it to the widgets. This useful when dispatching a specific event:

class MouseTouchManager(EventManagerBase):

    type_ids = ('touch',)

    def dispatch(self, etype, me):
        accepted = False
        if me.device == 'mouse':
            me.push() # Save current type_id and other values
            me.type_id = 'mouse_touch'
            self.window.transform_motion_event_2d(me)
            # Dispatch mouse touch event to widgets which registered
            # to receive 'mouse_touch'
            for widget in self.window.children[:]:
                if widget.dispatch('on_motion', etype, me):
                    accepted = True
                    break
            me.pop() # Restore
        return accepted

Listening to a motion event

If you want to receive all motion events, touch or not, you can bind the MotionEvent from the Window to your own callback:

def on_motion(self, etype, me):
    # 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, is_touch=False, type_id=None)

Bases: kivy.input.motionevent.MotionEvent

Abstract class that represents an input event.

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 motion event object.

depack(args)

Depack args into attributes of the class

dispatch_done()

Notify that dispatch to the listeners is done.

Called by the EventLoopBase.post_dispatch_input().

New in version 2.1.0.

distance(other_touch)

Return the distance between the two events.

property dpos

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

grab(class_instance, exclusive=False)

Grab this motion event.

If this event is a touch you can grab it 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

Changed in version 2.1.0: Allowed grab for non-touch events.

property is_mouse_scrolling

Returns True if the touch event is a mousewheel scrolling

New in version 1.6.0.

move(args)

Move to another position.

property opos

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

pop()

Pop attributes values from the stack.

property ppos

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

push(attrs=None)

Push attribute values in attrs onto the stack.

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

Scale position for the screen.

Changed in version 2.1.0: Max value for x, y and z is changed respectively to w - 1, h - 1 and p - 1.

property spos

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

to_absolute_pos(nx, ny, x_max, y_max, rotation)

Transforms normalized (0-1) coordinates nx and ny to absolute coordinates using x_max, y_max and rotation.

Raises:

ValueError: If rotation is not one of: 0, 90, 180 or 270

New in version 2.1.0.

ungrab(class_instance)

Ungrab a previously grabbed motion event.

« Input recorder Motion Event Factory »