12.9 Grabbing a Button

grab-button

window button event-mask &key (:modifiers 0) :owner-p :sync-pointer-p :sync-keyboard-p :confine-to :cursor

Function

window: A window.
button: The button (type card8) pressed or :any.
event-mask: A pointer-event-mask.
:modifiers: A modifier-mask.
:owner-p: If true, all client windows receive pointer events normally.
:sync-pointer-p: Indicates whether the pointer is handled in a synchronous or asynchronous fashion.
: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.

This request establishes a passive grab. If the specified button is pressed when the specified modifier keys are down (and no other buttons or modifier keys are down), and:

window contains the pointer
The :confine-to window (if any) is viewable
These constraints are not satisfied for any ancestor of window

then:

The pointer is actively grabbed as described with grab-pointer
The last-pointer-grab time is set to the time that the button was pressed (as transmitted in the :button-press event)
The :button-press event is reported

The interpretation of the remaining arguments is the same as with grab-pointer. The active grab is terminated automatically when all buttons are released (independent of the state of modifier keys).

A zero modifier mask is equivalent to issuing the request for all possible modifier-key combinations (including the combination of no modifiers). It is not required that all specified modifiers have currently assigned keycodes. A button of :any is equivalent to issuing the request for all possible buttons. Otherwise, it is not required that the specified button currently be assigned to a physical button.

ungrab-button

window button &key (:modifiers 0)

Function

window: A window.
button: The button (type card8) that is released or :any.
:modifiers: A modifier-mask.

Releases the passive button/key combination on the specified window if it was grabbed by this client. A zero modifier mask is equivalent to issuing the request for all possible modifier combinations including the combination of no modifiers. A button of :any is equivalent to issuing the request for all possible buttons. This has no effect on an active grab.