13.10 Grabbing a Key

The following paragraphs describe the functions used for passively grabbing and releasing the keyboard.

Function: grab-key window key &key (:modifiers 0) :owner-p :sync-pointer-p :sync-keyboard-p :time

window

A window.

key

The key (type card8) to be grabbed or :any.

:modifiers

A modifier-mask.

: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.

This request establishes a passive grab on the keyboard. If the specified key (which can also be a modifier key) is pressed (whether or not any specified modifier keys are down), and either of the following is true:

• window is an ancestor of (or is) the focus window
• window is a descendant of the focus window and contains the pointer
• These constraints are not satisfied for any ancestor of window, then the following occurs:
  • The keyboard is actively grabbed as described in grab-keyboard
  • The last-keyboard-grab time is set to the time that the key was pressed (as transmitted in the :key-press event)
  • The :key-press event is reported

The interpretation of the remaining arguments is as for grab-keyboard. The active grab is terminated automatically when the specified key has been released, independent of the state of the modifier keys.

A zero modifier mask is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all specified modifiers have currently assigned keycodes. A key of :any is equivalent to issuing the request for all possible keycodes. Otherwise, the key must be in the range specified by display-min-keycode and display-max-keycode in the connection setup.

Function: ungrab-key window key &key (:modifiers 0)

window

A window.

key

The key (type card8) to be released or :any.

:modifiers

A modifier-mask.

Releases the key combination on the specified window if it was grabbed by this client. A zero modifier mask of :any is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A key of :any is equivalent to issuing the request for all possible keycodes. ungrab-key has no effect on an active grab.