1XGRABDEVICE(libmansuffix)
2=========================
3
4NAME
5----
6
7   XGrabDevice, XUngrabDevice - grab/release the specified
8   extension device
9
10SYNOPSIS
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          the events from the device are to be reported as usual or
42          reported with respect to the grab window if 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 events the client wishes to receive.
52          These event classes must have been obtained specifying
53          the device being grabbed.
54
55   this_device_mode
56          Specifies further processing of events from this
57          device. You can pass GrabModeSync or GrabModeAsync.
58
59   other_devices_mode
60          Specifies further processing of events from other
61          devices. You can pass GrabModeSync or GrabModeAsync.
62
63   time
64          Specifies the time. You can pass either a timestamp or
65          CurrentTime.
66
67DESCRIPTION
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
136DIAGNOSTICS
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
156SEE ALSO
157--------
158
159   XAllowDeviceEvents(libmansuffix), XGrabDeviceButton(libmansuffix), XGrabDeviceKey(libmansuffix)
160