[PATCH inputproto 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>
---
 specs/XI2proto.txt |   14 +++++++++++++-
 1 files changed, 13 insertions(+), 1 deletions(-)

diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index 31c2647..4437d0e 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
 
 //                            ❧❧❧❧❧❧❧❧❧❧❧
 
@@ -1043,8 +1043,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}
 
@@ -1092,6 +1095,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
@@ -1123,6 +1128,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:
@@ -1135,6 +1141,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
@@ -1182,6 +1189,11 @@ 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 and confine_to is not None and the device is a
+master pointer device, the cursor will be confined to that window
+for the duration of the grab.
+
     ┌───
         XIPassiveUngrabDevice
             deviceid:        DEVICEID
-- 
1.7.5.1