NAME
XAllowEvents − 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
displaySpecifies 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.
timeSpecifies the time when the grab should take place. Pass either a timestamp, expressed in milliseconds, or the constant CurrentTime.
Description
XAllowEvents() 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 grabbing 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:
AsyncPointerIf XAllowEvents() is called with AsyncPointer while the pointer is frozen by the client, pointer event processing 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.
AsyncKeyboardIf XAllowEvents() is called with AsyncKeyboard while the keyboard is frozen by the client, keyboard event processing 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.
SyncPointerIf XAllowEvents() is called with SyncPointer while the pointer is frozen by the client, normal pointer event processing continues until the next ButtonPress or ButtonRelease 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 ButtonRelease 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.
SyncKeyboardIf XAllowEvents() is called with SyncKeyboard while the keyboard is frozen by the client, normal keyboard event processing continues until the next KeyPress or KeyRelease 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.
ReplayPointerThis 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.
ReplayKeyboardThis 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 processed as if it had occurred after the release, ignoring any passive grabs at or above in the hierarchy (towards the root).
SyncBothSyncBoth 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).
AsyncBothAsyncBoth has the effect described for both AsyncKeyboard 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 processing 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
BadValueInvalid mode constant.
See Also
QLength(), XCheckIfEvent(), XCheckMaskEvent(), XCheckTypedEvent(), XCheckTypedWindowEvent(), XCheckWindowEvent(), XEventsQueued(), XGetInputFocus(), XGetMotionEvents(), XIfEvent(), XMaskEvent(), XNextEvent(), XPeekEvent(), XPeekIfEvent(), XPending(), XPutBackEvent(), XSelectInput(), XSendEvent(), XSetInputFocus(), XSynchronize(), XWindowEvent.
Copyright O’Reilly & Assoc. —