12.12.1 Keyboard and Pointer Events

The keyboard and pointer events are: :key-press, :key-release, :button-press, :button-release, :motion-notify, :enter-notify, and :leave-notify.



:key-press, :key-release, :button-press, :button-release Event Type
        
Selected by:
:key-press, :key-release, :button-press, or :button-release.

:key-press, and :key-release events are generated when a key or pointer button changes state. Note that :key-press and :key-release are generated for all keys, even those mapped to modifiers. All of these event types have the same slots. The window containing the pointer at the time of the event is referred to as the source window. The event window is the window to which the event is actually reported. The event window is found by starting with the source window and looking up the hierarchy for the first window on which any client has selected interest in the event (provided no intervening window prohibits event generation by including the event type in its do-not-propagate-mask). The actual window used for reporting can be modified by active grabs and, in the case of keyboard events, can be modified by the focus window.

A :button-press event has the effect of a temporary grab-button. When a pointer button is pressed and no active pointer grab is in progress, the ancestors of the source window are searched from the root down, looking for a passive grab to activate. If no matching passive grab on the button exists, then an active grab is started automatically for the client receiving the :button-press event, and the last-pointer-grab time is set to the current server time. The effect is essentially equivalent to calling grab-button with the following arguments:

Argument Description
window The event window.
button The button that was pressed.
event-mask The client's selected pointer events on the event window.
:modifiers 0
:owner-p t if the client has :owner-grab-button selected on the event window; otherwise nil.
:sync-pointer-p nil
:sync-keyboard-p nil
:confine-to nil
:cursor nil

The :button-press grab is terminated automatically when all buttons are released. The functions ungrab-pointer and change-active-pointer-grab can both be used to modify the :button-press grab.

window, event-window
Type window. The window receiving the event.
code
Type card8. The code argument varies with the event type. For :key-press and :key-release, code is the keycode (see paragrpah 14.4, Keyboard Encodings). For :button-press and :button-release, code is the pointer button number.
x
Type int16. If event-window is on the same screen as root, then x and y are the pointer coordinates relative to the event-window; otherwise x and y are zero.
y
Type int16. If event-window is on the same screen as root, then x and y are the pointer coordinates relative to the event-window; otherwise x and y are zero.
state
Type card16. A mask that gives the state of the buttons and modifier keys just before the event.
time
Type card32. A timestamp for the moment when the event occurred.
root
Type window. The root window of the source window.
root-x
Type int16. The x coordinate of the pointer position relative to root at the time of the event.
root-y
Type int16. The y coordinate of the pointer position relative to root at the time of the event.
child
Type (or null window). If the source window is an inferior of the event-window, child is set to the child of event-window that is an ancestor of (or is) the source window; otherwise, it is set to nil.
same-screen-p
Type boolean. True if event-window and root are on the same screen.


:motion-notify Event Type
        

Selected by:
:button-1-motion, :button-2-motion, :button-3-motion, :button-4-motion, :button-5-motion, :button-motion, or :pointer-motion.

The :motion-notify event is generated when the pointer moves. A :motion-notify event has the same slots as :button-press, :button-release, :key-press, and :key-release events, with the exception that the code slot is replaced by the hint-p slot. As with these other events, the event window for :motion-notify is found by starting with the source window and looking up the hierarchy for the first window on which any client has selected interest in the event (provided no intervening window prohibits event generation by including :motion-notify in its do-not-propagate-mask).The actual window used for reporting can be modified by active grabs.

:motion-notify events are generated only when the motion begins and ends in the window. The granularity of motion events is not guaranteed, but a client selecting for motion events is guaranteed to get at least one event when the pointer moves and comes to rest. Selecting :pointer-motion generates :motion-notify events regardless of the state of the pointer buttons. By selecting some subset of :button[1-5]-motion instead, :motion-notify events are only received when one or more of the specified buttons are pressed. By selecting :button-motion, :motion-notify events are only received when at least one button is pressed. If :pointer-motion-hint is also selected, the server is free to send only one :motion-notify, until either the key or button state changes, the pointer leaves the event window, or the client calls query-pointer or motion-events.

hint-p
Type boolean. True if the event is a hint generated by selecting :pointer-motion-hint.


:enter-notify, :leave-notify Event Type
        
Selected by:
:enter-window or :leave-window.

If pointer motion or a window hierarchy change causes the pointer to be in a different window than before, :enter-notify and :leave-notify events are generated instead of a :motion-notify event. All :enter-notify and :leave-notify events caused by a hierarchy change are generated after any hierarchy event (:unmap-notify, :map-notify, :configure-notify, :gravity-notify, or :circulate-notify) caused by that change, but the ordering of :enter-notify and :leave-notify events with respect to :focus-out, :visibility-notify, and :exposure events is not constrained by the X protocol. An :enter-notify or :leave-notify event can also be generated when a client application calls change-active-pointer-grab, grab-pointer, or ungrab-pointer.

window, event-window
Type window. The window receiving the event.
x
Type int16. The final pointer position. If event-window is on the same screen as root, then x and y are the pointer coordinates relative to the event-window; otherwise x and y are zero.
y
Type int16. The final pointer position. If event-window is on the same screen as root, then x and y are the pointer coordinates relative to the event-window; otherwise x and y are zero.
mode
Type (member :normal :grab :ungrab). Events caused when the pointer is actively grabbed have mode :grab. Events caused when an active pointer grab deactivates have mode :ungrab. In all other cases, mode is :normal.
kind
Type (member :ancestor :virtual :inferior :nonlinear :nonlinear-virtual). When the pointer moves from window A to window B, and A is an inferior of B:
  • :leave-notify with kind :ancestor is generated on A
  • :leave-notify with kind :virtual is generated on each window between A and B exclusive (in that order)
  • :enter-notify with kind :inferior is generated on B

When the pointer moves from window A to window B, and B is an inferior of A:

  • :leave-notify with kind :inferior is generated on A
  • :enter-notify with kind :virtual is generated on each window between A and B exclusive (in that order)
  • :enter-notify with kind :ancestor is generated on B

When the pointer moves from window A to window B, with window C being their least common ancestor:

  • :leave-notify with kind :nonlinear is generated on A
  • :leave-notify with kind :nonlinear-virtual is generated on each window between A and C exclusive (in that order)
  • :enter-notify with kind :nonlinear-virtual is generated on each window between C and B exclusive (in that order)
  • :enter-notify with kind :nonlinear is generated on B

When the pointer moves from window A to window B, on different screens:

  • :leave-notify with kind :nonlinear is generated on A
  • If A is not a root window, :leave-notify with kind :nonlinear-virtual is generated on each window above A up to and including its root (in order)
  • If B is not a root window, :enter-notify with kind :nonlinear-virtual is generated on each window from B's root down to but not including B (in order)
  • :enter-notify with kind :nonlinear is generated on B

When a pointer grab activates (but after any initial warp into a confine-to window, and before generating any actual :button-press event that activates the grab), with G the grab-window for the grab and P the window the pointer is in, then :enter-notify and :leave-notify events with mode :grab are generated (as for :normal above) as if the pointer were to suddenly warp from its current position in P to some position in G. However, the pointer does not warp, and the pointer position is used as both the initial and final positions for the events.

When a pointer grab deactivates (but after generating any actual :button-release event that deactivates the grab), with G the grab-window for the grab and P the window the pointer is in, then :enter-notify and :leave-notify events with mode :ungrab are generated (as for :normal above) as if the pointer were to suddenly warp from from some position in G to its current position in P. However, the pointer does not warp, and the current pointer position is used as both the initial and final positions for the events.

focus-p
Type boolean. If event-window is the focus window or an inferior of the focus window, then focus-p is t; otherwise, focus-p is nil.
state
Type card16. A mask that gives the state of the buttons and modifier keys just before the event.
time
Type card32. A timestamp for the moment when the event occurred.
root
Type window. The root window containing the final pointer position.
root-x
Type int16. The x coordinate of the pointer position relative to root at the time of the event.
root-y
Type int16. The y coordinate of the pointer position relative to root at the time of the event.
child
Type (or null window). In a :leave-notify event, if a child of the event-window contains the initial position of the pointer, the child slot is set to that child; otherwise, the child slot is nil. For an :enter-notify event, if a child of the event-window contains the final pointer position, the child slot is set to that child; otherwise, the child slot is nil.
same-screen-p
Type boolean. True if event-window and root are on the same screen.