12.10 Grabbing the Keyboard

grab-keyboard

window &key :owner-p :sync-pointer-p :sync-keyboard-p :time

Function

window: A window.
:owner-p: If true, all client windows receive keyboard input normally.
:sync-pointer-p: Indicates whether the pointer is in synchronous or asynchronous mode.
:sync-keyboard-p: Indicates whether the keyboard is in synchronous or asynchronous mode.
:time: A timestamp .

Actively grabs control of the keyboard. Further key events are reported only to the grabbing client. The request overrides any active keyboard grab by this client. grab-keyboard generates :focus-in and :focus-out events.

If :owner-p is nil, all generated key events are reported with respect to window. If :owner-p is true, then a generated key event that would normally be reported to this client is reported normally; otherwise the event is reported with respect to the window. Both :key-press and :key-release events are always reported, independent of any event selection made by the client.

If :sync-keyboard-p is nil, keyboard event processing continues normally (asynchronously); if the keyboard is currently frozen by this client, then processing of keyboard events is resumed. If :sync-keyboard-p is true, the keyboard (as seen via the protocol) appears to freeze, and no further keyboard events are generated by the server until the grabbing client issues a releasing allow-events request. Actual keyboard changes are not lost while the keyboard is frozen; they are simply queued for later processing.

If :sync-pointer-p is nil, pointer event processing is unaffected by activation of the grab. If :sync-pointer-p is true, the pointer (as seen via the protocol) appears to freeze, and no further pointer events are generated by the server until the grabbing client issues a releasing allow-events request. Actual pointer changes are not lost while the pointer is frozen; they are simply queued for later processing.

The grab can fail with a status of:

:already-grabbed if the keyboard is actively grabbed by some other client
:frozen if the keyboard is frozen by an active grab from another client
:not-viewable if window is not viewable
:invalid-time if the specified time is earlier than the last-keyboard-grab time or later than the current server time. Otherwise, grab-keyboard returns a status of :success and last-keyboard-grab time is set to the specified time, with current-time replaced by current server time.

grab-status: One of :already-grabbed, :frozen, :invalid-time, :not-viewable, or :success.