DevGuide > TouchEvents

Touch events

Event dispatchingEvents

In this document

Simple touch interaction

Example of simple interaction with a widget:

3 events will be called:

  • on_touch_down()
  • on_touch_move() (can be multiple time)
  • on_touch_up()

Stop touch event propagation

Imagine that the touch was handled by a button. You don't want the event to be used by another widget.

You can stop the dispatching of the event by returning True in the event handler:

@widA.event
def on_touch_down(touch):
  print 'This is my touch !!'
  return True

Grab a touch for ourself

There is a possibility that you can't receive the on_touch_up() event. Why? Just check this picture:

The touch has left the widget. When collision is tested on your widget, you'll never receive the on_touch_up() event! So, what can we do?

Solution: use the grab() / ungrab() method on the touch.

@widD.event
def on_touch_down(touch):
  # check if the touch is inside the widget
  if not widD.collide_point(*touch.pos):
    return
  # the touch is inside the widget, grab for us !
  touch.grab(widD)
  # stop dispatching of this event
  return True

@widD.event
def on_touch_move(touch):
  # is the touch is a previously grabbed touch ?
  if touch.grab_current != widD:
    return
  # this is our touch !
  print 'My touch move to', touch.pos
  return

@widD.event
def on_touch_up(touch):
  # is the touch is a previously grabbed touch ?
  if touch.grab_current != widD:
    return
  # this is our touch !
  print 'My touch up !!!!'
  return

The touch.grab_current property is used to select only the previously grabbed touch. Here is how the grabbed touch event is dispatched:

If a touch is grabbed by a widget, it will receive the touch's events directly, whatever its position in the tree!