DocsTable of Contents
- Input Device events
- Pointer Window events
- Input Focus events
- KeymapNotify
- Expose
- GraphicsExposure
- NoExposure
- VisibilityNotify
- CreateNotify
- DestroyNotify
- UnmapNotify
- MapNotify
- MapRequest
- ReparentNotify
- ConfigureNotify
- GravityNotify
- ResizeRequest
- ConfigureRequest
- CirculateNotify
- CirculateRequest
- PropertyNotify
- SelectionClear
- SelectionRequest
- SelectionNotify
- ColormapNotify
- MappingNotify
- ClientMessage
When a button press is processed with the pointer in some window W and no active pointer grab is in progress, the ancestors of W 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 event, and the last-pointer-grab time is set to the current server time. The effect is essentially equivalent to a GrabButton with arguments:
| Argument | Value |
|---|---|
| event-window | Event window |
| event-mask | Client's selected pointer events on the event window |
| pointer-mode and keyboard-mode | Asynchronous |
| owner-events | True if the client has OwnerGrabButton selected on the event window, otherwise False |
| confine-to | None |
| cursor | None |
The grab is terminated automatically when the logical state of the pointer has all buttons released. UngrabPointer and ChangeActivePointerGrab can both be used to modify the active grab.
These events are generated either when a key or button logically changes state or when the pointer logically moves. The generation of these logical changes may lag the physical changes if device event processing is frozen. Note that KeyPress and KeyRelease are generated for all keys, even those mapped to modifier bits. The source of the event is the window the pointer is in. The window the event is reported with respect to is called the event window. 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.
The root is the root window of the source window, and root-x and root-y are the pointer coordinates relative to root's origin at the time of the event. Event is the event window. If the event window is on the same screen as root, then event-x and event-y are the pointer coordinates relative to the event window's origin. Otherwise, event-x and event-y are zero. If the source window is an inferior of the event window, then child is set to the child of the event window that is an ancestor of (or is) the source window. Otherwise, it is set to None. The state component gives the logical state of the buttons and modifier keys just before the event. The detail component type varies with the event type:
| Event | Component |
|---|---|
| KeyPress, KeyRelease | KEYCODE |
| ButtonPress, ButtonRelease | BUTTON |
| MotionNotify | { Normal Hint } |
MotionNotify events are only generated 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 PointerMotion receives events independent of the state of the pointer buttons. By selecting some subset of Button[1-5]Motion instead, MotionNotify events will only be received when one or more of the specified buttons are pressed. By selecting ButtonMotion, MotionNotify events will be received only when at least one button is pressed. The events are always of type MotionNotify, independent of the selection. If PointerMotionHint is selected, the server is free to send only one MotionNotify event (with detail Hint) to the client for the event window until either the key or button state changes, the pointer leaves the event window, or the client issues a QueryPointer or GetMotionEvents request.
If pointer motion or window hierarchy change causes the pointer to be in a different window than before, EnterNotify and LeaveNotify events are generated instead of a MotionNotify event. Only clients selecting EnterWindow on a window receive EnterNotify events, and only clients selecting LeaveWindow receive LeaveNotify events. The pointer position reported in the event is always the final position, not the initial position of the pointer. The root is the root window for this position, and root-x and root-y are the pointer coordinates relative to root's origin at the time of the event. Event is the event window. If the event window is on the same screen as root, then event-x and event-y are the pointer coordinates relative to the event window's origin. Otherwise, event-x and event-y are zero. In a LeaveNotify event, if a child of the event window contains the initial position of the pointer, then the child component is set to that child. Otherwise, it is None. For an EnterNotify event, if a child of the event window contains the final pointer position, then the child component is set to that child. Otherwise, it is None. If the event window is the focus window or an inferior of the focus window, then focus is True. Otherwise, focus is False.
Normal pointer motion events have mode Normal. Pseudo-motion events when a grab activates have mode Grab, and pseudo-motion events when a grab deactivates have mode Ungrab.
All EnterNotify and LeaveNotify events caused by a hierarchy change are generated after any hierarchy event caused by that change (that is, UnmapNotify, MapNotify, ConfigureNotify, GravityNotify, CirculateNotify), but the ordering of EnterNotify and LeaveNotify events with respect to FocusOut, VisibilityNotify, and Expose events is not constrained.
Normal events are generated as follows:
When the pointer moves from window A to window B and A is an inferior of B:
LeaveNotify with detail Ancestor is generated on A.
LeaveNotify with detail Virtual is generated on each window between A and B exclusive (in that order).
EnterNotify with detail Inferior is generated on B.
When the pointer moves from window A to window B and B is an inferior of A:
LeaveNotify with detail Inferior is generated on A.
EnterNotify with detail Virtual is generated on each window between A and B exclusive (in that order).
EnterNotify with detail Ancestor is generated on B.
When the pointer moves from window A to window B and window C is their least common ancestor:
LeaveNotify with detail Nonlinear is generated on A.
LeaveNotify with detail NonlinearVirtual is generated on each window between A and C exclusive (in that order).
EnterNotify with detail NonlinearVirtual is generated on each window between C and B exclusive (in that order).
EnterNotify with detail Nonlinear is generated on B.
When the pointer moves from window A to window B on different screens:
LeaveNotify with detail Nonlinear is generated on A.
If A is not a root window, LeaveNotify with detail NonlinearVirtual is generated on each window above A up to and including its root (in order).
If B is not a root window, EnterNotify with detail NonlinearVirtual is generated on each window from B's root down to but not including B (in order).
EnterNotify with detail 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 ButtonPress event that activates the grab), G is the grab-window for the grab, and P is the window the pointer is in:
EnterNotify and LeaveNotify 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 ButtonRelease event that deactivates the grab), G is the grab-window for the grab, and P is the window the pointer is in:
EnterNotify and LeaveNotify events with mode Ungrab are generated (as for Normal above) as if the pointer were to suddenly warp 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.
| FocusIn |
| FocusOut |
| event: WINDOW |
| mode: { Normal, WhileGrabbed, Grab, Ungrab} |
| detail: { Ancestor, Virtual, Inferior, Nonlinear, NonlinearVirtual, Pointer, |
| PointerRoot, None } |
These events are generated when the input focus changes and are reported to clients selecting FocusChange on the window. Events generated by SetInputFocus when the keyboard is not grabbed have mode Normal. Events generated by SetInputFocus when the keyboard is grabbed have mode WhileGrabbed. Events generated when a keyboard grab activates have mode Grab, and events generated when a keyboard grab deactivates have mode Ungrab.
All FocusOut events caused by a window unmap are generated after any UnmapNotify event, but the ordering of FocusOut with respect to generated EnterNotify, LeaveNotify, VisibilityNotify, and Expose events is not constrained.
Normal and WhileGrabbed events are generated as follows:
When the focus moves from window A to window B, A is an inferior of B, and the pointer is in window P:
FocusOut with detail Ancestor is generated on A.
FocusOut with detail Virtual is generated on each window between A and B exclusive (in order).
FocusIn with detail Inferior is generated on B.
If P is an inferior of B but P is not A or an inferior of A or an ancestor of A, FocusIn with detail Pointer is generated on each window below B down to and including P (in order).
When the focus moves from window A to window B, B is an inferior of A, and the pointer is in window P:
If P is an inferior of A but P is not an inferior of B or an ancestor of B, FocusOut with detail Pointer is generated on each window from P up to but not including A (in order).
FocusOut with detail Inferior is generated on A.
FocusIn with detail Virtual is generated on each window between A and B exclusive (in order).
FocusIn with detail Ancestor is generated on B.
When the focus moves from window A to window B, window C is their least common ancestor, and the pointer is in window P:
If P is an inferior of A, FocusOut with detail Pointer is generated on each window from P up to but not including A (in order).
FocusOut with detail Nonlinear is generated on A.
FocusOut with detail NonlinearVirtual is generated on each window between A and C exclusive (in order).
FocusIn with detail NonlinearVirtual is generated on each window between C and B exclusive (in order).
FocusIn with detail Nonlinear is generated on B.
If P is an inferior of B, FocusIn with detail Pointer is generated on each window below B down to and including P (in order).
When the focus moves from window A to window B on different screens and the pointer is in window P:
If P is an inferior of A, FocusOut with detail Pointer is generated on each window from P up to but not including A (in order).
FocusOut with detail Nonlinear is generated on A.
If A is not a root window, FocusOut with detail NonlinearVirtual is generated on each window above A up to and including its root (in order).
If B is not a root window, FocusIn with detail NonlinearVirtual is generated on each window from B's root down to but not including B (in order).
FocusIn with detail Nonlinear is generated on B.
If P is an inferior of B, FocusIn with detail Pointer is generated on each window below B down to and including P (in order).
When the focus moves from window A to PointerRoot (or None) and the pointer is in window P:
If P is an inferior of A, FocusOut with detail Pointer is generated on each window from P up to but not including A (in order).
FocusOut with detail Nonlinear is generated on A.
If A is not a root window, FocusOut with detail NonlinearVirtual is generated on each window above A up to and including its root (in order).
FocusIn with detail PointerRoot (or None) is generated on all root windows.
If the new focus is PointerRoot, FocusIn with detail Pointer is generated on each window from P's root down to and including P (in order).
When the focus moves from PointerRoot (or None) to window A and the pointer is in window P:
If the old focus is PointerRoot, FocusOut with detail Pointer is generated on each window from P up to and including P's root (in order).
FocusOut with detail PointerRoot (or None) is generated on all root windows.
If A is not a root window, FocusIn with detail NonlinearVirtual is generated on each window from A's root down to but not including A (in order).
FocusIn with detail Nonlinear is generated on A.
If P is an inferior of A, FocusIn with detail Pointer is generated on each window below A down to and including P (in order).
When the focus moves from PointerRoot to None (or vice versa) and the pointer is in window P:
If the old focus is PointerRoot, FocusOut with detail Pointer is generated on each window from P up to and including P's root (in order).
FocusOut with detail PointerRoot (or None) is generated on all root windows.
FocusIn with detail None (or PointerRoot) is generated on all root windows.
If the new focus is PointerRoot, FocusIn with detail Pointer is generated on each window from P's root down to and including P (in order).
When a keyboard grab activates (but before generating any actual KeyPress event that activates the grab), G is the grab-window for the grab, and F is the current focus:
FocusIn and FocusOut events with mode Grab are generated (as for Normal above) as if the focus were to change from F to G.
When a keyboard grab deactivates (but after generating any actual KeyRelease event that deactivates the grab), G is the grab-window for the grab, and F is the current focus:
FocusIn and FocusOut events with mode Ungrab are generated (as for Normal above) as if the focus were to change from G to F.
| KeymapNotify |
| keys: LISTofCARD8 |
The value is a bit vector as described in QueryKeymap. This event is reported to clients selecting KeymapState on a window and is generated immediately after every EnterNotify and FocusIn.
| Expose |
| window: WINDOW |
| x, y, width, height: CARD16 |
| count: CARD16 |
This event is reported to clients selecting Exposure on the window. It is generated when no valid contents are available for regions of a window, and either the regions are visible, the regions are viewable and the server is (perhaps newly) maintaining backing store on the window, or the window is not viewable but the server is (perhaps newly) honoring window's backing-store attribute of Always or WhenMapped. The regions are decomposed into an arbitrary set of rectangles, and an Expose event is generated for each rectangle.
For a given action causing exposure events, the set of events for a given window are guaranteed to be reported contiguously. If count is zero, then no more Expose events for this window follow. If count is nonzero, then at least that many more Expose events for this window follow (and possibly more).
The x and y coordinates are relative to window's origin and specify the upper-left corner of a rectangle. The width and height specify the extent of the rectangle.
Expose events are never generated on InputOnly windows.
All Expose events caused by a hierarchy change are generated after any hierarchy event caused by that change (for example, UnmapNotify, MapNotify, ConfigureNotify, GravityNotify, CirculateNotify). All Expose events on a given window are generated after any VisibilityNotify event on that window, but it is not required that all Expose events on all windows be generated after all Visibilitity events on all windows. The ordering of Expose events with respect to FocusOut, EnterNotify, and LeaveNotify events is not constrained.
| GraphicsExposure |
| drawable: DRAWABLE |
| x, y, width, height: CARD16 |
| count: CARD16 |
| major-opcode: CARD8 |
| minor-opcode: CARD16 |
This event is reported to a client using a graphics context with graphics-exposures selected and is generated when a destination region could not be computed due to an obscured or out-of-bounds source region. All of the regions exposed by a given graphics request are guaranteed to be reported contiguously. If count is zero then no more GraphicsExposure events for this window follow. If count is nonzero, then at least that many more GraphicsExposure events for this window follow (and possibly more).
The x and y coordinates are relative to drawable's origin and specify the upper-left corner of a rectangle. The width and height specify the extent of the rectangle.
The major and minor opcodes identify the graphics request used. For the core protocol, major-opcode is always CopyArea or CopyPlane, and minor-opcode is always zero.
| NoExposure |
| drawable: DRAWABLE |
| major-opcode: CARD8 |
| minor-opcode: CARD16 |
This event is reported to a client using a graphics context with graphics-exposures selected and is generated when a graphics request that might produce GraphicsExposure events does not produce any. The drawable specifies the destination used for the graphics request.
The major and minor opcodes identify the graphics request used. For the core protocol, major-opcode is always CopyArea or CopyPlane, and the minor-opcode is always zero.
| VisibilityNotify |
| window: WINDOW |
| state: { Unobscured, PartiallyObscured, FullyObscured} |
This event is reported to clients selecting VisibilityChange on the window. In the following, the state of the window is calculated ignoring all of the window's subwindows. When a window changes state from partially or fully obscured or not viewable to viewable and completely unobscured, an event with Unobscured is generated. When a window changes state from viewable and completely unobscured, from viewable and completely obscured, or from not viewable, to viewable and partially obscured, an event with PartiallyObscured is generated. When a window changes state from viewable and completely unobscured, from viewable and partially obscured, or from not viewable to viewable and fully obscured, an event with FullyObscured is generated.
VisibilityNotify events are never generated on InputOnly windows.
All VisibilityNotify events caused by a hierarchy change are generated after any hierarchy event caused by that change (for example, UnmapNotify, MapNotify, ConfigureNotify, GravityNotify, CirculateNotify). Any VisibilityNotify event on a given window is generated before any Expose events on that window, but it is not required that all VisibilityNotify events on all windows be generated before all Expose events on all windows. The ordering of VisibilityNotify events with respect to FocusOut, EnterNotify, and LeaveNotify events is not constrained.
| CreateNotify |
| parent, window: WINDOW |
| x, y: INT16 |
| width, height, border-width: CARD16 |
| override-redirect: BOOL |
This event is reported to clients selecting SubstructureNotify on the parent and is generated when the window is created. The arguments are as in the CreateWindow request.
| DestroyNotify |
| event, window: WINDOW |
This event is reported to clients selecting StructureNotify on the window and to clients selecting SubstructureNotify on the parent. It is generated when the window is destroyed. The event is the window on which the event was generated, and the window is the window that is destroyed.
The ordering of the DestroyNotify events is such that for any given window, DestroyNotify is generated on all inferiors of the window before being generated on the window itself. The ordering among siblings and across subhierarchies is not otherwise constrained.
| UnmapNotify |
| event, window: WINDOW |
| from-configure: BOOL |
This event is reported to clients selecting StructureNotify on the window and to clients selecting SubstructureNotify on the parent. It is generated when the window changes state from mapped to unmapped. The event is the window on which the event was generated, and the window is the window that is unmapped. The from-configure flag is True if the event was generated as a result of the window's parent being resized when the window itself had a win-gravity of Unmap.
| MapNotify |
| event, window: WINDOW |
| override-redirect: BOOL |
This event is reported to clients selecting StructureNotify on the window and to clients selecting SubstructureNotify on the parent. It is generated when the window changes state from unmapped to mapped. The event is the window on which the event was generated, and the window is the window that is mapped. The override-redirect flag is from the window's attribute.
| MapRequest |
| parent, window: WINDOW |
This event is reported to the client selecting SubstructureRedirect on the parent and is generated when a MapWindow request is issued on an unmapped window with an override-redirect attribute of False.
| ReparentNotify |
| event, window, parent: WINDOW |
| x, y: INT16 |
| override-redirect: BOOL |
This event is reported to clients selecting SubstructureNotify on either the old or the new parent and to clients selecting StructureNotify on the window. It is generated when the window is reparented. The event is the window on which the event was generated. The window is the window that has been rerooted. The parent specifies the new parent. The x and y coordinates are relative to the new parent's origin and specify the position of the upper-left outer corner of the window. The override-redirect flag is from the window's attribute.
| ConfigureNotify |
| event, window: WINDOW |
| x, y: INT16 |
| width, height, border-width: CARD16 |
| above-sibling: WINDOW or None |
| override-redirect: BOOL |
This event is reported to clients selecting StructureNotify on the window and to clients selecting SubstructureNotify on the parent. It is generated when a ConfigureWindow request actually changes the state of the window. The event is the window on which the event was generated, and the window is the window that is changed. The x and y coordinates are relative to the new parent's origin and specify the position of the upper-left outer corner of the window. The width and height specify the inside size, not including the border. If above-sibling is None, then the window is on the bottom of the stack with respect to siblings. Otherwise, the window is immediately on top of the specified sibling. The override-redirect flag is from the window's attribute.
| GravityNotify |
| event, window: WINDOW |
| x, y: INT16 |
This event is reported to clients selecting SubstructureNotify on the parent and to clients selecting StructureNotify on the window. It is generated when a window is moved because of a change in size of the parent. The event is the window on which the event was generated, and the window is the window that is moved. The x and y coordinates are relative to the new parent's origin and specify the position of the upper-left outer corner of the window.
| ResizeRequest |
| window: WINDOW |
| width, height: CARD16 |
This event is reported to the client selecting ResizeRedirect on the window and is generated when a ConfigureWindow request by some other client on the window attempts to change the size of the window. The width and height are the requested inside size, not including the border.
| ConfigureRequest |
| parent, window: WINDOW |
| x, y: INT16 |
| width, height, border-width: CARD16 |
| sibling: WINDOW or None |
| stack-mode: { Above, Below, TopIf, BottomIf, Opposite} |
| value-mask: BITMASK |
This event is reported to the client selecting SubstructureRedirect on the parent and is generated when a ConfigureWindow request is issued on the window by some other client. The value-mask indicates which components were specified in the request. The value-mask and 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 sibling and stack-mode, which are reported as None and Above (respectively) if not given in the request.
| CirculateNotify |
| event, window: WINDOW |
| place: { Top, Bottom} |
This event is reported to clients selecting StructureNotify on the window and to clients selecting SubstructureNotify on the parent. It is generated when the window is actually restacked from a CirculateWindow request. The event is the window on which the event was generated, and the window is the window that is restacked. If place is Top, the window is now on top of all siblings. Otherwise, it is below all siblings.
| CirculateRequest |
| parent, window: WINDOW |
| place: { Top, Bottom} |
This event is reported to the client selecting SubstructureRedirect on the parent and is generated when a CirculateWindow request is issued on the parent and a window actually needs to be restacked. The window specifies the window to be restacked, and the place specifies what the new position in the stacking order should be.
| PropertyNotify |
| window: WINDOW |
| atom: ATOM |
| state: { NewValue, Deleted} |
| time: TIMESTAMP |
This event is reported to clients selecting PropertyChange on the window and is generated with state NewValue when a property of the window is changed using ChangeProperty or RotateProperties, even when adding zero-length data using ChangeProperty and when replacing all or part of a property with identical data using ChangeProperty or RotateProperties. It is generated with state Deleted when a property of the window is deleted using request DeleteProperty or GetProperty. The timestamp indicates the server time when the property was changed.
| SelectionClear |
| owner: WINDOW |
| selection: ATOM |
| time: TIMESTAMP |
This event is reported to the current owner of a selection and is generated when a new owner is being defined by means of SetSelectionOwner. The timestamp is the last-change time recorded for the selection. The owner argument is the window that was specified by the current owner in its SetSelectionOwner request.
| SelectionRequest |
| owner: WINDOW |
| selection: ATOM |
| target: ATOM |
| property: ATOM or None |
| requestor: WINDOW |
| time: TIMESTAMP or CurrentTime |
This event is reported to the owner of a selection and is generated when a client issues a ConvertSelection request. The owner argument is the window that was specified in the SetSelectionOwner request. The remaining arguments are as in the ConvertSelection request.
The owner should convert the selection based on the specified target type and send a SelectionNotify back to the requestor. A complete specification for using selections is given in the X.Org standard Inter-Client Communication Conventions Manual.
| SelectionNotify |
| requestor: WINDOW |
| selection, target: ATOM |
| property: ATOM or None |
| time: TIMESTAMP or CurrentTime |
This event is generated by the server in response to a ConvertSelection request when there is no owner for the selection. When there is an owner, it should be generated by the owner using SendEvent. The owner of a selection should send this event to a requestor either when a selection has been converted and stored as a property or when a selection conversion could not be performed (indicated with property None).
| ColormapNotify |
| window: WINDOW |
| colormap: COLORMAP or None |
| new: BOOL |
| state: { Installed, Uninstalled} |
This event is reported to clients selecting ColormapChange on the window. It is generated with value True for new when the colormap attribute of the window is changed and is generated with value False for new when the colormap of a window is installed or uninstalled. In either case, the state indicates whether the colormap is currently installed.
| MappingNotify |
| request: { Modifier, Keyboard, Pointer} |
| first-keycode, count: CARD8 |
This event is sent to all clients. There is no mechanism to express disinterest in this event. The detail indicates the kind of change that occurred: Modifiers for a successful SetModifierMapping, Keyboard for a successful ChangeKeyboardMapping, and Pointer for a successful SetPointerMapping. If the detail is Keyboard, then first-keycode and count indicate the range of altered keycodes.
| ClientMessage |
| window: WINDOW |
| type: ATOM |
| format: {8, 16, 32} |
| data: LISTofINT8 or LISTofINT16 or LISTofINT32 |
This event is only generated by clients using SendEvent. The type specifies how the data is to be interpreted by the receiving client; the server places no interpretation on the type or the data. The format specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities, so that the server can correctly byte-swap, as necessary. The data always consists of either 20 8-bit values or 10 16-bit values or 5 32-bit values, although particular message types might not make use of all of these values.