13.8 Grabbing a Button

CLX provides the grab-button and ungrab-button functions for passively grabbing and releasing pointer control.

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

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.

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

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.