Grabbing and Ungrabbing Extension Input Devices

Grabbing Extended Input Devices

To grab a specified extension device, use XGrabDevice.

int XGrabDevice(display, device, grab_window,
owner_events, event_count, event_list, this_device_mode,
other_devices_mode, time)
      Display     *display;
      XDevice     *device;
      Window       grab_window;
      Bool         owner_events;
      int          event_count;
      XEventClass *event_list;
      int          this_device_mode, other_devices_mode;
      Time         time;

Title not available (Grabbing Extended Input Devices )

display: Specifies the connection to the X server.
device: Specifies the device to be grabbed.
grab_window: Specifies the id of a window to be associated with the device.
owner_events: Specifies a Boolean value that indicates whether the events from the device are to be reported as usual or reported with respect to the grab window if the events are selected by the event list.
event_count: Specifies the number of elements in the event_list array.
event_list: Specifies a pointer to a list of event classes that indicates which events the client wishes to receive. These event classes must have been obtained by specifying the device being grabbed.
this_device_mode: Specifies further processing of events from this device. You can pass GrabModeSync or GrabModeAsync.
other_devices_mode: Specifies further processing of events from other devices. You can pass GrabModeSync or GrabModeAsync.
time: Specifies the time. You can pass either a timestamp or CurrentTime.

The XGrabDevice function actively grabs control of the device and generates DeviceFocusIn and DeviceFocusOut events. Further device events are reported only to the grabbing client. XGrabDevice overrides any active device grab by this client. The event_list argument is a pointer to a list of event classes. This list indicates which events the client wishes to receive while the grab is active. If owner_events is False, all generated device events are reported with respect to grab_window if selected. If owner_events is True and if a generated device 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 specified in the event_list.

The this_device_mode parameter controls further processing of events from this device and the other_device_mode parameter controls the further processing of events from all other devices.

If this_device_mode is GrabModeAsync, device event processing continues as usual. If the device is currently frozen by this client, then processing of device events is resumed. If this_device_mode is GrabModeSync, the state of the device (as seen by client applications) appears to freeze, and the X server generates no further device events until the grabbing client issues a releasing XAllowDeviceEvents call or until the device grab is released. Actual device changes are not lost while the device is frozen; they are simply queued in the server for later processing.

If other_devices_mode is GrabModeAsync, processing of events from other devices is unaffected by activation of the grab. If other_devices_mode is GrabModeSync, the state of all devices except the grabbed device (as seen by client applications) appears to freeze, and the X server generates no further events from those devices until the grabbing client issues a releasing XAllowDeviceEvents call or until the device grab is released. Actual events are not lost while the devices are frozen; they are simply queued in the server for later processing.

If the device is actively grabbed by some other client, XGrabDevice fails and returns AlreadyGrabbed. If grab_window is not viewable, it fails and returns GrabNotViewable. If the device is frozen by an active grab of another client, it fails and returns GrabFrozen. If the specified time is earlier than the last-device-grab time or later than the current X server time, it fails and returns GrabInvalidTime. Otherwise, the last-device-grab time is set to the specified time (CurrentTime is replaced by the current X server time).

If a grabbed device is closed by a client while an active grab by that client is in effect, the active grab is released. If the device is frozen only by an active grab of the requesting client, it is thawed.

XGrabDevice can generate BadClass, BadDevice, BadValue, and BadWindow errors.

Ungrabbing Extended Input Devices

To ungrab a specified extension device, use XUngrabDevice.

int XUngrabDevice(display, device, time)
      Display *display;
      XDevice *device;
      Time     time;

Title not available (Ungrabbing Extended Input Devices )

display: Specifies the connection to the X server.
device: Specifies the device to be released.
time: Specifies the time. You can pass either a timestamp or CurrentTime.

The XUngrabDevice function releases the device and any queued events if this client has it actively grabbed from XGrabDevice, XGrabDeviceButton, or XGrabDeviceKey. If other devices are frozen by the grab, XUngrabDevice thaws them. XUngrabDevice does not release the device and any queued events if the specified time is earlier than the last-device-grab time or is later than the current X server time. It also generates DeviceFocusIn and DeviceFocusOut events. The X server automatically performs an UngrabDevice request if the event window for an active device grab becomes not viewable.

XUngrabDevice can generate a BadDevice error.

Grabbing Extended Input Device Buttons

To grab extension input device buttons, use XGrabDeviceButton.

int XGrabDeviceButton(display, device, button,
modifiers, modifier_device, grab_window,
owner_events, event_count, event_list,
this_device_mode, other_devices_mode)
      Display      *display;
      XDevice      *device;
      unsigned int  button;
      unsigned int  modifiers;
      XDevice      *modifier_device;
      Window        grab_window;
      Bool          owner_events;
      unsigned int  event_count;
      XEventClass  *event_list;
      int           this_device_mode, other_devices_mode;

Title not available (Grabbing Extended Input Device Buttons )

display: Specifies the connection to the X server.
device: Specifies the device that is to be grabbed.
button: Specifies the device button that is to be grabbed or AnyButton.
modifiers: Specifies the set of keymasks or AnyModifier. The mask is the bitwise inclusive OR of the valid keymask bits. Valid bits are: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask.
modifier_device: Specifies the device whose modifiers are to be used. If NULL is specified, the X keyboard will be used as the modifier device.
grab_window: Specifies the grab window.
owner_events: Specifies a Boolean value that indicates whether the device events are to be reported as usual or reported with respect to the grab window if selected by the event list.
event_count: Specifies the number of event classes in the event list.
event_list: Specifies which events are reported to the client.
this_device_mode: Specifies further processing of events from this device. You can pass GrabModeSync or GrabModeAsync.
other_devices_mode: Specifies further processing of events from all other devices. You can pass GrabModeSync or GrabModeAsync.

The XGrabDeviceButton function establishes a passive grab. When the specified button is pressed, the device is actively grabbed (as for XGrabDevice), the last-grab time is set to the time at which the button was pressed (as transmitted in the DeviceButtonPress event), and the DeviceButtonPress event is reported if all the following conditions are true:

The device is not grabbed, and the specified button is logically pressed when the specified modifier keys are logically down on the specified modifier device, and no other buttons or modifier keys are logically down.
Either the grab window is an ancestor of (or is) the focus window, or the grab window is a descendent of the focus window and contains the device.
A passive grab on the same button modifier combination does not exist on any ancestor of grab_window.

The interpretation of the remaining arguments is as for XGrabDevice. The active grab is terminated automatically when the logical state of the device has all buttons released (independent of the logical state of the modifier keys).

Note that the logical state of a device (as seen by client applications) may lag the physical state if device event processing is frozen.

This request overrides all previous grabs by the same client on the same button modifier combinations on the same window. A modifiers of AnyModifier is equivalent to issuing the grab request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned KeyCodes. A button of AnyButton is equivalent to issuing the request for all possible buttons. Otherwise, it is not required that the specified button currently be assigned to a physical button.

If some other client has already issued a XGrabDeviceButton with the same button modifier combination on the same window, a BadAccess error results. If AnyModifier was specified for the modifiers argument or AnyButton for the key argument, the request fails completely, and a BadAccess error results (no grabs are established), if there is a conflicting grab for any combination. XGrabDeviceButton has no effect on an active grab.

XGrabDeviceButton can generate BadClass, BadDevice, BadMatch, BadValue, and BadWindow errors.

Ungrabbing Extended Input Device Buttons

To ungrab an extended input device button, use XUngrabDeviceButton.

int XUngrabDeviceButton(display, device, button,
modifiers, modifier_device, grab_window)
      Display     *display;
      XDevice     *device;
      unsigned int button;
      unsigned int modifiers;
      XDevice     *modifier_device;
      Window       grab_window;

Title not available (Ungrabbing Extended Input Device Buttons )

display: Specifies the connection to the X server.
device: Specifies the device that is to be released.
button: Specifies the device button that is to be released or AnyButton.
modifiers: Specifies the set of keymasks or AnyModifier. The mask is the bitwise inclusive OR of the valid keymask bits. Valid bits are: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.
modifier_device: Specifies the device whose modifiers are to be used. If NULL is specified, the X keyboard will be used as the modifier device.
grab_window: Specifies the grab window.

The XUngrabDeviceButton function releases the passive grab for a button modifier combination on the specified window if it was grabbed by this client. A modifiers of AnyModifier is equivalent to issuing the ungrab request for all possible modifier combinations, including the combination of no modifiers. A button of AnyButton is equivalent to issuing the request for all possible buttons. XUngrabDeviceButton has no effect on an active grab.

XUngrabDeviceButton can generate BadDevice, BadMatch, BadValue, and BadWindow errors.

Grabbing Extended Input Device Keys

To grab an extension input device key, use XGrabDeviceKey.

XGrabDeviceKey(display, device, key, modifiers,
modifier_device, grab_window, owner_events, event_count,
event_list, this_device_mode, other_devices_mode)
      Display     *display;
      XDevice     *device;
      unsigned int key;
      unsigned int modifiers;
      XDevice     *modifier_device;
      Window       grab_window;
      Bool         owner_events;
      unsigned int event_count;
      XEventClass  event_list;
      int          this_device_mode, other_devices_mode;

Title not available (Grabbing Extended Input Device Keys )

display: Specifies the connection to the X server.
device: Specifies the device that is to be grabbed.
key: Specifies the device key that is to be grabbed or AnyKey.
modifiers: Specifies the set of keymasks or AnyModifier. The mask is the bitwise inclusive OR of the valid keymask bits.
modifier_device: Specifies the device whose modifiers are to be used. If NULL is specified, the X keyboard will be used as the modifier device.
grab_window: Specifies the grab window.
owner_events: Specifies a Boolean value that indicates whether the device events are to be reported as usual or reported with respect to the grab window if selected by the event list.
event_count: Specifies the number of event classes in the event list.
event_list: Specifies which device events are reported to the client.
this_device_mode: Specifies further processing of events from this device. You can pass GrabModeSync or GrabModeAsync.
other_devices_mode: Specifies further processing of events from other devices. You can pass GrabModeSync or GrabModeAsync.

The XGrabDeviceKey function establishes a passive grab. In the future, the device is actively grabbed (as for XGrabDevice), the last-device-grab time is set to the time at which the Key was pressed (as transmitted in the DeviceKeyPress event), and the DeviceKeyPress event is reported if all the following conditions are true:

The device is not grabbed, and the specified key is logically pressed when the specified modifier keys are logically down, and no other keys or modifier keys are logically down.
The grab_window is an ancestor of (or is) the focus window, or the grab_window is a descendent of the focus window and contains the device.
A passive grab on the same key/modifier combination does not exist on any ancestor of grab_window.

The interpretation of the remaining arguments is as for XGrabDevice. The active grab is terminated automatically when the logical state of the device has the specified keys released.

Note that the logical state of a device (as seen by means of the X protocol) may lag the physical state if device event processing is frozen.

If the key is not AnyKey, it must be in the range specified by min_keycode and max_keycode as returned by the XListInputDevices function. Otherwise, a BadValue error will result.

This request overrides all previous grabs by the same client on the same key modifier combinations on the same window. A modifiers of AnyModifier is equivalent to issuing the grab request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned KeyCodes. A key of AnyKey is equivalent to issuing the request for all possible keys. Otherwise, it is not required that the specified key currently be assigned to a physical key.

If some other client has already issued a XGrabDeviceKey with the same key modifier combination on the same window, a BadAccess error results. When using AnyModifier or AnyKey, the request fails completely, and a BadAccess error results (no grabs are established) if there is a conflicting grab for any combination. XGrabDeviceKey has no effect on an active grab.

XGrabDeviceKey can generate BadAccess, BadClass, BadDevice, BadMatch, BadValue, and BadWindow errors. It returns Success on successful completion of the request.

Ungrabbing Extended Input Device Keys

To ungrab an extended input device key, use XUngrabDeviceKey.

XUngrabDeviceKey(display, device, key, modifiers,
modifier_device, grab_window)
      Display     *display;
      XDevice     *device;
      unsigned int key;
      unsigned int modifiers;
      XDevice     *modifier_device;
      Window       grab_window;

Title not available (Ungrabbing Extended Input Device Keys )

display: Specifies the connection to the X server.
device: Specifies the device that is to be released.
key: Specifies the device key that is to be released or AnyKey.
modifiers: Specifies the set of keymasks or AnyModifier. The mask is the bitwise inclusive OR of the valid keymask bits. Valid bits are: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask.
modifier_device: Specifies the device whose modifiers are to be used. If NULL is specified, the X keyboard will be used as the modifier device.
grab_window: Specifies the grab window.

The XUngrabDeviceKey function releases the passive key/modifier combination on the specified window if it was grabbed by this client. A modifier of AnyModifier is equivalent to issuing the ungrab request for all possible modifier combinations, including the combination of no modifiers. A key of AnyKey is equivalent to issuing the request for all possible keys. XUngrabDeviceKey has no effect on an active grab.

XUngrabDeviceKey can generate BadDevice, BadMatch, BadValue, and BadWindow errors.

Releasing Queued Events

To release queued events, use XAllowDeviceEvents.

int XAllowDeviceEvents(display, device, event_mode, time)
      Display *display;
      XDevice *device;
      int      event_mode;
      Time     time;

Title not available (Releasing Queued Events )

display: Specifies the connection to the X server.
device: Specifies the device from which events are to be allowed.
event_mode: Specifies the event mode. You can pass AsyncThisDevice, SyncThisDevice, ReplayThisDevice, AsyncOtherDevices, SyncAllDevices, or AsyncAllDevices.
time: Specifies the time. You can pass either a timestamp or CurrentTime.

The XAllowDeviceEvents function releases some queued events if the client has caused a device to freeze. It has no effect if the specified time is earlier than the last-grab time of the most recent active grab for the client and device, or if the specified time is later than the current X server time.

The event modes are defined as follows:

Title not available (Releasing Queued Events )

AsyncThisDevice: If the specified device is frozen by the client, event processing for that device continues as usual. If the device is frozen multiple times by the client on behalf of multiple separate grabs, AsyncThisDevice thaws for all. AsyncThisDevice has no effect if the specified device is not frozen by the client.
SyncThisDevice: If the specified device is frozen and actively grabbed by the client, event processing for that device continues normally until the next key or button event is reported to the client. Then the specified device appears to freeze unless the reported event causes the grab to be released. SyncThisDevice has no effect if the specified device is not frozen or grabbed by the client.
ReplayThisDevice: If the specified device is actively grabbed by the client and is frozen as the result of an event having been sent to the client, the grab is released and that event is completely reprocessed. This time, however, the request ignores any passive grabs at or above the grab-window of the grab just released. The request has no effect if the specified device is not grabbed by the client or if it is not frozen as a result of an event.
AsyncOtherDevices: If the remaining devices are frozen by the client, event processing for them continues as usual. If the other devices are frozen multiple times by the client of behalf of multiple separate grabs, AsyncOtherDevices thaws for all. AsyncOtherDevices has no effect if the devices are not frozen by the client.
SyncAllDevices: If all the devices are frozen by the client, event processing for all the devices continues normally until the next button or key event is reported to the client for a grabbed device. Then the devices appear to freeze unless the reported event causes the grab to be released. If any device is still grabbed, then a subsequent event for it will still cause all the devices to freeze. SyncAllDevices has no effect unless all the devices are frozen by the client. If any device is frozen twice by the client on behalf of two separate grabs, SyncAllDevices thaws for both. A subsequent freeze for SyncAllDevices will only freeze each device once.
AsyncAllDevices: If all devices are frozen by the client, event processing for all devices continues normally. If any device is frozen multiple times by the client on behalf of multiple separate grabs, AsyncAllDevices thaws for all. AsyncAllDevices has no effect unless all devices are frozen by the client.

AsyncThisDevice, SyncThisDevice, and ReplayThisDevice have no effect on the processing of events from the remaining devices. AsyncOtherDevices has no effect on the processing of events from the specified device. When the event_mode is SyncAllDevices or AsyncAllDevices, the device parameter is ignored.

It is possible for several grabs of different devices by the same or different clients to be active simultaneously. If a device is frozen on behalf of any grab, no event processing is performed for that device. It is possible for a single device to be frozen because of several grabs. In that case, the freeze must be released on behalf or each grab before events can again be processed.

XAllowDeviceEvents can generate a BadDevice or BadValue error.