XI2: add passive grabs.

Most notably XI2 provides keysym grabs instead of keycode grabs.

1 files changed, 128 insertions, 0 deletions

diff --git a/XI2proto.txt b/XI2proto.txt
index 38a3a5d..903ebe7 100644
--- a/XI2proto.txt
+++ b/XI2proto.txt
@@ -828,6 +828,134 @@ XI2. Clients should ignore this data.
         paired master device frozen by the client.
         AsyncPair has no effect if deviceid specifies a slave device.
 
+    ┌───
+        XIPassiveGrabDevice
+            deviceid:        DEVICEID
+            detail:          CARD32
+            grab_type:       { GrabtypeButton, GrabtypeKeysym }
+            grab_window:     Window
+            cursor:          Cursor
+            owner_events:    Bool
+            grab_mode:       { Synchronous, Asynchronous }
+            paired_device_mode: { Synchronous, Asynchronous }
+            num_modifiers:   INT16
+            mask_len:        CARD16
+            masks:           SETofEVENTMASK
+            modifiers:       CARD32 or GrabAnyModifier
+            ▶
+            num_modifiers_return:    INT16
+            modifiers_return:        GRABMODIFIERINFO
+    └───
+
+        GRABMODIFIERINFO {   status:    Access
+                             modifiers: CARD32 }
+
+        Establish an explicit passive grab for a button or keycode or keysym
+        on the specified input device.
+
+        cursor
+            The cursor to display for the duration of the grab. If grab_type
+            is not GrabtypeButton, this argument is ignored.
+        deviceid
+            The device to establish the passive grab on.
+        detail
+            The button number, or key symbol to grab for.
+        grab_type
+            The type of grab to establish.
+        grab_window
+            Events are reported relative to the grab window.
+        grab_mode
+            If grab-mode is Asynchronous, device event processing continues
+            normally.  If the device is currently frozen by this client, then
+            processing of device events is resumed. If grab-mode is
+            Synchronous, the state of the grabbed device (as seen by means of
+            the protocol) appears to freeze, and no further device events are
+            generated by the server until the grabbing client issues a
+            releasing XIAllowEvents request or until the device grab is
+            released. Actual device input events are not lost while the device
+            is frozen; they are simply queued for later processing.
+        mask_len
+            Length of mask in 4 byte units.
+        mask
+            Event mask. An event mask for an event type T is defined as (1 << T).
+        modifiers
+            XKB modifier state to activate this passive grab.
+        num_modifiers
+            Number of elements in modifiers.
+        owner_events
+            Specifies whether event will be reported normally or relative to the
+            grab window.
+        num_modifiers_return
+            Number of elements in modifiers_return
+        modifiers_return
+            XKB modifier state that could not be grabbed.
+
+        If owner-events is False, input events generated from this device are
+        reported with respect to grab-window, and are only reported if
+        selected by being included in the event-list.  If owner-events is
+        True, then if a generated event would normally be reported to this
+        client, it is reported normally, otherwise the event is reported
+        with respect to the grab-window, and is only reported if selected
+        by being included in the event-list. For either value of
+        owner-events, unreported events are discarded.
+
+        In the future, the device is actively grabbed if:
+        - the device is not grabbed, and
+        - the specified modifier keys are down, and
+        - the grab_type is GrabtypeButton and the button specified in detail
+          is logically pressed or the grab_type is GrabtypeKeysym and the
+          keysym specified in detail is logically pressed, and
+        - the grab_window contains the pointer, and
+        - a passive grab on the same button/keycode/keysym + modifier
+          combination does not exist on an ancestor of grab_window.
+
+        A modifier of GrabAnyModifier is equivalent to issuing the request for
+        all possible modifier combinations (including no modifiers). A client
+        may request a grab for GrabAnyModifier and explicit modifier
+        combinations in the same request.
+
+        The grab is released when all buttons or keycodes or keysyms are
+        released, independent of the state of modifier keys. Note that the
+        logical state of a device (as seen by means of the protocol) may lag
+        the physical state if device event processing is frozen.
+        This request overrides all previous passive grabs by the same client
+        on the same button/key combinations on the same window.
+
+        If some other client already has issued a XIPassiveGrabDevice request
+        with the same button/keycode/keysym and modifier combination, the
+        failed modifier combinations is returned in modifiers_return. If
+        num_modifiers_return is zero, all passive grabs have been successful.
+
+    ┌───
+        XIPassiveUngrabDevice
+            deviceid:        DEVICEID
+            detail:          CARD32
+            grab_type:       { ButtonGrab, KeycodeGrab, KeysymGrab }
+            grab_window:     Window
+            num_modifiers:   INT16
+            modifiers:       MODIFIERINFO
+    └───
+
+        Release an explicit passive grab for a button or keycode or keysym on
+        the specified input device.
+
+        deviceid
+            The device to establish the passive grab on.
+        detail
+            The button number or key symbol to ungrab.
+        grab_type
+            The type of grab to establish.
+        grab_window
+            Events are reported relative to the grab window.
+        modifiers
+            XKB modifier state to activate this passive grab.
+        num_modifiers
+            Number of elements in modifiers.
+
+        This request has no effect if the matching button/keycode/keysym and
+        modifier combination is not grabbed b this client.
+
+
 8. Events:
 
 An event specifies its length in 4-byte units after the initial 32 bytes.