12.8 Grabbing the Pointer

grab-pointer

window event-mask &key :owner-p :sync-pointer-p :sync-keyboard-p :confine-to :cursor :time

Function

window: The window grabbing the pointer.
event-mask: A pointer-event-mask.
:owner-p: If true, all client windows receive pointer events 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.
:confine-to: A window to which the pointer is confined.
:cursor: A cursor.
:time: A timestamp . A nil value means the current server time is used.

Actively grabs control of the pointer. Further pointer events are only reported to the grabbing client. The request overrides any active pointer grab by this client.

If :owner-p is nil, all generated pointer events are reported with respect to window, and are only reported if selected by event-mask. If :owner-p is true, and if a generated pointer event would normally be reported to this client, it is reported normally; otherwise the event is reported with respect to the window, and is only reported if selected by event-mask. For either value of :owner-p, unreported events are simply discarded.

If :sync-pointer-p is nil, pointer event processing continues normally (asynchronously); if the pointer is currently frozen by this client, then processing of pointer events is resumed. If :sync-pointer-p is true (indicating a synchronous action), 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.

If :sync-keyboard-p is nil, keyboard event processing is unaffected by activation of the grab. 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 :cursor is specified, it is displayed regardless of what window the pointer is in. Otherwise, the normal cursor for the window is displayed.

If a :confine-to window is specified, the pointer is restricted to stay within that window. The :confine-to window does not need to have any relationship to the window . If the pointer is not initially in the :confine-to window, it is warped automatically to the closest edge (with :enter/:leave-events generated normally) just before the grab activates. If the :confine-to window is subsequently reconfigured, the pointer is warped automatically as necessary to keep it contained in the window.

grab-pointer generates :enter-notify and :leave-notify events. grab-pointer can fail with a status of:

:already-grabbed if the pointer is actively grabbed by some other client
:frozen if the pointer is frozen by an active grab of another client
:not-viewable if the window or the :confine-to window is not viewable, or if the :confine-to window lies completely outside the boundaries of the root window.
:invalid-time if the specified time is earlier than the last-pointer-grab time or later than the current server time. Otherwise, the last-pointer-grab time is set to the specified time, with current-time replaced by the current server time, and a value of :success is returned by grab-pointer.

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