1XIALLOWEVENTS(libmansuffix)
2===========================
3
4NAME
5----
6
7   XIAllowEvents - Release queued events
8
9SYNOPSIS
10--------
11
12    #include <X11/extensions/XInput2.h>
13
14    Status XIAllowEvents( Display *display,
15                          int deviceid,
16                          int event_mode,
17                          Time time );
18
19    Status XIAllowTouchEvents( Display *dpy,
20                               int deviceid,
21                               unsigned int touchid,
22                               Window grab_window,
23                               int event_mode );
24
25    display
26            Specifies the connection to the X server.
27
28    device
29            Specifies the device that is to be grabbed or released
30
31    event_mode
32            Specifies whether a device is to be thawed and events are to be
33            replayed, or how to handle a grabbed touch sequence.
34
35    time
36            A valid server time or CurrentTime.
37
38    touchid
39            The ID of the touch sequence to accept or reject. The value is ignored
40            for event modes other than AcceptTouch and RejectTouch.
41
42    grab_window
43            The window on which to accept or reject a touch sequence grab. The value
44            is ignored for event modes other than AcceptTouch and RejectTouch.
45
46DESCRIPTION
47-----------
48
49    The XIAllowEvents request releases some queued events if the client
50    has caused a device to freeze. It also is used to handle touch grab and
51    ownership processing.
52
53    The function has no effect if the specified time is earlier than the last-grab
54    time of the most recent active grab for the client, or if the specified time is
55    later than the current X server time. The time parameter must be CurrentTime for
56    requests with event modes of XIAcceptTouch and XIRejectTouch.
57
58    The following describes the processing that occurs depending on what constant
59    you pass to the event_mode argument:
60
61        XIAsyncDevice:
62            If the specified device is frozen by the client, event processing for that
63            device continues as usual. If the device is frozen multiple times by the
64            client on behalf of multiple separate grabs, XIAsyncDevice thaws for
65            all. XIAsyncDevice has no effect if the specified device is not frozen
66            by the client, but the device need not be grabbed by the client.
67
68        XISyncDevice:
69            If the specified device is frozen and actively grabbed by the client,
70            event processing for that device continues normally until the next
71            button press or release, or key press or release, or a gesture begin or end
72            event (depending on the grab) is reported to the client.
73            At this time, the specified device again appears to freeze.
74            However, if the reported event causes the grab to be released, the
75            specified device does not freeze.
76            XISyncDevice has no effect if the specified device is not frozen by the
77            client or is not grabbed by the client.
78
79        XIReplayDevice:
80            If the specified device is actively grabbed by the client and is frozen
81            as the result of an event having been sent to the client (either from
82            the activation of a XIGrabButton or from a previous XIAllowEvents with
83            mode SyncDevice, but not from a Grab), the grab is released and
84            that event is completely reprocessed.  This time, however, the request
85            ignores any passive grabs at or above (towards the root) the
86            grab window of the grab just released.
87            The request has no effect if the specified device is not grabbed by
88            the client or if it is not frozen as the result of an event.
89            In case of gesture begin event being replayed, the original grabbing
90            client will receive a XI_GesturePinchEnd or XI_GestureSwipeEnd event.
91
92        XIAsyncPairedDevice:
93            If the paired master device is frozen by the client, event processing
94            for it continues as usual. If the paired device is frozen multiple
95            times by the client on behalf of multiple separate grabs,
96            XIAsyncPairedDevice thaws for all.
97            XIAsyncPairedDevice has no effect if the device is not frozen by the
98            client, but those devices need not be grabbed by the client.
99            XIAsyncPairedDevice has no effect if deviceid specifies a slave device.
100
101        XISyncPair:
102            If both the device and the paired master device are frozen by the
103            client, event processing (for both devices) continues normally until
104            the next XI_ButtonPress, XI_ButtonRelease, XI_KeyPress, or XI_KeyRelease
105            event is reported to the client for a grabbed device (button event for
106            a pointer, key event for a keyboard), at which time the devices again
107            appear to freeze. However, if the reported event causes the grab to be
108            released, then the devices do not freeze (but if the other device is
109            still grabbed, then a subsequent event for it will still cause both
110            devices to freeze).
111            XISyncPair has no effect unless both the device and the paired master
112            device are frozen by the client. If the device or paired master device
113            is frozen twice by the client on behalf of two separate grabs,
114            XISyncPair thaws for both (but a subsequent freeze for XISyncPair will
115            only freeze each device once).
116            XISyncPair has no effect if deviceid specifies a slave device.
117
118        XIAsyncPair:
119            If the device and the paired master device are frozen by the client,
120            event processing for both devices continues normally. If a device is
121            frozen twice by the client on behalf of two separate grabs, AsyncBoth
122            thaws for both. XIAsyncPair has no effect unless both the device and the
123            paired master device frozen by the client.
124            XIAsyncPair has no effect if deviceid specifies a slave device.
125
126        XIAcceptTouch:
127            The client is deemed to have taken control of the touch sequence once it
128            owns the sequence. TouchEnd events will be sent to all clients listening
129            to the touch sequence that have either grabbed the touch sequence on a
130            child window of the grab_window or have received events for the touch
131            sequence through event selection. These clients will no longer receive
132            any TouchUpdate events.
133
134        XIRejectTouch:
135            The client is no longer interested in the touch sequence, and will
136            receive a XI_TouchEnd event. If the client is the current owner of the
137            sequence, ownership will be passed on to the next listener.
138
139DIAGNOSTICS
140-----------
141
142    BadDevice
143            An invalid deviceid was specified.
144
145    BadAccess
146            This error may occur if event_mode is XIAcceptTouch and this client
147            is not the current or potential owner of the specified touch ID.
148
149    BadValue
150            This error may occur if event_mode is XIAcceptTouch and touch ID is invalid.
151
152    BadWindow
153            A value for a grab_window argument does not name a defined
154            Window.
155
156SEE ALSO
157--------
158
159    XIGrabButton(libmansuffix)
160