Next Prev Up

12.8 Grabbing the Pointer

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


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.

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

Releases the pointer if this client has it actively grabbed (from either grab-pointer, grab-button , or from a normal button press), and releases any queued events. The request has no effect if the specified :time is earlier than the last-pointer-grab time or is later than the current server time. An ungrabpointer is performed automatically if the event window or :confine-to window for an active pointer grab becomes not viewable.

This request generates :enter-notify and :leave-notify events.


change-active-pointer-grab display event-mask &optional cursor time Function
     
display
A display.
event-mask
A pointer-event-mask.
cursor
A cursor or nil.
time
A timestamp .

Changes the specified dynamic parameters if the pointer is actively grabbed by the client and the specified time is no earlier than the last-pointer-grab time and no later than the current server time. The interpretation of event-mask and cursor are as in grab-pointer. change-active-pointer-grab has no effect on the passive parameters of a grab-button .


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