Each touch or pointer is tracked individually.
New touches and pointers can appear and disappear over time.
When a new one enters the system, a ‘pointer-added’ event is fired at the application's document.
When it is removed, a ‘pointer-removed’ event is fired at the application's document.
When one switches from “up” to “down”, the position of the tap is hit tested and a ‘pointer-down’ event is fired at the target element under the cursor, if any, or the document otherwise.
When one moves, if it is “up” then a ‘pointer-moved’ event is fired at the application's document, otherwise if it is “down” then the event is fired at the element or document that was selected for the ‘pointer-down’ event.
When one switches from “down” to “up”, a ‘pointer-up’ event is fired at the element or document that was selected for the ‘pointer-down’ event.
These events all bubble and their data is an object with the following fields:
pointer: an integer assigned to this touch or pointer when it enters the system, never reused, increasing monotonically every time a new value is assigned, starting from 1 (if the system gets a new tap every microsecond, this will cause a problem after 285 years)
x: x-position relative to the top-left corner of the display,
in global layout coordinates
y: x-position relative to the top-left corner of the display,
in global layout coordinates
buttons: a bitfield of the buttons pressed, where 1 is the primary button, 2 is the secondary, and subsequent numbers refer to any other buttons
TODO(ianh): add other fields for touches (radius/pressure, angle)
TODO(ianh): should we use a different way to express buttons? e.g. create a new touch for the secondary button when it goes down, removing the touch when it goes back up?
TODO(ianh): find a way to avoid the trap everyone always falls into of treating all the buttons as equivalent to a touch (e.g. right-clicking a button shouldn't trigger the button). For example, maybe we should remove ‘buttons’ and use different event names for the up/down state changes of non-primary buttons of pointers, like ‘pointer-down-2’ for the secondary button, ‘pointer-down-3’ for the middle mouse button, and so on.
When a wheel input device is turned, a ‘wheel’ event that bubbles is fired at the application's document, with the following fields:
wheel: an integer assigned to this wheel by the system. The same
wheel on the same system must always be given the same ID.
The primary wheel (e.g. the vertical wheel on a mouse)
must be given ID 1.
delta: an floating point number representing the fraction of the
wheel that was turned, with positive numbers representing
a downward movement on vertical wheels, rightward movement
on horizontal wheels, and a clockwise movement on wheels
with a user-facing side.
Additionally, if the wheel is associated with a pointer (e.g. a mouse wheel), the following fields must be present also:
pointer: the integer assigned to the pointer in its ‘pointer-add’ event (see above).
x: x-position relative to the top-left corner of the display,
in global layout coordinates
y: x-position relative to the top-left corner of the display,
in global layout coordinates
TODO(ianh): keyboard events