man/XGrabDevice.txt

   1 XGRABDEVICE(libmansuffix)
   2 =========================
   3
   4 NAME
   5 ----
   6
   7    XGrabDevice, XUngrabDevice - grab/release the specified
   8    extension device
   9
  10 SYNOPSIS
  11 --------
  12
  13    #include <X11/extensions/XInput.h>
  14
  15    int XGrabDevice( Display *display,
  16                     XDevice* device,
  17                     Window grab_window,
  18                     Bool owner_events,
  19                     int event_count,
  20                     XEventClass *event_list,
  21                     int this_device_mode,
  22                     int other_devices_mode,
  23                     Time time);
  24
  25    int XUngrabDevice( Display *display,
  26                       XDevice *device,
  27                       Time time);
  28
  29    display
  30           Specifies the connection to the X server.
  31
  32    device
  33           Specifies the device to be grabbed or released.
  34
  35    grab_window
  36           Specifies the id of a window to be associated with the
  37           device.
  38
  39    owner_events
  40           Specifies a Boolean value that indicates whether
  41           theevents from the deviceare to be reported as usual or
  42           reported with respect to the grab windowif selected by
  43           the event list.
  44
  45    event_count
  46           Specifies the number of elements in the event_list
  47           array.
  48
  49    event_list
  50           Specifies a pointer to a list of event classes that
  51           indicates which eventsthe client wishes to receive.
  52           These event classes must have beenobtained specifying
  53           the device being grabbed.
  54
  55    this_device_mode
  56           Specifies further processing of events from this
  57           device.You can pass GrabModeSyncor GrabModeAsync.
  58
  59    other_devices_mode
  60           Specifies further processing of events from other
  61           devices.You can pass GrabModeSyncor GrabModeAsync.
  62
  63    time
  64           Specifies the time.You can pass either a timestamp or
  65           CurrentTime.
  66
  67 DESCRIPTION
  68 -----------
  69
  70    The XGrabDevice request actively grabs control of the device
  71    and generates DeviceFocusIn and DeviceFocusOut events. Further
  72    device events are reported only to the grabbing
  73    client.XGrabDevice overrides any active device grab by this
  74    client. event_list is a pointer to a list of event classes.
  75    This list indicates which events the client wishes to receive
  76    while the grab is active. If owner_events is False, all
  77    generated device events are reported with respect to
  78    grab_window if selected. If owner_events is True and if a
  79    generated device event would normally be reported to this
  80    client, it is reported normally; otherwise, the event is
  81    reported with respect to the grab_window, and is only reported
  82    if specified in the event_list.
  83
  84    If the this_device_mode argument is GrabModeAsync, device event
  85    processing continues as usual. If the device is currently
  86    frozen by this client, then processing of device events is
  87    resumed. If the this_device_mode argument is GrabModeSync, the
  88    state of the device (as seen by client applications) appears to
  89    freeze, and the X server generates no further device events
  90    until the grabbing client issues a releasing XAllowDeviceEvents
  91    call or until the device grab is released. Actual device
  92    changes are not lost while the device is frozen; they are
  93    simply queued in the server for later processing.
  94
  95    If other_devices_mode is GrabModeAsync, processing of events
  96    from other devices is unaffected by activation of the grab. If
  97    other_devices_mode is GrabModeSync, the state of all devices
  98    except the grabbed device (as seen by client applications)
  99    appears to freeze, and the X server generates no further events
 100    from those devices until the grabbing client issues a releasing
 101    XAllowDeviceEvents call or until the device grab is released.
 102    Actual events are not lost while the devices are frozen; they
 103    are simply queued in the server for later processing.
 104
 105    If the device is actively grabbed by some other client,
 106    XGrabDevice fails and returns AlreadyGrabbed. If grab_window is
 107    not viewable, it fails and returns GrabNotViewable. If the
 108    device is frozen by an active grab of another client, it fails
 109    and returns GrabFrozen. If the specified time is earlier than
 110    the last-device-grab time or later than the current X server
 111    time, it fails and returns GrabInvalidTime. Otherwise, the
 112    last-device-grab time is set to the specified time (
 113    CurrentTime is replaced by the current X server time).
 114
 115    If a grabbed device is closed by a client while an active grab
 116    by that client is in effect, the active grab is released. If
 117    the device is frozen only by an active grab of the requesting
 118    client, it is thawed.
 119
 120    XGrabDevice can generate BadClass, BadDevice, BadValue, and
 121    BadWindow errors.
 122
 123    The XUngrabDevice request releases the device and any queued
 124    events if this client has it actively grabbed from either
 125    XGrabDevice or XGrabDeviceKey. If other devices are frozen by
 126    the grab, XUngrabDevice thaws them.XUngrabDevice does not
 127    release the device and any queued events if the specified time
 128    is earlier than the last-device-grab time or is later than the
 129    current X server time. It also generates DeviceFocusIn and
 130    DeviceFocusOut events. The X server automatically performs an
 131    UngrabDevice request if the event window for an active device
 132    grab becomes not viewable.
 133
 134    XUngrabDevice can generate a BadDevice error.
 135
 136 DIAGNOSTICS
 137 -----------
 138
 139    BadDevice
 140           An invalid device was specified. The specified device
 141           does not exist or has not been opened by this client via
 142           XOpenInputDevice. This error may also occur if the
 143           specified device is the X keyboard or X pointer device.
 144
 145    BadValue
 146           Some numeric value falls outside the range of values
 147           accepted by the request. Unless a specific range is
 148           specified for an argument, the full range defined by the
 149           argument's type is accepted. Any argument defined as a
 150           set of alternatives can generate this error.
 151
 152    BadWindow
 153           A value for a Window argument does not name a defined
 154           Window.
 155
 156 SEE ALSO
 157 --------
 158
 159    XAllowDeviceEvents(libmansuffix), XGrabDeviceButton(libmansuffix), XGrabDeviceKey(libmansuffix)