Module device.gesturedetector

This module detects gestures.

Current detectable gestures:

  • touch (emitted once on first contact down)
  • tap (touch action detected as single tap)
  • pan
  • hold
  • swipe
  • pinch
  • spread
  • rotate
  • hold_pan (will emit hold_release on contact lift, unlike its two-finger variant)
  • double_tap
  • inward_pan
  • outward_pan
  • pan_release
  • hold_release
  • two_finger_hold
  • two_finger_hold_release
  • two_finger_tap
  • two_finger_pan
  • two_finger_hold_pan
  • two_finger_swipe
  • two_finger_pan_release
  • two_finger_hold_pan_release

You change the state machine by feeding it touch events, i.e. calling GestureDetector:feedEvent(tev).

a touch event should have following format:

tev = {
    slot = 1,
    id = 46,
    x = 0,
    y = 1,
    timev = time.s(123.23),
}

Don't confuse tev with raw evs from kernel, tev is built according to ev.

GestureDetector:feedEvent(tev) will return a detection result when you feed a touch release event to it.

Functions

GestureDetector:feedEvent (tevs) Feeds touch events to state machine.
Contact:getPath (simple, diagonal, initial_tev) Compares current_tev with initial_tev.
GestureDetector:probeClockSource (timev) Attempts to figure out which clock source tap events are using...
Contact:tapState (new_tap) Handles both single and double tap.
Contact:handleDoubleTap () Emits both tap & double_tap gestures.
Contact:handleNonTap (new_tap) Handles move (switch to panState) & hold (switch to holdState).
Contact:panState (keep_contact) Handles the full panel of pans & swipes, including their two-finger variants.
Contact:voidState () Used to ignore a buddy slot part of a MT gesture, so that we don't send duplicate events.
Contact:handleSwipe () Emits the swipe & multiswipe gestures.
Contact:handlePan () Emits the pan gestures and handles their two finger variants.
Contact:handleTwoFingerPan (buddy_contact) Emits the pan, twofingerpan, twofingerholdpan, inwardpan, outward_pan & rotate gestures.
Contact:handlePanRelease (keep_contact) Emits the panrelease & twofingerpanrelease gestures.
Contact:holdState (new_hold) Emits the hold, holdrelease & holdpan gestures and their two_finger variants.
GestureDetector:adjustGesCoordinate (ges) Changes gesture's x and y coordinates according to screen view mode.


Functions

GestureDetector:feedEvent (tevs)
Feeds touch events to state machine.

Note that, in a single input frame, if the same slot gets multiple events, only the last one is kept. Every slot in the input frame is consumed, and that in FIFO order (slot order based on appearance in the frame).

Parameters:

  • tevs
Contact:getPath (simple, diagonal, initial_tev)
Compares current_tev with initial_tev.

The first boolean argument simple results in only four directions if true.

Parameters:

  • simple
  • diagonal
  • initial_tev

Returns:

    (direction, distance) pan direction and distance
GestureDetector:probeClockSource (timev)
Attempts to figure out which clock source tap events are using...

Parameters:

  • timev We'll check if that timestamp is +/- 2.5s away from the three potential clock sources supported by evdev. We have bigger issues than this if we're parsing events more than 3s late ;).
Contact:tapState (new_tap)
Handles both single and double tap. new_tap is true for the initial contact down event.

Parameters:

  • new_tap
Contact:handleDoubleTap ()
Emits both tap & doubletap gestures. Contact is up (but down is still true) or pending a doubletap timer.
Contact:handleNonTap (new_tap)
Handles move (switch to panState) & hold (switch to holdState). Contact is down. new_tap is true for the initial contact down event.

Parameters:

  • new_tap
Contact:panState (keep_contact)
Handles the full panel of pans & swipes, including their two-finger variants.

Parameters:

  • keep_contact
Contact:voidState ()
Used to ignore a buddy slot part of a MT gesture, so that we don't send duplicate events.
Contact:handleSwipe ()
Emits the swipe & multiswipe gestures. Contact is up. ST only (i.e., there isn't any buddy contact active).
Contact:handlePan ()
Emits the pan gestures and handles their two finger variants. Contact is down (and either in holdState or panState).
Contact:handleTwoFingerPan (buddy_contact)
Emits the pan, twofingerpan, twofingerholdpan, inwardpan, outward_pan & rotate gestures. Contact is down in panState or holdState, or up in panState if it was lifted below the swipe interval.

Parameters:

  • buddy_contact logger.dbg("Contact handleTwoFingerPan for slot", self.slot)
Contact:handlePanRelease (keep_contact)
Emits the panrelease & twofingerpanrelease gestures. Contact is up (but down is still true) and in panState.

Parameters:

  • keep_contact logger.dbg("Contact handlePanRelease for slot", self.slot)
Contact:holdState (new_hold)
Emits the hold, holdrelease & holdpan gestures and their two_finger variants.

Parameters:

  • new_hold
GestureDetector:adjustGesCoordinate (ges)
Changes gesture's x and y coordinates according to screen view mode.

Parameters:

  • ges gesture that you want to adjust

Returns:

    adjusted gesture.
generated by LDoc 1.5.0 Last updated 2025-07-09 10:50:23