[PATCH inputproto multitouch 9/9] Specify dependent device pointer/touch handling

[Chase Douglas]

With the added rules, trackpads should be manageable no matter what
occurs (button presses and pointer motion). Gesture and touch semantics
during these actions are not well defined, and cancelling touches cleans
up the protocol and implementation.

Signed-off-by: Chase Douglas <chase.douglas at canonical.com>
---
 XI2.h              |    2 ++
 specs/XI2proto.txt |   26 +++++++++++++++++++++++++-
 2 files changed, 27 insertions(+), 1 deletions(-)

diff --git a/XI2.h b/XI2.h
index 31257d1..f6bdbb2 100644
--- a/XI2.h
+++ b/XI2.h
@@ -157,6 +157,8 @@
 #define XIPointerEmulated                       (1 << 16)
 /* Device event flags (touch events only) */
 #define XITouchPendingEnd                       (1 << 16)
+#define XITouchCanceled                         (1 << 17)
+#define XITouchResumed                          (1 << 18)
 
 /* Touch modes */
 #define XIDirectTouch                           1
diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index 3e18820..29ab8bc 100644
--- a/specs/XI2proto.txt
+++ b/specs/XI2proto.txt
@@ -266,6 +266,14 @@ When the touch has physically ended, or a client will otherwise not receive
 any more events for a given touchpoint, a <<events-deviceevent,TouchEnd event>>
 will be sent to that client.
 
+A touch sequence may be canceled and/or resumed. When a sequence is canceled, a
+TouchEnd event is sent with the TouchCanceled flag. When a touch is resumed, a
+TouchBegin event is sent with the TouchResumed flag. Touch resumption denotes
+that touch processing has resumed; a resumed touch may never have been a
+canceled touch if the touch began while touch processing was inhibited. If a
+touch has stayed in physical contact from cancel through resume, the resumed
+touch sequence will have the same tracking ID.
+
 Passive touch grabs are similar to standard input event grabs in that they
 take precedence over event selections and are searched from the root window
 to the child window (as opposed to selections, which start their search at the
@@ -371,6 +379,21 @@ pointer. A dependent device may only have one window set at a time, for all
 touches. Any future touch sequence will use the same window set. The window set
 is cleared when all touch sequences on the device end.
 
+Button presses for buttons one, two, and three on dependent devices will cause
+the following:
+
+- All touch events from the device are canceled. New touches are inhibited from
+  beginning new touch sequences.
+- The button press is handled and delivered through normal pointer event
+  mechanisms.
+- Pointer motion events may be generated by the device.
+
+When all of the buttons have been released, any active touches will resume, and
+new touches will be allowed to begin.
+
+When a dependent device causes pointer motion, touch sequences are canceled.
+Touch sequences may resume after pointer motion ceases.
+
 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.
@@ -1929,7 +1952,8 @@ For a detailed description of classes, see the XQueryDevice request.
     DEVICEEVENTFLAGS (all events): none
     DEVICEEVENTFLAGS (key events only): { KeyRepeat }
     DEVICEEVENTFLAGS (pointer and touch events only): { PointerEmulated }
-    DEVICEEVENTFLAGS (touch events only): { TouchPendingEnd }
+    DEVICEEVENTFLAGS (touch events only): { TouchPendingEnd, TouchCanceled,
+                                            TouchResumed }
 
 An XIDeviceEvent is generated whenever the logical state of a device
 changes in response to a button press, a button release, a motion, a key
-- 
1.7.4.1