[PATCH inputproto v2 2/4] XI2.1: Add confine_to to XIGrabDevice.

[Peter Hutterer]

From: Philipp Reh <sefi at s-e-f-i.de>

Updated the specs for XIGrabDevice which now
sends an additional confine_to parameter after the mask.

The confine_to behaviour is the same as the core event behaviour: if the
device is a pointer, the confine_to window determines the window the
cursor is confined to during the grab.

Changes in protocol behaviour to XI 2.0:
XIGrabDevice may return NotViewable if the confine_to is not viewable.

Signed-off-by: Philipp Reh <sefi at s-e-f-i.de>
Reviewed-by: Peter Hutterer <peter.hutterer at who-t.net>
Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
Reviewed-by: Jeremy Huddleston <jeremyhu at apple.com>
---
Changes to v1:
- slave devices can have confine_to as well. add the documentation

I've thought about the valuator range confinement and IMO we should just
leave it at the current behaviour which proportionally clips it into the
confine_to range. XI2 valuators are mainly there to give high precision data
to the clients and if the pointer is confined, this data is confined too.
Sending non-confined valuator ranges during a confine grab would put the
burden of mapping the ranges into the confine_to dimensions on the client.

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

diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt
index 5abf9d4..a777d9a 100644
--- a/specs/XI2proto.txt
+++ b/specs/XI2proto.txt
@@ -39,6 +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
 
 //                            ❧❧❧❧❧❧❧❧❧❧❧
 
@@ -822,10 +823,13 @@ Return the current focus window for the given device.
             cursor:          Cursor
             mask_len:        CARD16
             masks:           SETofEVENTMASK
+            confine_to*:     Window
             ▶
             status:          Success, AlreadyGrabbed, Frozen, InvalidTime, NotViewable
     └───
 
+    * since XI 2.1
+
 This request actively grabs control of the specified input device. Further
 input events from this device are reported only to the grabbing client.
 This request overides any previous active grab by this client for this
@@ -851,6 +855,8 @@ device.
         Length of mask in 4 byte units.
     mask
         Event mask. An event mask for an event type T is defined as (1 << T).
+    confine_to
+        The window to confine the pointer to. Can be None.
     status
         Success or the reason why the grab could not be established.
 
@@ -887,10 +893,18 @@ devices are frozen; they are simply queued for later processing.
 If the cursor is not None and the device is a master pointer device, the
 cursor will be displayed until the device is ungrabbed.
 
+If the client supports XI 2.1 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. 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.
+
 This request fails and returns:
 
     AlreadyGrabbed: If the device is actively grabbed by some other client.
-    NotViewable: If grab-window is not viewable.
+    NotViewable: If grab-window or the confine_to window (if any) is not
+                 viewable.
     InvalidTime: If the specified time is earlier than the last-grab-time for
                  the specified device or later than the current X server time.
                  Otherwise, the last-grab-time for the specified device is set
-- 
1.7.5.1