Motion Event — Kivy v1.0.1-dev documentation

# 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