[PATCH inputproto] specs: explain touch behaviour for dependent devices

[Peter Hutterer]

Dependent devices don't send touch events until the interaction is a true
touch interaction (i.e. doesn't just serve to move the pointer). Once that
happens, all touchpoints send touch events exclusively. Pointer movement
restarts once we're down to one touch that controls the pointer again.

For clients listening to touch events in addition to pointer events, this
also means that a two-finger tap looks identical to holding one finger down
and tapping with a second-finger. Both actions will result in short
TouchBegin/TouchEnd sequences for both fingers.

The above is the default behaviour we expect from touchpads, the protocol is
more generically worded to leave more room for drivers to decide when a
touch only controls the pointer and when it doesn't.

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
Reviewed-by: Chase Douglas <chase.douglas at canonical.com>
---
 specs/XI2proto.txt |   50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 50 insertions(+), 0 deletions(-)

diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index 9a9217a..10f953a 100644
--- a/specs/XI2proto.txt
+++ b/specs/XI2proto.txt
@@ -445,6 +445,56 @@ A window set is calculated on TouchBegin and remains constant until the end
 of the sequence. Modifications to the window hierarchy, new grabs or changed
 event selection do not affect the window set.
 
+Pointer control of dependent devices
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+On a dependent device, the device may differ between a pointer-controlling
+touch and a non-pointer-controlling touch. For example, on a touchpad the
+first touch is pointer-controlling (i.e. serves only to move the visible
+pointer). Multi-finger gestures on a touchpad cause all touches to be
+non-pointer-controlling.
+
+For pointer-controlling touches, no touch events are sent; the touch
+generates regular pointer events instead. Non-pointer-controlling touches
+send touch events. A touch may change from pointer-controlling to
+non-pointer-controlling, or vice versa.
+
+- If a touch changes from pointer-controlling to non-pointer-controlling,
+ a new touch ID is assigned and a TouchBegin is sent for the last known
+ position of the touch. Further events are sent as TouchUpdate events, or as
+ TouchEnd event if the touch terminates.
+
+- If a touch changes from non-pointer-controlling to pointer-controlling, a
+  TouchEnd is sent for that touch at the last known position of the touch.
+  Further events are sent as pointer events.
+
+The conditions to switch from pointer-controlling to non-pointer-controlling
+touch is implementation-dependent. A device may support touches that are
+both pointer-controlling and a touch event.
+
+.Dependent touch example event sequence on a touchpad, touches are marked
+when switching to pointer-controlling (pc) or to non-pointer-controlling (np)
+[width="50%", options="header"]
+|====================================================
+| Finger 1 | Finger 2 | Event generated(touchid)
+|  down    |          | Motion
+|  move    |          | Motion
+|  move    |          | Motion
+|  (np)    |   down   | TouchBegin(0), TouchBegin(1)
+|  move    |    --    | TouchUpdate(0)
+|   --     |   move   | TouchUpdate(1)
+|   up     |   (pc)   | TouchEnd(0), TouchEnd(1)
+|          |   move   | Motion
+|  down    |   (np)   | TouchBegin(2), TouchBegin(3)
+|  move    |    --    | TouchUpdate(2)
+|   up     |   (pc)   | TouchEnd(2), TouchEnd(3)
+|          |    up    | Motion
+|  down    |          | Motion
+|  (np)    |   down   | TouchBegin(4), TouchBegin(5)
+|  (pc)    |    up    | TouchEnd(4), TouchEnd(5)
+|  move    |          | Motion
+|   up     |          | Motion
+|====================================================
+
 
 [[multitouch-emulation]]
 Pointer emulation from multitouch events
-- 
1.7.7.5