13.12 Releasing Queued Events

A client grabbing the keyboard or pointer can freeze the reporting of events on that device. When an input device is thus frozen, the server queues events until explicitly requested to release them by the grabbing client. CLX programs can use the allow-events function to release queued events from a frozen input device.

Function: allow-events display mode &optional time

display

A display.

mode

One of: :async-pointer, :sync-pointer, :reply-pointer, :async-keyboard, :sync-keyboard, :replay-keyboard, :async-both, :sync-both.

time

A timestamp.

Releases some queued events if the client has caused a device to freeze. The request has no effect if the time is earlier than the last-grab time of the most recent active grab for the client, or if the time is later than the current server time. If time is nil, the current server time is used. The effect of this function depends on the specified mode.

• :async-pointer – If the pointer is frozen by the client, pointer event processing continues normally. If the pointer is frozen twice by the client on behalf of two separate grabs, :async-pointer releases events for both grabs. :async-pointer has no effect if the pointer is not frozen by the client, but the pointer need not be grabbed by the client.
• :sync-pointer – If the pointer is frozen and actively grabbed by the client, pointer event processing continues normally until the next :button-press or :button-release event is reported to the client, at which time the pointer again appears to freeze. However, if the reported event causes the pointer grab to be released, the pointer does not freeze. :sync-pointer has no effect if the pointer is not frozen by the client, or if the pointer is not grabbed by the client.
• :replay-pointer – If the pointer is actively grabbed by the client and is frozen as the result of an event having been sent to the client (either from the activation of a grab-button, or from a previous allow-events with mode :sync-pointer, but not from a grab-pointer), the pointer grab is released and that event is completely reprocessed, but this time ignoring any passive grabs at or above (towards the root) the grab-window of the grab just released. The request has no effect if the pointer is not grabbed by the client, or if the pointer is not frozen as the result of an event.
• :async-keyboard – If the keyboard is frozen by the client, keyboard event processing continues normally. If the keyboard is frozen twice by the client on behalf of two separate grabs, :async-keyboard releases events for both grabs. :async-keyboard has no effect if the keyboard is not frozen by the client, but the keyboard need not be grabbed by the client.
• :sync-keyboard – If the keyboard is frozen and actively grabbed by the client, keyboard event processing continues normally until the next :key-press or :key-release event is reported to the client, at which time the keyboard again appears to freeze. However if the reported event causes the keyboard grab to be released, the keyboard does not freeze. :sync-keyboard has no effect if the keyboard is not frozen by the client, or if the keyboard is not grabbed by the client.
• :replay-keyboard – If the keyboard is actively grabbed by the client and is frozen as the result of an event having been sent to the client (either from the activation of a grab-key, or from a previous allow-events with mode :sync-keyboard, but not from a grab-keyboard), the keyboard grab is released and that event is completely reprocessed, but this time ignoring any passive grabs at or above (towards the root) the grab-window of the grab just released. The request has no effect if the keyboard is not grabbed by the client, or if the keyboard is not frozen as the result of an event.
• :sync-both – If both pointer and keyboard are frozen by the client, event processing (for both devices) continues normally until the next :button-press, :button-release, :key-press, or :key-release event is reported to the client for a grabbed device (button event for the pointer, key event for the keyboard). At this time, the devices again appear to freeze. If the reported event causes the grab to be released, the devices do not freeze. However, if the other device is still grabbed, then a subsequent event for it will still cause both devices to freeze. :sync-both has no effect unless both pointer and keyboard are frozen by the client. If the pointer of keyboard is frozen twice by the client on behalf of two separate grabs, :sync-both thaws for both, but a subsequent freeze for :sync-both will only freeze each device once.
• :async-both – If the pointer and the keyboard are frozen by the client, event processing for both devices continues normally. If a device is frozen twice by the client on behalf of two separate grabs, :async-both thaws for both. :async-both has no effect unless both pointer and keyboard are frozen by the client.

:async-pointer, :sync-pointer, and :replay-pointer have no effect on processing of keyboard events. :async-keyboard, :sync-keyboard, and :replay-keyboard have no effect on processing of pointer events.

It is possible for both a pointer grab and a keyboard grab to be active simultaneously by the same or different clients. When a device is frozen on behalf of either grab, no event processing is performed for the device. It is possible for a single device to be frozen due to both grabs. In this case, the freeze must be released on behalf of both grabs before events can again be processed.