Next: , Previous: Images, Up: Top

9 Event

These three status routines always return immediately if there are events already in the queue.

— Function: x:q-length display

Returns the length of the event queue for the connected display. Note that there may be more events that have not been read into the queue yet (see X:Events-Queued).

— Function: x:pending display

Returns the number of events that have been received from the X server but have not been removed from the event queue.

— Function: x:events-queued display

Returns the number of events already in the queue if the number is nonzero. If there are no events in the queue, X:Events-Queued attempts to read more events out of the application's connection without flushing the output buffer and returns the number read.

Both of these routines return an object of type event.

— Function: x:next-event display

Removes and returns the first event from the event queue. If the event queue is empty, X:Next-Event flushes the output buffer and blocks until an event is received.

— Function: x:peek-event display

Returns the first event from the event queue, but it does not remove the event from the queue. If the queue is empty, X:Peek-Event flushes the output buffer and blocks until an event is received.

Each event object has fields dependent on its sub-type.

— Function: x:event-ref event field-name

window The window on which event was generated and is referred to as the event window.
root is the event window's root window.
subwindow If the source window is an inferior of the event window, the subwindow is the child of the event window that is the source window or the child of the event window that is an ancestor of the source window. Otherwise, ‘None’.
X-event:type An integer: x:Key-Press, x:Key-Release, x:Button-Press, x:Button-Release, x:Motion-Notify, x:Enter-Notify, x:Leave-Notify, x:Focus-In, x:Focus-Out, x:Keymap-Notify, x:Expose, x:Graphics-Expose, x:No-Expose, x:Visibility-Notify, x:Create-Notify, x:Destroy-Notify, x:Unmap-Notify, x:Map-Notify, x:Map-Request, x:Reparent-Notify, x:Configure-Notify, x:Configure-Request, x:Gravity-Notify, x:Resize-Request, x:Circulate-Notify, x:Circulate-Request, x:Property-Notify, x:Selection-Clear, x:Selection-Request, x:Selection-Notify, x:Colormap-Notify, x:Client-Message, or x:Mapping-Notify.
X-event:serial The serial number of the protocol request that generated the event.
X-event:send-event Boolean that indicates whether the event was sent by a different client.
X-event:time The time when the event was generated expressed in milliseconds.
X-event:y For window entry/exit events the x and y members are set to the coordinates of the pointer position in the event window. This position is always the pointer's final position, not its initial position. If the event window is on the same screen as the root window, x and y are the pointer coordinates relative to the event window's origin. Otherwise, x and y are set to zero.

For expose events The x and y members are set to the coordinates relative to the drawable's origin and indicate the upper-left corner of the rectangle.

For configure, create, gravity, and reparent events the x and y members are set to the window's coordinates relative to the parent window's origin and indicate the position of the upper-left outside corner of the created window.

X-event:y-root The pointer's coordinates relative to the root window's origin at the time of the event.
X-event:state For keyboard, pointer and window entry/exit events, the state member is set to indicate the logical state of the pointer buttons and modifier keys just prior to the event, which is the bitwise inclusive OR of one or more of the button or modifier key masks: x:Button1-Mask, x:Button2-Mask, x:Button3-Mask, x:Button4-Mask, x:Button5-Mask, x:Shift-Mask, x:Lock-Mask, x:Control-Mask, x:Mod1-Mask, x:Mod2-Mask, x:Mod3-Mask, x:Mod4-Mask, and x:Mod5-Mask.

For visibility events, the state of the window's visibility: x:Visibility-Unobscured, x:Visibility-Partially-Obscured, or x:Visibility-Fully-Obscured.

For colormap events, indicates whether the colormap is installed or uninstalled: x:Colormap-Installed or x:Colormap-Uninstalled.

For property events, indicates whether the property was changed to a new value or deleted: x:Property-New-Value or x:Property-Delete.

X-event:keycode An integer that represents a physical key on the keyboard.
X-event:same-screen Indicates whether the event window is on the same screen as the root window. If #t, the event and root windows are on the same screen. If #f, the event and root windows are not on the same screen.
X-event:button The pointer button that changed state; can be the x:Button1, x:Button2, x:Button3, x:Button4, or x:Button5 value.
X-event:is-hint Detail of motion-notify events: x:Notify-Normal or x:Notify-Hint.
X-event:mode Indicates whether the event is a normal event, pseudo-motion event when a grab activates, or a pseudo-motion event when a grab deactivates: x:Notify-Normal, x:Notify-Grab, or x:Notify-Ungrab.
X-event:detail Indicates the notification detail: x:Notify-Ancestor, x:Notify-Virtual, x:Notify-Inferior, x:Notify-Nonlinear, or x:Notify-Nonlinear-Virtual.
X-event:focus If the event window is the focus window or an inferior of the focus window, #t; otherwise #f.
X-event:height The size (extent) of the rectangle.
X-event:count For mapping events is the number of keycodes altered.

For expose events Is the number of Expose or GraphicsExpose events that are to follow. If count is zero, no more Expose events follow for this window. However, if count is nonzero, at least that number of Expose events (and possibly more) follow for this window. Simple applications that do not want to optimize redisplay by distinguishing between subareas of its window can just ignore all Expose events with nonzero counts and perform full redisplays on events with zero counts.

X-event:major-code The major_code member is set to the graphics request initiated by the client and can be either X_CopyArea or X_CopyPlane. If it is X_CopyArea, a call to XCopyArea initiated the request. If it is X_CopyPlane, a call to XCopyPlane initiated the request.
X-event:minor-code Not currently used.
X-event:border-width For configure events, the width of the window's border, in pixels.
X-event:override-redirect The override-redirect attribute of the window. Window manager clients normally should ignore this window if it is #t.
X-event:from-configure True if the event was generated as a result of a resizing of the window's parent when the window itself had a win-gravity of x:Unmap-Gravity.
X-event:value-mask Indicates which components were specified in the ConfigureWindow protocol request. The corresponding values are reported as given in the request. The remaining values are filled in from the current geometry of the window, except in the case of above (sibling) and detail (stack-mode), which are reported as None and Above, respectively, if they are not given in the request.
X-event:place The window's position after the restack occurs and is either x:Place-On-Top or x:Place-On-Bottom. If it is x:Place-On-Top, the window is now on top of all siblings. If it is x:Place-On-Bottom, the window is now below all siblings.
X-event:new indicate whether the colormap for the specified window was changed or installed or uninstalled and can be True or False. If it is True, the colormap was changed. If it is False, the colormap was installed or uninstalled.
X-event:format Is 8, 16, or 32 and specifies whether the data should be viewed as a list of bytes, shorts, or longs
X-event:request Indicates the kind of mapping change that occurred and can be x:Mapping-Modifier, x:Mapping-Keyboard, or x:Mapping-Pointer. If it is x:Mapping-Modifier, the modifier mapping was changed. If it is x:Mapping-Keyboard, the keyboard mapping was changed. If it is x:Mapping-Pointer, the pointer button mapping was changed.
X-event:first-keycode The X-event:first-keycode is set only if the X-event:request was set to x:Mapping-Keyboard. The number in X-event:first-keycode represents the first number in the range of the altered mapping, and X-event:count represents the number of keycodes altered.