[PATCH inputproto multitouch v2] Allow grabbing clients to accept or reject touches any time

[Chase Douglas]

This is potentially both a performance and client complexity
improvement. An example is a gesture recognizer using touch grabs on
each window with a subscription. If events on a child window is known
to not match any subscription on the child window, then the client
should be able to reject the touch grab even if the parent window hasn't
accepted any of the touches, perhaps because the parent window
gesture hasn't timed out or crossed other thresholds yet.

As an inverse example, the events may match a child window subscription
before the root window has rejected ownership. The child window should
be able to accept the touch proactively. This allows for further clients
to receive a TouchEnd event earlier, and means the client may be able to
reduce state being tracked. If this were not allowed, the client would
need to wait until it received ownership before accepting the sequence.

Signed-off-by: Chase Douglas <chase.douglas at canonical.com>
---
 XI2proto.h         |    3 ++-
 specs/XI2proto.txt |   28 ++++++++++++++++++----------
 2 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/XI2proto.h b/XI2proto.h
index 3315f1e..9e2c63c 100644
--- a/XI2proto.h
+++ b/XI2proto.h
@@ -648,8 +648,9 @@ typedef struct {
     uint8_t     mode;
     uint8_t     pad;
     uint32_t    touch_id;               /**< Since XI 2.2 */
+    Window      grab_window;            /**< Since XI 2.2 */
 } xXIAllowEventsReq;
-#define sz_xXIAllowEventsReq                   16 /**< Was 12 before XI 2.2 */
+#define sz_xXIAllowEventsReq                   20 /**< Was 12 before XI 2.2 */
 
 
 /**
diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index 9bd586a..dfc80cc 100644
--- a/specs/XI2proto.txt
+++ b/specs/XI2proto.txt
@@ -1373,6 +1373,7 @@ active device grab becomes not viewable.
                                ReplayDevice, AsyncPair, SyncPair, AcceptTouch*,
                                RejectTouch* }
             touch_id*:       CARD32
+            grab_window*:    Window
     └───
 
 * since XI 2.2
@@ -1391,13 +1392,17 @@ ownership processing.
     touch_id
         The ID of the touch sequence to accept or reject. The value is undefined
         for event modes other than AcceptTouch and RejectTouch.
+    grab_window
+        The window on which to accept or reject a touch sequence grab. The value
+        is undefined for event modes other than AcceptTouch and RejectTouch.
 
-The request has no effect if the specified time is earlier than the
-last-grab time of the most recent active grab for the client, or if the
-specified time is later than the current X server time.
+For event modes other than AcceptTouch and RejectTouch, the request has no
+effect if the specified time is earlier than the last-grab time of the most
+recent active grab for the client, or if the specified time is later than the
+current X server time.
 
-When event-mode is AcceptTouch or RejectTouch, a BadValue error occurs if the
-touch ID is invalid. A BadAccess error occurs if this client is not the current
+When event-mode is AcceptTouch, a BadValue error occurs if the touch ID is
+invalid. A BadAccess error occurs if this client is not the current or potential
 owner of the specified touch ID.
 
 The following describes the processing that occurs depending on what constant
@@ -1470,13 +1475,16 @@ you pass to the event-mode argument:
         paired master device frozen by the client.
         AsyncPair has no effect if deviceid specifies a slave device.
      AcceptTouch
-        The client is deemed to have taken control of the touch sequence.
-        TouchEnd events will be sent to all other clients listening to the touch
-        sequence, and they will no longer receive any TouchUpdate events.
+        The client is deemed to have taken control of the touch sequence once it
+        owns the sequence. TouchEnd events will be sent to all clients listening
+        to the touch sequence that have either grabbed the touch sequence on a
+        child window of the grab_window or have received events for the touch
+        sequence through event selection. These clients will no longer receive
+        any TouchUpdate events.
      RejectTouch
         The client is no longer interested in the touch sequence, and will
-        receive a TouchEnd event. Ownership will be passed on to the next
-        listener.
+        receive a TouchEnd event. If the client is the current owner of the
+        sequence, ownership will be passed on to the next listener.
 
 [[requests-passivegrabdevice]]
     ┌───
-- 
1.7.4.1