From 08043dbe6d7deec764aeec776aacef60a0c7f271 Mon Sep 17 00:00:00 2001
From: Hixie <github.com@spam.hixie.ch>
Date: Fri, 30 Jan 2015 10:03:26 -0800
Subject: [PATCH] Specs: Define when pointer events fire; stub for keyboard
 events

Review URL: https://codereview.chromium.org/892633004
---
 specs/keyboard.md | 32 ++++++++++++++++++++++++++++++++
 specs/pointer.md  | 41 ++++++++++++++++++++++++++++++++++-------
 2 files changed, 66 insertions(+), 7 deletions(-)
 create mode 100644 specs/keyboard.md

diff --git a/specs/keyboard.md b/specs/keyboard.md
new file mode 100644
index 00000000000..6abdc1a3d91
--- /dev/null
+++ b/specs/keyboard.md
@@ -0,0 +1,32 @@
+Keyboard Events
+===============
+
+Scope
+-----
+
+The Sky keyboard API is intended to handle the following:
+
+- reporting raw key down/up events from physical keyboards ("Alt"
+  down, "E" down, "E" up, "Alt" up)
+
+- reporting simulated raw key down/up events from virtual keyboards,
+  if the keyboard provides them
+
+- IME
+   - reporting input text events from physical and virtual keyboards
+     ("é", autorepeat)
+   - inline editing of typed word
+   - backspace
+   - autocorrect
+   - editing around app-provided chips
+   - adjusting editor UI (line height, word spacing, etc)
+   - replacing selection
+   - providing per-phrase alternative interpretations
+   - composing letters
+   - composing words
+
+
+API
+---
+
+TODO(ianh): Write API.
diff --git a/specs/pointer.md b/specs/pointer.md
index 7c728e732b2..b73f03d2d04 100644
--- a/specs/pointer.md
+++ b/specs/pointer.md
@@ -1,5 +1,5 @@
-UI Events
-=========
+Pointer Events
+==============
 
 Scope
 -----
@@ -9,7 +9,7 @@ The following input devices are supported by sky:
  - 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
@@ -47,9 +47,11 @@ 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.
 
@@ -146,6 +148,33 @@ 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:
 
@@ -304,8 +333,6 @@ When kind is 'stylus' or 'stylus-inverted':
 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