[PATCH inputproto v2 3/4] XI2.1: Add confine_to to XIPassiveGrabDevice

[Peter Hutterer]

Enter and button grabs can specify an additional confine_to window to which
the pointer is confined to during the grab. If the confine_to window is not
None the grab does not activate if the confine_to window is not viewable.

Changes in protocol behaviour to XI 2.0:
XIPassiveGrabDevice may return BadWindow if the confine_to window does
not specify a valid window.

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
CC: Philipp Reh <sefi at s-e-f-i.de>
Reviewed-by: Jeremy Huddleston <jeremyhu at apple.com>
---
Changes to v1:
- allow for confine_to on slave devices

 specs/XI2proto.txt |   17 ++++++++++++++++-
 1 files changed, 16 insertions(+), 1 deletions(-)

diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index a777d9a..fdbcc72 100644
--- a/specs/XI2proto.txt
+++ b/specs/XI2proto.txt
@@ -39,7 +39,7 @@ device information in each event (with the exception of core events).
 Changes introduced by version 2.1
 
 - RawEvents are sent regardless of the grab state.
-- XIGrabDevice takes a confine_to parameter
+- XIGrabDevice and XIPassiveGrabDevice take a confine_to parameter
 
 //                            ❧❧❧❧❧❧❧❧❧❧❧
 
@@ -1047,8 +1047,11 @@ you pass to the event-mode argument:
             ▶
             num_modifiers_return:    INT16
             modifiers_return:        GRABMODIFIERINFO
+            confine_to*:     Window
     └───
 
+    * since XI 2.1
+
         GRABTYPE         { GrabtypeButton, GrabtypeKeycode, GrabtypeEnter,
                            GrabtypeFocusIn}
 
@@ -1096,6 +1099,8 @@ on the specified input device.
             Number of elements in modifiers_return
         modifiers_return
             XKB modifier state that could not be grabbed.
+        confine_to
+            The window to confine the pointer to. Can be None.
 
 If owner-events is False, input events generated from this device are
 reported with respect to grab-window, and are only reported if
@@ -1127,6 +1132,7 @@ device is actively grabbed if:
         - the grab_window contains the pointer, and
         - a passive grab on the same button/keycode + modifier
           combination does not exist on an ancestor of grab_window.
+        - the confine_to window (if any) is viewable
 
 Otherwise, if grab_type is GrabtypeEnter or GrabtypeFocusIn, the
 device is actively grabbed if:
@@ -1139,6 +1145,7 @@ device is actively grabbed if:
           grab_window or a descendant of grab_window,
         - a passive grab of the same grab_type + modifier combination does not
           does not exist on an ancestor of grab_window.
+        - the confine_to window (if any) is viewable
 
 A modifier of GrabAnyModifier is equivalent to issuing the request for
 all possible modifier combinations (including no modifiers). A client
@@ -1186,6 +1193,14 @@ grab deactivates, addional LeaveNotify events with mode
 XIPassiveUngrabNotify are generated and sent to the grabbing client
 before the grab deactivates.
 
+If the client supports XI 2.1 and the grab type is GrabtypeButton or
+GrabtypeEnter and confine_to is not None and the device is a
+master pointer device or a slave device, the device will be confined
+to that window for the duration of the grab. Reported root-relative
+coordinates are restricted to the confine_to window. If the device reports
+valuators within an axis range, the reported valuators are proportionally
+restricted to the confine_to window.
+
     ┌───
         XIPassiveUngrabDevice
             deviceid:        DEVICEID
-- 
1.7.5.1