XAllowEvents()XAllowEvents()NameXAllowEvents – control the behavior of keyboard and pointer events when
these resources are grabbed.
Synopsis
XAllowEvents(display, event_mode, time)
Display *display;
int event_mode;
Time time;
Arguments
display Specifies a connection to an X server; returned from
XOpenDisplay().
event_mode
Specifies the event mode. Pass one of these constants:
AsyncPointer, SyncPointer, AsyncKeyboard, SyncKeyboard,
ReplayPointer, ReplayKeyboard, AsyncBoth, or SyncBoth.
time Specifies the time when the grab should take place. Pass
either a timestamp, expressed in milliseconds, or the con‐
stant CurrentTime.
DescriptionXAllowEvents() releases the events queued in the server since the last
XAllowEvents() call for the same device and by the same client. Events
are queued in the server (not released to Xlib to propagate into Xlib's
queues) only when the client has caused a device to "freeze" (by grab‐
bing the device with mode GrabModeSync). The request has no effect if
time is earlier than the last-grab time or later than the current
server time.
The event_mode argument controls what device events are released for
and just how and when they are released. The event_mode is interpreted
as follows:
AsyncPointer If XAllowEvents() is called with AsyncPointer while the
pointer is frozen by the client, pointer event process‐
ing resumes normally, even if the pointer is frozen
twice by the client on behalf of two separate grabs.
AsyncPointer has no effect if the pointer is not frozen
by the client, but the pointer need not be grabbed by
the client.
AsyncKeyboard If XAllowEvents() is called with AsyncKeyboard while the
keyboard is frozen by the client, keyboard event pro‐
cessing resumes normally, even if the keyboard is frozen
twice by the client on behalf of two separate grabs.
AsyncKeyboard has no effect if the keyboard is not
frozen by the client, but the keyboard need not be
grabbed by the client.
SyncPointer If XAllowEvents() is called with SyncPointer while the
pointer is frozen by the client, normal pointer event
processing continues until the next ButtonPress or But‐
tonRelease event is reported to the client. At this
time, the pointer again appears to freeze. However, if
the reported event causes the pointer grab to be
released, then the pointer does not freeze, which is the
case when an automatic grab is released by a ButtonRe‐
lease or when XGrabButton() or XGrabKey() has been
called and the specified key or button is released.
SyncPointer has no effect if the pointer is not frozen
or not grabbed by the client.
SyncKeyboard If XAllowEvents() is called with SyncKeyboard while the
keyboard is frozen by the client, normal keyboard event
processing continues until the next KeyPress or KeyRe‐
lease event is reported to the client. At this time,
the keyboard again appears to freeze. However, if the
reported event causes the keyboard grab to be released,
then the keyboard does not freeze, which is the case
when an automatic grab is released by a ButtonRelease or
when XGrabButton() or XGrabKey() has been called and the
specified key or button is released. SyncKeyboard has
no effect if the keyboard is not frozen or not grabbed
by the client.
ReplayPointer This symbol has an effect only if the pointer is grabbed
by the client and thereby frozen as the result of an
event. In other words, XGrabButton() must have been
called and the selected button/key combination pressed,
or an automatic grab (initiated by a ButtonPress) must
be in effect, or a previous XAllowEvents() must have
been called with mode SyncPointer. If the pointer_mode
of the XGrabPointer() was GrabModeSync, then the grab is
released and the releasing event is processed as if it
had occurred after the release, ignoring any passive
grabs at or above in the hierarchy (towards the root) on
the grab-window of the grab just released.
ReplayKeyboard This symbol has an effect only if the keyboard is
grabbed by the client and if the keyboard is frozen as
the result of an event. In other words, XGrabKey() must
have been called and the selected key combination
pressed, or a previous XAllowEvents() must have been
called with mode SyncKeyboard. If the pointer_mode or
keyboard_mode of the XGrabKey() was GrabModeSync, then
the grab is released and the releasing event is pro‐
cessed as if it had occurred after the release, ignor‐
ing any passive grabs at or above in the hierarchy
(towards the root).
SyncBoth SyncBoth has the effect described for both SyncKeyboard
and SyncPointer. SyncBoth has no effect unless both
pointer and keyboard are frozen by the client. If the
pointer or keyboard is frozen twice by the client on
behalf of two separate grabs, SyncBoth "thaws" for both
(but a subsequent freeze for SyncBoth will only freeze
each device once).
AsyncBoth AsyncBoth has the effect described for both AsyncKey‐
board and AsyncPointer. AsyncBoth has no effect unless
both pointer and keyboard are frozen by the client. If
the pointer and the keyboard were frozen by the client,
or if both are frozen twice by two separate grabs, event
processing (for both devices) continues normally. If a
device is frozen twice by the client on behalf of the
two separate grabs, AsyncBoth releases events for both.
AsyncPointer, SyncPointer, and ReplayPointer have no effect on the pro‐
cessing of keyboard events. AsyncKeyboard, SyncKeyboard, and
ReplayKeyboard have no effect on the processing of pointer events.
It is possible for both a pointer grab and a keyboard grab (by the same
or different clients) to be active simultaneously. If a device is
frozen on behalf of either grab, no event processing is performed for
the device. It is also possible for a single device to be frozen
because of both grabs. In this case, the freeze must be released on
behalf of both grabs before events will be released.
For more information on event handling, see Volume One, Chapter 9, The
Keyboard and Pointer.
Errors
BadValue Invalid mode constant.
See AlsoXQLength(), XCheckIfEvent(), XCheckMaskEvent(), XCheckTypedEvent(),
XCheckTypedWindowEvent(), XCheckWindowEvent(), XEventsQueued(), XGet‐
InputFocus(), XGetMotionEvents(), XIfEvent(), XMaskEvent(), XNex‐
tEvent(), XPeekEvent(), XPeekIfEvent(), XPending(), XPutBackEvent(),
XSelectInput(), XSendEvent(), XSetInputFocus(), XSynchronize(), XWin‐
dowEvent().
Xlib - Input Handling XAllowEvents()
