Next Prev Up

12.10 Grabbing the Keyboard

CLX provides the grab-keyboard and ungrab-keyboard functions for actively grabbing and releasing control of 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.

ungrab-keyboard display &key :time Function
     
display
A display.
:time
A timestamp .

Releases the keyboard if this client has it actively grabbed (from either grab-keyboard or grab-key ), and releases any queued events. The request has no effect if the specified time is earlier than the last-keyboard-grab time or is later than the current server time. An ungrab-keyboard is performed automatically if the event window for an active keyboard grab becomes not viewable.


Next Prev Up
© 1988, 1989 Texas Instruments Incorporated
Conversion to HTML made by Gilbert Baumann.
Last build: Tue Dec 16 23:30:42 1997