XAllowDeviceEvents.txt revision c27c18e8 
1XALLOWDEVICEEVENTS(libmansuffix)
2================================
3
4NAME
5----
6
7   XAllowDeviceEvents - release queued events
8
9SYNOPSIS
10------
11
12   #include <X11/extensions/XInput.h>
13
14   int XAllowDeviceEvents( Display *display,
15                           XDevice *device,
16                           int event_mode,
17                           Time time);
18   display
19          Specifies the connection to the X server.
20
21   device
22          Specifies the device from which events are to be
23          allowed.
24
25   event_mode
26          Specifies the event mode.You can pass AsyncThisDevice,
27          SyncThisDevice, ReplayThisDevice, AsyncOtherDevices,
28          SyncAll,or AsyncAll.
29
30   time
31          Specifies the time.You can pass either a timestamp or
32          CurrentTime.
33
34DESCRIPTION
35-----------
36
37   The XAllowDeviceEvents function releases some queued events if
38   the client has caused a device to freeze. It has no effect if
39   the specified time is earlier than the last-grab time of the
40   most recent active grab for the client and device, or if the
41   specified time is later than the current X server time.
42
43   The following describes the processing that occurs depending on
44   what constant you pass to the event_mode argument.
45
46   AsyncThisDevice If the specified device is frozen by the
47   client, event processing for that device continues as usual. If
48   the device is frozen multiple times by the client on behalf of
49   multiple separate grabs, AsyncThisDevice thaws for
50   all.AsyncThisDevice has no effect if the specified device is
51   not frozen by the client, but the device need not be grabbed by
52   the client.
53
54   SyncThisDevice If the specified device is frozen and actively
55   grabbed by the client, event processing for that device
56   continues normally until the next key or button event is
57   reported to the client. At this time, the specified device
58   again appears to freeze. However, if the reported event causes
59   the grab to be released, the specified device does not freeze.
60   SyncThisDevice has no effect if the specified device is not
61   frozen by the client or is not grabbed by the client.
62
63   ReplayThisDevice If the specified device is actively grabbed by
64   the client and is frozen as the result of an event having been
65   sent to the client (either from the activation of a
66   GrabDeviceButton or from a previous AllowDeviceEvents with mode
67   SyncThisDevice, but not from a GrabDevice), the grab is
68   released and that event is completely reprocessed. This time,
69   however, the request ignores any passive grabs at or above
70   (toward the root) that the grab-window of the grab just
71   released. The request has no effect if the specified device is
72   not grabbed by the client or if it is not frozen as the result
73   of an event.
74
75   AsyncOtherDevices If the remaining devices are frozen by the
76   client, event processing for them continues as usual. If the
77   other devices are frozen multiple times by the client on behalf
78   of multiple grabs, AsyncOtherDevices "thaws" for all.
79   AsyncOtherDevices has no effect if the devices are not frozen
80   by the client.
81
82   SyncAll If all devices are frozen by the client, event
83   processing (for all devices) continues normally until the next
84   button or key event is reported to the client for a grabbed
85   device, at which time all devices again appear to freeze.
86   However, if the reported event causes the grab to be released,
87   then the devices do not freeze. If any device is still grabbed,
88   then a subsequent event for it will still cause all devices to
89   freeze. SyncAll has no effect unless all devices are frozen by
90   the client. If any device is frozen twice by the client on
91   behalf of two separate grabs, SyncAll thaws for both. A
92   subsequent freeze for SyncAll will only freeze each device
93   once.
94
95   AsyncAll If all devices are frozen by the client, event
96   processing for all devices continues normally. If any device is
97   frozen multiple times by the client on behalf of multiple
98   separate grabs, AsyncAll thaws for all. AsyncAll has no effect
99   unless all devices are frozen by the client.
100
101   AsyncThisDevice, SyncThisDevice, and ReplayThisDevice have no
102   effect on the processing of events from the remaining
103   devices.AsyncOtherDevices has no effect on the processing of
104   events from the specified device. When the event_mode is
105   SyncAll or AsyncAll, the device parameter is ignored.
106
107   It is possible for several grabs of different devices by the
108   same or different clients to be active simultaneously. If a
109   device is frozen on behalf of any grab, no event processing is
110   performed for the device. It is possible for a single device to
111   be frozen because of several grabs. In this case, the freeze
112   must be released on behalf of each grab before events can again
113   be processed.
114
115   XAllowDeviceEvents can generate a BadDevice or BadValue error.
116
117DIAGNOSTICS
118-------------
119
120   BadDevice
121          An invalid device was specified. The specified device
122          does not exist or has not been opened by this client via
123          XOpenInputDevice. This error may also occur if the
124          specified device is the X keyboard or X pointer device.
125
126   BadValue
127          An invalid mode was specified on the request.
128
129SEE ALSO
130--------
131
132   XGrabDevice(libmansuffix)
133
134