All event handling is described Chapter 8. There is no change for touch platforms in Introduced in platform.apiLevel = '2.2' except for two new handlers, on-screen keyboard up and down detection --- see on.keyboardUp(keyboardOverlapHeight) and on.keyboardDown() event handler.
Please see Table 2.1 for the mapping between touch gestures and the existing event handlers.
Table 2.1: Gesture to event handler mapping
|
Gesture |
"on" handler |
Comment |
|
Single Tap |
on.mouseDown() on.mouseUp() |
It should be noted that the gesture recognizer adds a small delay between lifting the finger from the screen and sending the mouseUp event. |
|
Double Tap |
on.mouseDown() on.mouseUp() on.mouseDown() on.mouseUp() |
Likewise due to the gesture recognizer the first mouseUp is received after the second tap is complete. The following down and up are send immediately. |
|
Pan |
on.mouseDown() on.mouseMove()'s ... on.mouseUp() |
Same behavior as on a desktop platform when pressing the mouse button, dragging the mouse and releasing the mouse button again. When running on a non-touch platform, on.mouseMove() can be received while the mouse button is not pressed. |
|
Long Press Move |
on.mouseDown() on.mouseMove()'s on.mouseUp() |
Same behavior as pan. There is no differentiation possible from the script |
|
Other Gestures |
on.mouseDown() [on.mouseMove()'s] on.mouseUp() |
Will reliably generate a on.mouseDown() and on.mouseUp() event. One or multiple on.mouseMove() might be send. Multi-finger gestures will report coordinates below or between the fingers. |
Note: The behavior of the mapping described in Table 2.1 is slightly different for mouse handler registered with D2Editor:registerFilter(). In case of single and double tap will the first on.mouseDown() event be received after the gesture is fully recognized and the finger lifted up from the screen. Similar is true for the pan and long press gesture. The on.mouseDown() event is send when either the finger starts moving or the stays without moving for a particular time.
Another important aspect related to event handling is the return value of an event handler. The main use case in platform.apiLevel = '2.0' for event handler return values has been lter event handler registered for a 2D Editor - see D2Editor:registerFilter(). Every event handler may return a boolean to indicate if the event has been handled (true) or ignored (false). If an event handler does not return explicitly a value, the value will default to true. In the context of touch and on-screen keyboard, the return value of mouseDown while the keyboard is up plays an important role and can disturb the user experience when used incorrectly. While the keyboard is up, the user can pan the screen to see content behind the keyboard. If mouseDown returns true, or has no explicit return statement, the user will be prevented from panning the screen.