Specs: Define when pointer events fire; stub for keyboard events

sky/specs/pointer.md

-UI Events
-=========
+Pointer Events
+==============
 
 Scope
 -----
 
 The following input devices are supported by sky:
  - fingers on multitouch screens
  - mice, including mouse wheels
  - styluses on screens
  - other devices that emulate mice (track pads, track balls)
- - keyboards
+ - [Keyboard](keyboard.md)
 
 The following input devices are not supported natively by sky, but can
 be used by connecting directly to the mojo application servicing the
 relevant device:
  - joysticks
  - track balls that move focus (or raw data from track balls)
  - raw data from track pads (e.g. multitouch gestures)
  - raw data from styluses that have their own absolute pads
  - raw data from mice (e.g. to handle mouse capture in 3D games)
 
@@ skipping 17 matching lines @@
  - a zoom/rotation (whether using two finger gestures, or one finger
    with the double-tap-and-hold gesture)
  - a double-tap autozoom
 
 In particular, this means distinguishing whether a finger tap consists
 of a tap, a drag, or a long-press; it also means distinguishing
 whether a drag, once established as such, should be treated as a pan
 or a drag, and deciding whether a secondary touch should begin a
 zoom/rotation or not.
 
+This is done using the [gesture recogniser API](gestures.md)
 
-Pointer events
---------------
+
+Pointers
+--------
 
 Each touch or pointer is tracked individually.
 
 New touches and pointers can appear and disappear over time.
 
 Each pointer has a list of current targets.
 
 When a new one enters the system, a non-bubbling 'pointer-added' event
 is fired at the application's document, and the pointer's current
 targets list is initialised to just that Document object.
@@ skipping 76 matching lines @@
 that only contains the application's document.
 
 Nothing special happens when a pointer's current target moves in the
 DOM.
 
 The x and y position of an -up or -down event always match those of
 the previous -moved or -added event, so their dx and dy are always 0.
 
 Positions are floating point numbers; they can have subpixel values.
 
+For each pointer, only a single pointer-added or pointer-removed event
+is fired per frame. If a pointer would have been added and removed in
+the same frame, the pointer is ignored, and no events are fired for
+that pointer.
+
+For each pointer, only a single pointer-down or pointer-up event is
+fired per frame, representing the change in state from the last frame,
+if any. Exactly when the event is fired is up to the implementation
+and may depend on the hardware.
+
+For each pointer, at most two pointer-move events are fired per frame,
+one before the pointer-down or pointer-up event, if any, and one
+after. If the pointer didn't change "down" state, then only one
+pointer-move event is fired. All the actual moves that the pointer
+experienced are coallesced into the event.
+
+   Example:
+    If a mouse experiences the following events:
+       - move +1, down, move +2, up, move +4, down, move +8
+    ...the events might be:
+       - move +7, down, move +8
+    ...or:
+       - move +1, down, move +14
+
+TODO(ianh): expose the unfiltered uncoalesced stream of events for
+programs that want more precision (e.g. drawing apps)
+
 
 These data of all these events 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)
 
@@ skipping 138 matching lines @@
                  ...giving the angle of the axis of the stylus,
                  relative to the axis perpendicular to the screen
                  (thus 0 indicates the stylus is orthogonal to the
                  plane of the screen, while pi/2 indicates that the
                  stylus is flat on the screen)
 
 
 TODO(ianh): add an API that exposes the currently existing pointers,
 so that you can determine e.g. if you have a mouse.
 
-TODO(ianh): determine what the update frequency of these events should
-be. One set of events per frame? Multiple updates per frame?
 
 
 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
@@ skipping 13 matching lines @@
                  '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
 
 Note: The only wheels that are supported are mouse wheels and physical
 dials. Track balls are not reported as mouse wheels.