Specs: UI events, first draft (covers just pointer events for now)

sky/specs/ui.md

+UI Events
+=========
+
+Pointer events
+--------------
+
+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.
+
+
+Wheel events
+------------
+
+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
+
+
+Text input events
+-----------------
+
+TODO(ianh): keyboard events