# Events

A client application communicates with the X server through the connection you establish with the XOpenDisplay function. A client application sends requests to the X server over this connection. These requests are made by the Xlib functions that are called in the client application. Many Xlib functions cause the X server to generate events, and the user’s typing or moving the pointer can generate events asynchronously. The X server returns events to the client on the same connection.

This chapter discusses the following topics associated with events:

- Event types

- Event structures

- Event masks

- Event processing

Functions for handling events are dealt with in the next chapter.

## Event Types

An event is data generated asynchronously by the X server as a result of some device activity or as side effects of a request sent by an Xlib function. Device-related events propagate from the source window to ancestor windows until some client application has selected that event type or until the event is explicitly discarded. The X server generally sends an event to a client application only if the client has specifically asked to be informed of that event type, typically by setting the event-mask attribute of the window. The mask can also be set when you create a window or by changing the window's event-mask. You can also mask out events that would propagate to ancestor windows by manipulating the do-not-propagate mask of the window's attributes. However, MappingNotify events are always sent to all clients.

Event types
Event
Input Control
Output Control

An event type describes a specific event generated by the X server. For each event type, a corresponding constant name is defined in `<X11/X.h>`, which is used when referring to an event type. The following table lists the event category and its associated event type or types. The processing associated with these events is discussed in section 10.5.

X11/X.h
Files <X11/X.h>
Headers <X11/X.h>
Event categories

Event Category | Event Type
--- | ---
Keyboard events | KeyPress, KeyRelease
Pointer events | ButtonPress, ButtonRelease, MotionNotify
Window crossing events | EnterNotify, LeaveNotify
Input focus events | FocusIn, FocusOut
Keymap state notification event | KeymapNotify
Exposure events | Expose, GraphicsExpose, NoExpose
Structure control events | CirculateRequest, ConfigureRequest, MapRequest, ResizeRequest
Window state notification events | CirculateNotify, ConfigureNotify, CreateNotify, DestroyNotify, GravityNotify, MapNotify, MappingNotify, ReparentNotify, UnmapNotify, VisibilityNotify
Colormap state notification event | ColormapNotify
Client communication events | ClientMessage, PropertyNotify, SelectionClear, SelectionNotify, SelectionRequest

## Event Structures

For each event type, a corresponding structure is declared in `<X11/Xlib.h>`. All the event structures have the following common members:

X11/Xlib.h
Files <X11/Xlib.h>
Headers <X11/Xlib.h>

    typedef struct {
         int           type;
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        window;
    } XAnyEvent;

XAnyEvent

The type member is set to the event type constant name that uniquely identifies it. For example, when the X server reports a GraphicsExpose event to a client application, it sends an XGraphicsExposeEvent structure with the type member set to GraphicsExpose. The display member is set to a pointer to the display the event was read on. The send_event member is set to True if the event came from a SendEvent protocol request. The serial member is set from the serial number reported in the protocol but expanded from the 16-bit least-significant bits to a full 32-bit value. The window member is set to the window that is most useful to toolkit dispatchers.

The X server can send events at any time in the input stream. Xlib stores any events received while waiting for a reply in an event queue for later use. Xlib also provides functions that allow you to check events in the event queue (see section 11.3).

In addition to the individual structures declared for each event type, the XEvent structure is a union of the individual structures declared for each event type. Depending on the type, you should access members of each event by using the XEvent union.

XEvent

    typedef union _XEvent {
         int                            type;          /* must not be changed */
         XAnyEvent                      xany;
         XKeyEvent                      xkey;
         XButtonEvent                   xbutton;
         XMotionEvent                   xmotion;
         XCrossingEvent                 xcrossing;
         XFocusChangeEvent              xfocus;
         XExposeEvent                   xexpose;
         XGraphicsExposeEvent           xgraphicsexpose;
         XNoExposeEvent                 xnoexpose;
         XVisibilityEvent               xvisibility;
         XCreateWindowEvent             xcreatewindow;
         XDestroyWindowEvent            xdestroywindow;
         XUnmapEvent                    xunmap;
         XMapEvent                      xmap;
         XMapRequestEvent               xmaprequest;
         XReparentEvent                 xreparent;
         XConfigureEvent                xconfigure;
         XGravityEvent                  xgravity;
         XResizeRequestEvent            xresizerequest;
         XConfigureRequestEvent         xconfigurerequest;
         XCirculateEvent                xcirculate;
         XCirculateRequestEvent         xcirculaterequest;
         XPropertyEvent                 xproperty;
         XSelectionClearEvent           xselectionclear;
         XSelectionRequestEvent         xselectionrequest;
         XSelectionEvent                xselection;
         XColormapEvent                 xcolormap;
         XClientMessageEvent            xclient;
         XMappingEvent                  xmapping;
         XErrorEvent                    xerror;
         XKeymapEvent                   xkeymap;
         long                           pad[24];
    } XEvent;

An XEvent structure's first entry always is the type member, which is set to the event type. The second member always is the serial number of the protocol request that generated the event. The third member always is send_event, which is a Bool that indicates if the event was sent by a different client. The fourth member always is a display, which is the display that the event was read from. Except for keymap events, the fifth member always is a window, which has been carefully selected to be useful to toolkit dispatchers. To avoid breaking toolkits, the order of these first five entries is not to change. Most events also contain a time member, which is the time at which an event occurred. In addition, a pointer to the generic event must be cast before it is used to access any other information in the structure.

## Event Masks

Clients select event reporting of most events relative to a window. To do this, pass an event mask to an Xlib event-handling function that takes an event_mask argument. The bits of the event mask are defined in `<X11/X.h>`. Each bit in the event mask maps to an event mask name, which describes the event or events you want the X server to return to a client application.

Event mask
X11/X.h
Files <X11/X.h>
Headers <X11/X.h>

Unless the client has specifically asked for them, most events are not reported to clients when they are generated. Unless the client suppresses them by setting graphics-exposures in the GC to False, GraphicsExpose and NoExpose are reported by default as a result of and . SelectionClear, SelectionRequest, SelectionNotify, or ClientMessage cannot be masked. Selection-related events are only sent to clients cooperating with selections (see section 4.5). When the keyboard or pointer mapping is changed, MappingNotify is always sent to clients.

The following table lists the event mask constants you can pass to the event_mask argument and the circumstances in which you would want to specify the event mask:

Event Mask | Circumstances
--- | ---
NoEventMask | No events wanted
KeyPressMask | Keyboard down events wanted
KeyReleaseMask | Keyboard up events wanted
ButtonPressMask | Pointer button down events wanted
ButtonReleaseMask | Pointer button up events wanted
EnterWindowMask | Pointer window entry events wanted
LeaveWindowMask | Pointer window leave events wanted
PointerMotionMask | Pointer motion events wanted
PointerMotionHintMask | Pointer motion hints wanted
Button1MotionMask | Pointer motion while button 1 down
Button2MotionMask | Pointer motion while button 2 down
Button3MotionMask | Pointer motion while button 3 down
Button4MotionMask | Pointer motion while button 4 down
Button5MotionMask | Pointer motion while button 5 down
ButtonMotionMask | Pointer motion while any button down
KeymapStateMask | Keyboard state wanted at window entry and focus in
ExposureMask | Any exposure wanted
VisibilityChangeMask | Any change in visibility wanted
StructureNotifyMask | Any change in window structure wanted
ResizeRedirectMask | Redirect resize of this window
SubstructureNotifyMask | Substructure notification wanted
SubstructureRedirectMask | Redirect structure requests on children
FocusChangeMask | Any change in input focus wanted
PropertyChangeMask | Any change in property wanted
ColormapChangeMask | Any change in colormap wanted
OwnerGrabButtonMask | Automatic grabs should activate with owner_events set to True

## Event Processing Overview

The event reported to a client application during event processing depends on which event masks you provide as the event-mask attribute for a window. For some event masks, there is a one-to-one correspondence between the event mask constant and the event type constant. For example, if you pass the event mask ButtonPressMask, the X server sends back only ButtonPress events. Most events contain a time member, which is the time at which an event occurred.

CurrentTime

In other cases, one event mask constant can map to several event type constants. For example, if you pass the event mask SubstructureNotifyMask, the X server can send back CirculateNotify, ConfigureNotify, CreateNotify, DestroyNotify, GravityNotify, MapNotify, ReparentNotify, or UnmapNotify events.

In another case, two event masks can map to one event type. For example, if you pass either PointerMotionMask or ButtonMotionMask, the X server sends back a MotionNotify event.

The following table lists the event mask, its associated event type or types, and the structure name associated with the event type. Some of these structures actually are typedefs to a generic structure that is shared between two event types. Note that N.A. appears in columns for which the information is not applicable.

Event Mask | Event Type | Structure | Generic Structure
--- | --- | --- | ---
ButtonMotionMask Button1MotionMask Button2MotionMask Button3MotionMask Button4MotionMask Button5MotionMask | MotionNotify | XPointerMovedEvent | XMotionEvent
ButtonPressMask | ButtonPress | XButtonPressedEvent | XButtonEvent
ButtonReleaseMask | ButtonRelease | XButtonReleasedEvent | XButtonEvent
ColormapChangeMask | ColormapNotify | XColormapEvent
EnterWindowMask | EnterNotify | XEnterWindowEvent | XCrossingEvent
LeaveWindowMask | LeaveNotify | XLeaveWindowEvent | XCrossingEvent
ExposureMask | Expose | XExposeEvent
GCGraphicsExposures in GC | GraphicsExpose | XGraphicsExposeEvent
NoExpose | XNoExposeEvent
FocusChangeMask | FocusIn | XFocusInEvent | XFocusChangeEvent
FocusOut | XFocusOutEvent | XFocusChangeEvent
KeymapStateMask | KeymapNotify | XKeymapEvent
KeyPressMask | KeyPress | XKeyPressedEvent | XKeyEvent
KeyReleaseMask | KeyRelease | XKeyReleasedEvent | XKeyEvent
OwnerGrabButtonMask | N.A. | N.A.
PointerMotionMask | MotionNotify | XPointerMovedEvent | XMotionEvent
PointerMotionHintMask | N.A. | N.A.
PropertyChangeMask | PropertyNotify | XPropertyEvent
ResizeRedirectMask | ResizeRequest | XResizeRequestEvent
StructureNotifyMask | CirculateNotify | XCirculateEvent
ConfigureNotify | XConfigureEvent
DestroyNotify | XDestroyWindowEvent
GravityNotify | XGravityEvent
MapNotify | XMapEvent
ReparentNotify | XReparentEvent
UnmapNotify | XUnmapEvent
SubstructureNotifyMask | CirculateNotify | XCirculateEvent
ConfigureNotify | XConfigureEvent
CreateNotify | XCreateWindowEvent
DestroyNotify | XDestroyWindowEvent
GravityNotify | XGravityEvent
MapNotify | XMapEvent
ReparentNotify | XReparentEvent
UnmapNotify | XUnmapEvent
SubstructureRedirectMask | CirculateRequest | XCirculateRequestEvent
ConfigureRequest | XConfigureRequestEvent
MapRequest | XMapRequestEvent
N.A. | ClientMessage | XClientMessageEvent
N.A. | MappingNotify | XMappingEvent
N.A. | SelectionClear | XSelectionClearEvent
N.A. | SelectionNotify | XSelectionEvent
N.A. | SelectionRequest | XSelectionRequestEvent
VisibilityChangeMask | VisibilityNotify | XVisibilityEvent

The sections that follow describe the processing that occurs when you select the different event masks. The sections are organized according to these processing categories:

- Keyboard and pointer events

- Window crossing events

- Input focus events

- Keymap state notification events

- Exposure events

- Window state notification events

- Structure control events

- Colormap state notification events

- Client communication events

## Keyboard and Pointer Events

This section discusses:

- Pointer button events

- Keyboard and pointer events

### Pointer Button Events

The following describes the event processing that occurs when a pointer button press is processed with the pointer in some window w and when no active pointer grab is in progress.

The X server searches the ancestors of w from the root down, looking for a passive grab to activate. If no matching passive grab on the button exists, the X server automatically starts an active grab for the client receiving the event and sets the last-pointer-grab time to the current server time. The effect is essentially equivalent to an with these client passed arguments:

Argument | Value
--- | ---
w | The event window
event_mask | The client's selected pointer events on the event window
pointer_mode | GrabModeAsync
keyboard_mode | GrabModeAsync
owner_events | True, if the client has selected OwnerGrabButtonMask on the event window, otherwise False
confine_to | None
cursor | None

The active grab is automatically terminated when the logical state of the pointer has all buttons released. Clients can modify the active grab by calling and .

### Keyboard and Pointer Events

This section discusses the processing that occurs for the keyboard events KeyPress and KeyRelease and the pointer events ButtonPress, ButtonRelease, and MotionNotify. For information about the keyboard event-handling utilities, see chapter 11.

Events ButtonPress
Events ButtonRelease
Events KeyPress
Events KeyRelease
Events MotionNotify

The X server reports KeyPress or KeyRelease events to clients wanting information about keys that logically change state. Note that these events are generated for all keys, even those mapped to modifier bits. The X server reports ButtonPress or ButtonRelease events to clients wanting information about buttons that logically change state.

KeyPress
KeyRelease
ButtonPress
ButtonRelease

The X server reports MotionNotify events to clients wanting information about when the pointer logically moves. The X server generates this event whenever the pointer is moved and the pointer motion begins and ends in the window. The granularity of MotionNotify events is not guaranteed, but a client that selects this event type is guaranteed to receive at least one event when the pointer moves and then rests.

MotionNotify

The generation of the logical changes lags the physical changes if device event processing is frozen.

To receive KeyPress, KeyRelease, ButtonPress, and ButtonRelease events, set KeyPressMask, KeyReleaseMask, ButtonPressMask, and ButtonReleaseMask bits in the event-mask attribute of the window.

To receive MotionNotify events, set one or more of the following event masks bits in the event-mask attribute of the window.

- Button1MotionMask - Button5MotionMask

- The client application receives MotionNotify events only when one or more of the specified buttons is pressed.

- ButtonMotionMask

- The client application receives MotionNotify events only when at least one button is pressed.

- PointerMotionMask

- The client application receives MotionNotify events independent of the state of the pointer buttons.

- PointerMotionHintMask

- If PointerMotionHintMask is selected in combination with one or more of the above masks, the X server is free to send only one MotionNotify event (with the is_hint member of the XPointerMovedEvent structure set to NotifyHint) to the client for the event window, until either the key or button state changes, the pointer leaves the event window, or the client calls or . The server still may send MotionNotify events without is_hint set to NotifyHint.

The source of the event is the viewable window that the pointer is in. The window used by the X server to report these events depends on the window's position in the window hierarchy and whether any intervening window prohibits the generation of these events. Starting with the source window, the X server searches up the window hierarchy until it locates the first window specified by a client as having an interest in these events. If one of the intervening windows has its do-not-propagate-mask set to prohibit generation of the event type, the events of those types will be suppressed. Clients can modify the actual window used for reporting by performing active grabs and, in the case of keyboard events, by using the focus window.

The structures for these event types contain:

    typedef struct {
         int            type;            /* ButtonPress or ButtonRelease */
         unsigned long  serial;          /* # of last request processed by server */
         Bool           send_event;      /* true if this came from a SendEvent request */
         Display        *display;        /* Display the event was read from */
         Window         window;          /* ``event'' window it is reported relative to */
         Window         root;            /* root window that the event occurred on */
         Window         subwindow;       /* child window */
         Time           time;            /* milliseconds */
         int            x, y;            /* pointer x, y coordinates in event window */
         int            x_root, y_root;  /* coordinates relative to root */
         unsigned int   state;           /* key or button mask */
         unsigned int   button;          /* detail */
         Bool           same_screen;     /* same screen flag */
    } XButtonEvent;
    typedef XButtonEvent XButtonPressedEvent;
    typedef XButtonEvent XButtonReleasedEvent;

    typedef struct {
         int            type;            /* KeyPress or KeyRelease */
         unsigned long  serial;          /* # of last request processed by server */
         Bool           send_event;      /* true if this came from a SendEvent request */
         Display        *display;        /* Display the event was read from */
         Window         window;          /* ``event'' window it is reported relative to */
         Window         root;            /* root window that the event occurred on */
         Window         subwindow;       /* child window */
         Time           time;            /* milliseconds */
         int            x, y;            /* pointer x, y coordinates in event window */
         int            x_root, y_root;  /* coordinates relative to root */
         unsigned int   state;           /* key or button mask */
         unsigned int   keycode;         /* detail */
         Bool           same_screen;     /* same screen flag */
    } XKeyEvent;
    typedef XKeyEvent XKeyPressedEvent;
    typedef XKeyEvent XKeyReleasedEvent;

    typedef struct {
         int            type;              /* MotionNotify */
         unsigned long  serial;            /* # of last request processed by server */
         Bool           send_event;        /* true if this came from a SendEvent request */
         Display        *display;          /* Display the event was read from */
         Window         window;            /* ``event'' window reported relative to */
         Window         root;              /* root window that the event occurred on */
         Window         subwindow;         /* child window */
         Time           time;              /* milliseconds */
         int            x, y;              /* pointer x, y coordinates in event window */
         int            x_root, y_root;    /* coordinates relative to root */
         unsigned int   state;             /* key or button mask */
         char           is_hint;           /* detail */
         Bool           same_screen;       /* same screen flag */
    } XMotionEvent;
    typedef XMotionEvent XPointerMovedEvent;

These structures have the following common members: window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen. The window member is set to the window on which the event was generated and is referred to as the event window. As long as the conditions previously discussed are met, this is the window used by the X server to report the event. The root member is set to the source window's root window. The x_root and y_root members are set to the pointer's coordinates relative to the root window's origin at the time of the event.

The same_screen member is set to indicate whether the event window is on the same screen as the root window and can be either True or False. If True, the event and root windows are on the same screen. If False, the event and root windows are not on the same screen.

If the source window is an inferior of the event window, the subwindow member of the structure is set to 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, the X server sets the subwindow member to None. The time member is set to the time when the event was generated and is expressed in milliseconds.

If the event window is on the same screen as the root window, the x and y members are set to the coordinates relative to the event window's origin. Otherwise, these members are set to zero.

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: Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.

Each of these structures also has a member that indicates the detail. For the XKeyPressedEvent and XKeyReleasedEvent structures, this member is called a keycode. It is set to a number that represents a physical key on the keyboard. The keycode is an arbitrary representation for any key on the keyboard (see sections 12.7 and 16.1).

For the XButtonPressedEvent and XButtonReleasedEvent structures, this member is called button. It represents the pointer button that changed state and can be the Button1, Button2, Button3, Button4, or Button5 value. For the XPointerMovedEvent structure, this member is called is_hint. It can be set to NotifyNormal or NotifyHint.

Some of the symbols mentioned in this section have fixed values, as follows:

Symbol | Value
--- | ---
Button1MotionMask | (1L<<8)
Button2MotionMask | (1L<<9)
Button3MotionMask | (1L<<10)
Button4MotionMask | (1L<<11)
Button5MotionMask | (1L<<12)
Button1Mask | (1<<8)
Button2Mask | (1<<9)
Button3Mask | (1<<10)
Button4Mask | (1<<11)
Button5Mask | (1<<12)
ShiftMask | (1<<0)
LockMask | (1<<1)
ControlMask | (1<<2)
Mod1Mask | (1<<3)
Mod2Mask | (1<<4)
Mod3Mask | (1<<5)
Mod4Mask | (1<<6)
Mod5Mask | (1<<7)
Button1 | 1
Button2 | 2
Button3 | 3
Button4 | 4
Button5 | 5

## Window Entry/Exit Events

This section describes the processing that occurs for the window crossing events EnterNotify and LeaveNotify. If a pointer motion or a window hierarchy change causes the pointer to be in a different window than before, the X server reports EnterNotify or LeaveNotify events to clients who have selected for these events. All EnterNotify and LeaveNotify events caused by a hierarchy change are generated after any hierarchy event (UnmapNotify, MapNotify, ConfigureNotify, GravityNotify, CirculateNotify) caused by that change; however, the X protocol does not constrain the ordering of EnterNotify and LeaveNotify events with respect to FocusOut, VisibilityNotify, and Expose events.

Events EnterNotify
Events LeaveNotify
EnterNotify
LeaveNotify

This contrasts with MotionNotify events, which are also generated when the pointer moves but only when the pointer motion begins and ends in a single window. An EnterNotify or LeaveNotify event also can be generated when some client application calls and .

To receive EnterNotify or LeaveNotify events, set the EnterWindowMask or LeaveWindowMask bits of the event-mask attribute of the window.

The structure for these event types contains:

    typedef struct {
         int           type;           /* EnterNotify or LeaveNotify */
         unsigned long serial;         /* # of last request processed by server */
         Bool          send_event;     /* true if this came from a SendEvent request */
         Display       *display;       /* Display the event was read from */
         Window        window;         /* ``event'' window reported relative to */
         Window        root;           /* root window that the event occurred on */
         Window        subwindow;      /* child window */
         Time          time;           /* milliseconds */
         int           x, y;           /* pointer x, y coordinates in event window */
         int           x_root, y_root; /* coordinates relative to root */
         int           mode;           /* NotifyNormal, NotifyGrab, NotifyUngrab */
         int           detail;
                       /*
                        * NotifyAncestor, NotifyVirtual, NotifyInferior,
                        * NotifyNonlinear,NotifyNonlinearVirtual
                        */
         Bool          same_screen;    /* same screen flag */
         Bool          focus;          /* boolean focus */
         unsigned int  state;          /* key or button mask */
    } XCrossingEvent;
    typedef XCrossingEvent XEnterWindowEvent;
    typedef XCrossingEvent XLeaveWindowEvent;

The window member is set to the window on which the EnterNotify or LeaveNotify event was generated and is referred to as the event window. This is the window used by the X server to report the event, and is relative to the root window on which the event occurred. The root member is set to the root window of the screen on which the event occurred.

For a LeaveNotify event, if a child of the event window contains the initial position of the pointer, the subwindow component is set to that child. Otherwise, the X server sets the subwindow member to None. For an EnterNotify event, if a child of the event window contains the final pointer position, the subwindow component is set to that child or None.

The time member is set to the time when the event was generated and is expressed in milliseconds. 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. The x_root and y_root members are set to the pointer's coordinates relative to the root window's origin at the time of the event.

The same_screen member is set to indicate whether the event window is on the same screen as the root window and can be either True or False. If True, the event and root windows are on the same screen. If False, the event and root windows are not on the same screen.

The focus member is set to indicate whether the event window is the focus window or an inferior of the focus window. The X server can set this member to either True or False. If True, the event window is the focus window or an inferior of the focus window. If False, the event window is not the focus window or an inferior of the focus window.

The state member is set to indicate the state of the pointer buttons and modifier keys just prior to the event. The X server can set this member to the bitwise inclusive OR of one or more of the button or modifier key masks: Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask.

The mode member is set to indicate whether the events are normal events, pseudo-motion events when a grab activates, or pseudo-motion events when a grab deactivates. The X server can set this member to NotifyNormal, NotifyGrab, or NotifyUngrab.

The detail member is set to indicate the notify detail and can be NotifyAncestor, NotifyVirtual, NotifyInferior, NotifyNonlinear, or NotifyNonlinearVirtual.

### Normal Entry/Exit Events

EnterNotify and LeaveNotify events are generated when the pointer moves from one window to another window. Normal events are identified by XEnterWindowEvent or XLeaveWindowEvent structures whose mode member is set to NotifyNormal.

- When the pointer moves from window A to window B and A is an inferior of B, the X server does the following:

- It generates a LeaveNotify event on window A, with the detail member of the XLeaveWindowEvent structure set to NotifyAncestor.

- It generates a LeaveNotify event on each window between window A and window B, exclusive, with the detail member of each XLeaveWindowEvent structure set to NotifyVirtual.

- It generates an EnterNotify event on window B, with the detail member of the XEnterWindowEvent structure set to NotifyInferior.

- When the pointer moves from window A to window B and B is an inferior of A, the X server does the following:

- It generates a LeaveNotify event on window A, with the detail member of the XLeaveWindowEvent structure set to NotifyInferior.

- It generates an EnterNotify event on each window between window A and window B, exclusive, with the detail member of each XEnterWindowEvent structure set to NotifyVirtual.

- It generates an EnterNotify event on window B, with the detail member of the XEnterWindowEvent structure set to NotifyAncestor.

- When the pointer moves from window A to window B and window C is their least common ancestor, the X server does the following:

- It generates a LeaveNotify event on window A, with the detail member of the XLeaveWindowEvent structure set to NotifyNonlinear.

- It generates a LeaveNotify event on each window between window A and window C, exclusive, with the detail member of each XLeaveWindowEvent structure set to NotifyNonlinearVirtual.

- It generates an EnterNotify event on each window between window C and window B, exclusive, with the detail member of each XEnterWindowEvent structure set to NotifyNonlinearVirtual.

- It generates an EnterNotify event on window B, with the detail member of the XEnterWindowEvent structure set to NotifyNonlinear.

- When the pointer moves from window A to window B on different screens, the X server does the following:

- It generates a LeaveNotify event on window A, with the detail member of the XLeaveWindowEvent structure set to NotifyNonlinear.

- If window A is not a root window, it generates a LeaveNotify event on each window above window A up to and including its root, with the detail member of each XLeaveWindowEvent structure set to NotifyNonlinearVirtual.

- If window B is not a root window, it generates an EnterNotify event on each window from window B's root down to but not including window B, with the detail member of each XEnterWindowEvent structure set to NotifyNonlinearVirtual.

- It generates an EnterNotify event on window B, with the detail member of the XEnterWindowEvent structure set to NotifyNonlinear.

### Grab and Ungrab Entry/Exit Events

Pseudo-motion mode EnterNotify and LeaveNotify events are generated when a pointer grab activates or deactivates. Events in which the pointer grab activates are identified by XEnterWindowEvent or XLeaveWindowEvent structures whose mode member is set to NotifyGrab. Events in which the pointer grab deactivates are identified by XEnterWindowEvent or XLeaveWindowEvent structures whose mode member is set to NotifyUngrab (see ).

- When a pointer grab activates 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, the X server does the following:

- It generates EnterNotify and LeaveNotify events (see section 10.6.1) with the mode members of the XEnterWindowEvent and XLeaveWindowEvent structures set to NotifyGrab. These events are generated 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 X server uses the pointer position as both the initial and final positions for the events.

- When a pointer grab deactivates 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, the X server does the following:

- It generates EnterNotify and LeaveNotify events (see section 10.6.1) with the mode members of the XEnterWindowEvent and XLeaveWindowEvent structures set to NotifyUngrab. These events are generated 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 X server uses the current pointer position as both the initial and final positions for the events.

XCrossingEvent
XEnterWindowEvent
XLeaveWindowEvent

## Input Focus Events

This section describes the processing that occurs for the input focus events FocusIn and FocusOut. The X server can report FocusIn or FocusOut events to clients wanting information about when the input focus changes. The keyboard is always attached to some window (typically, the root window or a top-level window), which is called the focus window. The focus window and the position of the pointer determine the window that receives keyboard input. Clients may need to know when the input focus changes to control highlighting of areas on the screen.

Events FocusIn
Events FocusOut
FocusIn
FocusOut

To receive FocusIn or FocusOut events, set the FocusChangeMask bit in the event-mask attribute of the window.

The structure for these event types contains:

    typedef struct {
         int           type;       /* FocusIn or FocusOut */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        window;     /* window of event */
         int           mode;       /* NotifyNormal, NotifyGrab, NotifyUngrab */
         int           detail;
                       /*
                        * NotifyAncestor, NotifyVirtual, NotifyInferior,
                        * NotifyNonlinear,NotifyNonlinearVirtual, NotifyPointer,
                        * NotifyPointerRoot, NotifyDetailNone
                        */
    } XFocusChangeEvent;
    typedef XFocusChangeEvent XFocusInEvent;
    typedef XFocusChangeEvent XFocusOutEvent;

The window member is set to the window on which the FocusIn or FocusOut event was generated. This is the window used by the X server to report the event. The mode member is set to indicate whether the focus events are normal focus events, focus events while grabbed, focus events when a grab activates, or focus events when a grab deactivates. The X server can set the mode member to NotifyNormal, NotifyWhileGrabbed, NotifyGrab, or NotifyUngrab.

All FocusOut events caused by a window unmap are generated after any UnmapNotify event; however, the X protocol does not constrain the ordering of FocusOut events with respect to generated EnterNotify, LeaveNotify, VisibilityNotify, and Expose events.

Depending on the event mode, the detail member is set to indicate the notify detail and can be NotifyAncestor, NotifyVirtual, NotifyInferior, NotifyNonlinear, NotifyNonlinearVirtual, NotifyPointer, NotifyPointerRoot, or NotifyDetailNone.

### Normal Focus Events and Focus Events While Grabbed

Normal focus events are identified by XFocusInEvent or XFocusOutEvent structures whose mode member is set to NotifyNormal. Focus events while grabbed are identified by XFocusInEvent or XFocusOutEvent structures whose mode member is set to NotifyWhileGrabbed. The X server processes normal focus and focus events while grabbed according to the following:

- When the focus moves from window A to window B, A is an inferior of B, and the pointer is in window P, the X server does the following:

- It generates a FocusOut event on window A, with the detail member of the XFocusOutEvent structure set to NotifyAncestor.

- It generates a FocusOut event on each window between window A and window B, exclusive, with the detail member of each XFocusOutEvent structure set to NotifyVirtual.

- It generates a FocusIn event on window B, with the detail member of the XFocusOutEvent structure set to NotifyInferior.

- If window P is an inferior of window B but window P is not window A or an inferior or ancestor of window A, it generates a FocusIn event on each window below window B, down to and including window P, with the detail member of each XFocusInEvent structure set to NotifyPointer.

- When the focus moves from window A to window B, B is an inferior of A, and the pointer is in window P, the X server does the following:

- If window P is an inferior of window A but P is not an inferior of window B or an ancestor of B, it generates a FocusOut event on each window from window P up to but not including window A, with the detail member of each XFocusOutEvent structure set to NotifyPointer.

- It generates a FocusOut event on window A, with the detail member of the XFocusOutEvent structure set to NotifyInferior.

- It generates a FocusIn event on each window between window A and window B, exclusive, with the detail member of each XFocusInEvent structure set to NotifyVirtual.

- It generates a FocusIn event on window B, with the detail member of the XFocusInEvent structure set to NotifyAncestor.

- When the focus moves from window A to window B, window C is their least common ancestor, and the pointer is in window P, the X server does the following:

- If window P is an inferior of window A, it generates a FocusOut event on each window from window P up to but not including window A, with the detail member of the XFocusOutEvent structure set to NotifyPointer.

- It generates a FocusOut event on window A, with the detail member of the XFocusOutEvent structure set to NotifyNonlinear.

- It generates a FocusOut event on each window between window A and window C, exclusive, with the detail member of each XFocusOutEvent structure set to NotifyNonlinearVirtual.

- It generates a FocusIn event on each window between C and B, exclusive, with the detail member of each XFocusInEvent structure set to NotifyNonlinearVirtual.

- It generates a FocusIn event on window B, with the detail member of the XFocusInEvent structure set to NotifyNonlinear.

- If window P is an inferior of window B, it generates a FocusIn event on each window below window B down to and including window P, with the detail member of the XFocusInEvent structure set to NotifyPointer.

- When the focus moves from window A to window B on different screens and the pointer is in window P, the X server does the following:

- If window P is an inferior of window A, it generates a FocusOut event on each window from window P up to but not including window A, with the detail member of each XFocusOutEvent structure set to NotifyPointer.

- It generates a FocusOut event on window A, with the detail member of the XFocusOutEvent structure set to NotifyNonlinear.

- If window A is not a root window, it generates a FocusOut event on each window above window A up to and including its root, with the detail member of each XFocusOutEvent structure set to NotifyNonlinearVirtual.

- If window B is not a root window, it generates a FocusIn event on each window from window B's root down to but not including window B, with the detail member of each XFocusInEvent structure set to NotifyNonlinearVirtual.

- It generates a FocusIn event on window B, with the detail member of each XFocusInEvent structure set to NotifyNonlinear.

- If window P is an inferior of window B, it generates a FocusIn event on each window below window B down to and including window P, with the detail member of each XFocusInEvent structure set to NotifyPointer.

- When the focus moves from window A to PointerRoot (events sent to the window under the pointer) or None (discard), and the pointer is in window P, the X server does the following:

- If window P is an inferior of window A, it generates a FocusOut event on each window from window P up to but not including window A, with the detail member of each XFocusOutEvent structure set to NotifyPointer.

- It generates a FocusOut event on window A, with the detail member of the XFocusOutEvent structure set to NotifyNonlinear.

- If window A is not a root window, it generates a FocusOut event on each window above window A up to and including its root, with the detail member of each XFocusOutEvent structure set to NotifyNonlinearVirtual.

- It generates a FocusIn event on the root window of all screens, with the detail member of each XFocusInEvent structure set to NotifyPointerRoot (or NotifyDetailNone).

- If the new focus is PointerRoot, it generates a FocusIn event on each window from window P's root down to and including window P, with the detail member of each XFocusInEvent structure set to NotifyPointer.

- When the focus moves from PointerRoot (events sent to the window under the pointer) or None to window A, and the pointer is in window P, the X server does the following:

- If the old focus is PointerRoot, it generates a FocusOut event on each window from window P up to and including window P's root, with the detail member of each XFocusOutEvent structure set to NotifyPointer.

- It generates a FocusOut event on all root windows, with the detail member of each XFocusOutEvent structure set to NotifyPointerRoot (or NotifyDetailNone).

- If window A is not a root window, it generates a FocusIn event on each window from window A's root down to but not including window A, with the detail member of each XFocusInEvent structure set to NotifyNonlinearVirtual.

- It generates a FocusIn event on window A, with the detail member of the XFocusInEvent structure set to NotifyNonlinear.

- If window P is an inferior of window A, it generates a FocusIn event on each window below window A down to and including window P, with the detail member of each XFocusInEvent structure set to NotifyPointer.

- When the focus moves from PointerRoot (events sent to the window under the pointer) to None (or vice versa), and the pointer is in window P, the X server does the following:

- If the old focus is PointerRoot, it generates a FocusOut event on each window from window P up to and including window P's root, with the detail member of each XFocusOutEvent structure set to NotifyPointer.

- It generates a FocusOut event on all root windows, with the detail member of each XFocusOutEvent structure set to either NotifyPointerRoot or NotifyDetailNone.

- It generates a FocusIn event on all root windows, with the detail member of each XFocusInEvent structure set to NotifyDetailNone or NotifyPointerRoot.

- If the new focus is PointerRoot, it generates a FocusIn event on each window from window P's root down to and including window P, with the detail member of each XFocusInEvent structure set to NotifyPointer.

### Focus Events Generated by Grabs

Focus events in which the keyboard grab activates are identified by XFocusInEvent or XFocusOutEvent structures whose mode member is set to NotifyGrab. Focus events in which the keyboard grab deactivates are identified by XFocusInEvent or XFocusOutEvent structures whose mode member is set to NotifyUngrab (see ).

- When a keyboard grab activates before generating any actual KeyPress event that activates the grab, G is the grab_window, and F is the current focus, the X server does the following:

- It generates FocusIn and FocusOut events, with the mode members of the XFocusInEvent and XFocusOutEvent structures set to NotifyGrab. These events are generated as if the focus were to change from F to G.

- When a keyboard grab deactivates after generating any actual KeyRelease event that deactivates the grab, G is the grab_window, and F is the current focus, the X server does the following:

- It generates FocusIn and FocusOut events, with the mode members of the XFocusInEvent and XFocusOutEvent structures set to NotifyUngrab. These events are generated as if the focus were to change from G to F.

XFocusChangeEvent
XFocusInEvent
XFocusOutEvent

## Key Map State Notification Events

The X server can report KeymapNotify events to clients that want information about changes in their keyboard state.

Events KeymapNotify
KeymapNotify

To receive KeymapNotify events, set the KeymapStateMask bit in the event-mask attribute of the window. The X server generates this event immediately after every EnterNotify and FocusIn event.

The structure for this event type contains:

    /* generated on EnterWindow and FocusIn when KeymapState selected */
    typedef struct {
         int            type;           /* KeymapNotify */
         unsigned long  serial;         /* # of last request processed by server */
         Bool           send_event;     /* true if this came from a SendEvent request */
         Display        *display;       /* Display the event was read from */
         Window         window;
         char           key_vector[32];
    } XKeymapEvent;

XKeymapEvent

The window member is not used but is present to aid some toolkits. The key_vector member is set to the bit vector of the keyboard. Each bit set to 1 indicates that the corresponding key is currently pressed. The vector is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N + 7 with the least significant bit in the byte representing key 8N.

## Exposure Events

The X protocol does not guarantee to preserve the contents of window regions when the windows are obscured or reconfigured. Some implementations may preserve the contents of windows. Other implementations are free to destroy the contents of windows when exposed. X expects client applications to assume the responsibility for restoring the contents of an exposed window region. (An exposed window region describes a formerly obscured window whose region becomes visible.) Therefore, the X server sends Expose events describing the window and the region of the window that has been exposed. A naive client application usually redraws the entire window. A more sophisticated client application redraws only the exposed region.

### Expose Events

The X server can report Expose events to clients wanting information about when the contents of window regions have been lost. The circumstances in which the X server generates Expose events are not as definite as those for other events. However, the X server never generates Expose events on windows whose class you specified as InputOnly. The X server can generate Expose events 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 the window's backing-store attribute of Always or WhenMapped. The regions decompose into an (arbitrary) set of rectangles, and an Expose event is generated for each rectangle. For any given window, the X server guarantees to report contiguously all of the regions exposed by some action that causes Expose events, such as raising a window.

Events Expose
Expose

To receive Expose events, set the ExposureMask bit in the event-mask attribute of the window.

The structure for this event type contains:

    typedef struct {
         int           type;           /* Expose */
         unsigned long serial;         /* # of last request processed by server */
         Bool          send_event;     /* true if this came from a SendEvent request */
         Display       *display;       /* Display the event was read from */
         Window        window;
         int           x, y;
         int           width, height;
         int           count;          /* if nonzero, at least this many more */
    } XExposeEvent;

XExposeEvent

The window member is set to the exposed (damaged) window. The x and y members are set to the coordinates relative to the window's origin and indicate the upper-left corner of the rectangle. The width and height members are set to the size (extent) of the rectangle. The count member is set to the number of Expose 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.

### GraphicsExpose and NoExpose Events

The X server can report GraphicsExpose events to clients wanting information about when a destination region could not be computed during certain graphics requests: or . The X server generates this event whenever a destination region could not be computed because of an obscured or out-of-bounds source region. In addition, the X server guarantees to report contiguously all of the regions exposed by some graphics request (for example, copying an area of a drawable to a destination drawable).

Events GraphicsExpose
Events NoExpose
GraphicsExpose

The X server generates a NoExpose event whenever a graphics request that might produce a GraphicsExpose event does not produce any. In other words, the client is really asking for a GraphicsExpose event but instead receives a NoExpose event.

NoExpose

To receive GraphicsExpose or NoExpose events, you must first set the graphics-exposure attribute of the graphics context to True. You also can set the graphics-expose attribute when creating a graphics context using or by calling .

The structures for these event types contain:

    typedef struct {
         int            type;           /* GraphicsExpose */
         unsigned long  serial;         /* # of last request processed by server */
         Bool           send_event;     /* true if this came from a SendEvent request */
         Display        *display;       /* Display the event was read from */
         Drawable       drawable;
         int            x, y;
         int            width, height;
         int            count;          /* if nonzero, at least this many more */
         int            major_code;     /* core is CopyArea or CopyPlane */
         int            minor_code;     /* not defined in the core */
    } XGraphicsExposeEvent;

XGraphicsExposeEvent

    typedef struct {
         int           type;         /* NoExpose */
         unsigned long serial;       /* # of last request processed by server */
         Bool          send_event;   /* true if this came from a SendEvent request */
         Display       *display;     /* Display the event was read from */
         Drawable      drawable;
         int           major_code;   /* core is CopyArea or CopyPlane */
         int           minor_code;   /* not defined in the core */
    } XNoExposeEvent;

XNoExposeEvent

Both structures have these common members: drawable, major_code, and minor_code. The drawable member is set to the drawable of the destination region on which the graphics request was to be performed. 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 initiated the request. If it is X_CopyPlane, a call to initiated the request. These constants are defined in `<X11/Xproto.h>`. The minor_code member, like the major_code member, indicates which graphics request was initiated by the client. However, the minor_code member is not defined by the core X protocol and will be zero in these cases, although it may be used by an extension.

X11/Xproto.h
Files <X11/Xproto.h>
Headers <X11/Xproto.h>

The XGraphicsExposeEvent structure has these additional members: x, y, width, height, and count. 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. The width and height members are set to the size (extent) of the rectangle. The count member is set to the number of GraphicsExpose events to follow. If count is zero, no more GraphicsExpose events follow for this window. However, if count is nonzero, at least that number of GraphicsExpose events (and possibly more) are to follow for this window.

## Window State Change Events

The following sections discuss:

- CirculateNotify events

- ConfigureNotify events

- CreateNotify events

- DestroyNotify events

- GravityNotify events

- MapNotify events

- MappingNotify events

- ReparentNotify events

- UnmapNotify events

- VisibilityNotify events

### CirculateNotify Events

The X server can report CirculateNotify events to clients wanting information about when a window changes its position in the stack. The X server generates this event type whenever a window is actually restacked as a result of a client application calling , , or .

Events CirculateNotify
CirculateNotify

To receive CirculateNotify events, set the StructureNotifyMask bit in the event-mask attribute of the window or the SubstructureNotifyMask bit in the event-mask attribute of the parent window (in which case, circulating any child generates an event).

The structure for this event type contains:

    typedef struct {
         int type;     /* CirculateNotify */
         unsigned long serial;     /* # of last request processed by server */
         Bool send_event;     /* true if this came from a SendEvent request */
         Display *display;     /* Display the event was read from */
         Window event;
         Window window;
         int place;     /* PlaceOnTop, PlaceOnBottom */
    } XCirculateEvent;

XCirculateEvent

The event member is set either to the restacked window or to its parent, depending on whether StructureNotify or SubstructureNotify was selected. The window member is set to the window that was restacked. The place member is set to the window's position after the restack occurs and is either PlaceOnTop or PlaceOnBottom. If it is PlaceOnTop, the window is now on top of all siblings. If it is PlaceOnBottom, the window is now below all siblings.

### ConfigureNotify Events

The X server can report ConfigureNotify events to clients wanting information about actual changes to a window's state, such as size, position, border, and stacking order. The X server generates this event type whenever one of the following configure window requests made by a client application actually completes:

Events ConfigureNotify
ConfigureNotify

- A window's size, position, border, and/or stacking order is reconfigured by calling .

- The window's position in the stacking order is changed by calling , , or .

- A window is moved by calling .

- A window's size is changed by calling .

- A window's size and location is changed by calling .

- A window is mapped and its position in the stacking order is changed by calling .

- A window's border width is changed by calling .

To receive ConfigureNotify events, set the StructureNotifyMask bit in the event-mask attribute of the window or the SubstructureNotifyMask bit in the event-mask attribute of the parent window (in which case, configuring any child generates an event).

The structure for this event type contains:

    typedef struct {
         int           type;       /* ConfigureNotify */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        event;
         Window        window;
         int           x, y;
         int           width, height;
         int           border_width;
         Window        above;
         Bool          override_redirect;
    } XConfigureEvent;

The event member is set either to the reconfigured window or to its parent, depending on whether StructureNotify or SubstructureNotify was selected. The window member is set to the window whose size, position, border, and/or stacking order was changed.

The x and y members are set to the coordinates relative to the parent window's origin and indicate the position of the upper-left outside corner of the window. The width and height members are set to the inside size of the window, not including the border. The border_width member is set to the width of the window's border, in pixels.

The above member is set to the sibling window and is used for stacking operations. If the X server sets this member to None, the window whose state was changed is on the bottom of the stack with respect to sibling windows. However, if this member is set to a sibling window, the window whose state was changed is placed on top of this sibling window.

The override_redirect member is set to the override-redirect attribute of the window. Window manager clients normally should ignore this window if the override_redirect member is True.

XConfigureEvent

### CreateNotify Events

The X server can report CreateNotify events to clients wanting information about creation of windows. The X server generates this event whenever a client application creates a window by calling or .

Events CreateNotify
CreateNotify

To receive CreateNotify events, set the SubstructureNotifyMask bit in the event-mask attribute of the window. Creating any children then generates an event.

The structure for the event type contains:

    typedef struct {
         int           type;               /* CreateNotify */
         unsigned long serial;             /* # of last request processed by server */
         Bool          send_event;         /* true if this came from a SendEvent request */
         Display       *display;           /* Display the event was read from */
         Window        parent;             /* parent of the window */
         Window        window;             /* window id of window created */
         int           x, y;               /* window location */
         int           width, height;      /* size of window */
         int           border_width;       /* border width */
         Bool          override_redirect;  /* creation should be overridden */
    } XCreateWindowEvent;

XCreateWindowEvent

The parent member is set to the created window's parent. The window member specifies the created window. The x and y members are set to the created window's coordinates relative to the parent window's origin and indicate the position of the upper-left outside corner of the created window. The width and height members are set to the inside size of the created window (not including the border) and are always nonzero. The border_width member is set to the width of the created window's border, in pixels. The override_redirect member is set to the override-redirect attribute of the window. Window manager clients normally should ignore this window if the override_redirect member is True.

### DestroyNotify Events

The X server can report DestroyNotify events to clients wanting information about which windows are destroyed. The X server generates this event whenever a client application destroys a window by calling or .

Events DestroyNotify
DestroyNotify

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 X protocol does not constrain the ordering among siblings and across subhierarchies.

To receive DestroyNotify events, set the StructureNotifyMask bit in the event-mask attribute of the window or the SubstructureNotifyMask bit in the event-mask attribute of the parent window (in which case, destroying any child generates an event).

The structure for this event type contains:

    typedef struct {
         int           type;       /* DestroyNotify */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        event;
         Window        window;
    } XDestroyWindowEvent;

XDestroyWindowEvent

The event member is set either to the destroyed window or to its parent, depending on whether StructureNotify or SubstructureNotify was selected. The window member is set to the window that is destroyed.

### GravityNotify Events

The X server can report GravityNotify events to clients wanting information about when a window is moved because of a change in the size of its parent. The X server generates this event whenever a client application actually moves a child window as a result of resizing its parent by calling , , or .

Events GravityNotify
GravityNotify

To receive GravityNotify events, set the StructureNotifyMask bit in the event-mask attribute of the window or the SubstructureNotifyMask bit in the event-mask attribute of the parent window (in which case, any child that is moved because its parent has been resized generates an event).

The structure for this event type contains:

    typedef struct {
         int           type;       /* GravityNotify */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        event;
         Window        window;
         int           x, y;
    } XGravityEvent;

XGravityEvent

The event member is set either to the window that was moved or to its parent, depending on whether StructureNotify or SubstructureNotify was selected. The window member is set to the child window that was moved. The x and y members are set to the coordinates relative to the new parent window's origin and indicate the position of the upper-left outside corner of the window.

### MapNotify Events

The X server can report MapNotify events to clients wanting information about which windows are mapped. The X server generates this event type whenever a client application changes the window's state from unmapped to mapped by calling , , , , or as a result of save-set processing.

Events MapNotify
MapNotify

To receive MapNotify events, set the StructureNotifyMask bit in the event-mask attribute of the window or the SubstructureNotifyMask bit in the event-mask attribute of the parent window (in which case, mapping any child generates an event).

The structure for this event type contains:

    typedef struct {
         int           type;                  /* MapNotify */
         unsigned long serial;                /* # of last request processed by server */
         Bool          send_event;            /* true if this came from a SendEvent request */
         Display       *display;              /* Display the event was read from */
         Window        event;
         Window        window;
         Bool          override_redirect;     /* boolean, is override set... */
    } XMapEvent;

XMapEvent

The event member is set either to the window that was mapped or to its parent, depending on whether StructureNotify or SubstructureNotify was selected. The window member is set to the window that was mapped. The override_redirect member is set to the override-redirect attribute of the window. Window manager clients normally should ignore this window if the override-redirect attribute is True, because these events usually are generated from pop-ups, which override structure control.

### MappingNotify Events

The X server reports MappingNotify events to all clients. There is no mechanism to express disinterest in this event. The X server generates this event type whenever a client application successfully calls:

Events MappingNotify
MappingNotify

- to indicate which KeyCodes are to be used as modifiers

- to change the keyboard mapping

- to set the pointer mapping

The structure for this event type contains:

    typedef struct {
         int           type;           /* MappingNotify */
         unsigned long serial;         /* # of last request processed by server */
         Bool          send_event;     /* true if this came from a SendEvent request */
         Display       *display;       /* Display the event was read from */
         Window        window;         /* unused */
         int           request;        /* one of MappingModifier, MappingKeyboard,
                       MappingPointer  */
         int           first_keycode;  /* first keycode */
         int           count;          /* defines range of change w. first_keycode*/
    } XMappingEvent;

XMappingEvent

The request member is set to indicate the kind of mapping change that occurred and can be MappingModifier, MappingKeyboard, or MappingPointer. If it is MappingModifier, the modifier mapping was changed. If it is MappingKeyboard, the keyboard mapping was changed. If it is MappingPointer, the pointer button mapping was changed. The first_keycode and count members are set only if the request member was set to MappingKeyboard. The number in first_keycode represents the first number in the range of the altered mapping, and count represents the number of keycodes altered.

To update the client application's knowledge of the keyboard, you should call .

### ReparentNotify Events

The X server can report ReparentNotify events to clients wanting information about changing a window's parent. The X server generates this event whenever a client application calls and the window is actually reparented.

Events ReparentNotify
ReparentNotify

To receive ReparentNotify events, set the StructureNotifyMask bit in the event-mask attribute of the window or the SubstructureNotifyMask bit in the event-mask attribute of either the old or the new parent window (in which case, reparenting any child generates an event).

The structure for this event type contains:

    typedef struct {
         int           type;       /* ReparentNotify */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        event;
         Window        window;
         Window        parent;
         int           x, y;
         Bool          override_redirect;
    } XReparentEvent;

XReparentEvent

The event member is set either to the reparented window or to the old or the new parent, depending on whether StructureNotify or SubstructureNotify was selected. The window member is set to the window that was reparented. The parent member is set to the new parent window. The x and y members are set to the reparented window's coordinates relative to the new parent window's origin and define the upper-left outer corner of the reparented window. The override_redirect member is set to the override-redirect attribute of the window specified by the window member. Window manager clients normally should ignore this window if the override_redirect member is True.

### UnmapNotify Events

The X server can report UnmapNotify events to clients wanting information about which windows are unmapped. The X server generates this event type whenever a client application changes the window's state from mapped to unmapped.

Events UnmapNotify
UnmapNotify

To receive UnmapNotify events, set the StructureNotifyMask bit in the event-mask attribute of the window or the SubstructureNotifyMask bit in the event-mask attribute of the parent window (in which case, unmapping any child window generates an event).

The structure for this event type contains:

    typedef struct {
         int           type;       /* UnmapNotify */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        event;
         Window        window;
         Bool          from_configure;
    } XUnmapEvent;

XUnmapEvent

The event member is set either to the unmapped window or to its parent, depending on whether StructureNotify or SubstructureNotify was selected. This is the window used by the X server to report the event. The window member is set to the window that was unmapped. The from_configure member is set to 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 UnmapGravity.

### VisibilityNotify Events

The X server can report VisibilityNotify events to clients wanting any change in the visibility of the specified window. A region of a window is visible if someone looking at the screen can actually see it. The X server generates this event whenever the visibility changes state. However, this event is never generated for windows whose class is InputOnly.

Events VisibilityNotify
VisibilityNotify

All VisibilityNotify events caused by a hierarchy change are generated after any hierarchy event (UnmapNotify, MapNotify, ConfigureNotify, GravityNotify, CirculateNotify) caused by that change. 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 X protocol does not constrain the ordering of VisibilityNotify events with respect to FocusOut, EnterNotify, and LeaveNotify events.

To receive VisibilityNotify events, set the VisibilityChangeMask bit in the event-mask attribute of the window.

The structure for this event type contains:

    typedef struct {
         int           type;       /* VisibilityNotify */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        window;
         int           state;
    } XVisibilityEvent;

XVisibilityEvent

The window member is set to the window whose visibility state changes. The state member is set to the state of the window's visibility and can be VisibilityUnobscured, VisibilityPartiallyObscured, or VisibilityFullyObscured. The X server ignores all of a window's subwindows when determining the visibility state of the window and processes VisibilityNotify events according to the following:

- When the window changes state from partially obscured, fully obscured, or not viewable to viewable and completely unobscured, the X server generates the event with the state member of the XVisibilityEvent structure set to VisibilityUnobscured.

- When the window changes state from viewable and completely unobscured or not viewable to viewable and partially obscured, the X server generates the event with the state member of the XVisibilityEvent structure set to VisibilityPartiallyObscured.

- When the window changes state from viewable and completely unobscured, viewable and partially obscured, or not viewable to viewable and fully obscured, the X server generates the event with the state member of the XVisibilityEvent structure set to VisibilityFullyObscured.

## Structure Control Events

This section discusses:

- CirculateRequest events

- ConfigureRequest events

- MapRequest events

- ResizeRequest events

### CirculateRequest Events

The X server can report CirculateRequest events to clients wanting information about when another client initiates a circulate window request on a specified window. The X server generates this event type whenever a client initiates a circulate window request on a window and a subwindow actually needs to be restacked. The client initiates a circulate window request on the window by calling , , or .

Events CirculateRequest
CirculateRequest

To receive CirculateRequest events, set the SubstructureRedirectMask in the event-mask attribute of the window. Then, in the future, the circulate window request for the specified window is not executed, and thus, any subwindow's position in the stack is not changed. For example, suppose a client application calls to raise a subwindow to the top of the stack. If you had selected SubstructureRedirectMask on the window, the X server reports to you a CirculateRequest event and does not raise the subwindow to the top of the stack.

The structure for this event type contains:

    typedef struct {
         int           type;       /* CirculateRequest */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        parent;
         Window        window;
         int place;                /* PlaceOnTop, PlaceOnBottom */
    } XCirculateRequestEvent;

XCirculateRequestEvent

The parent member is set to the parent window. The window member is set to the subwindow to be restacked. The place member is set to what the new position in the stacking order should be and is either PlaceOnTop or PlaceOnBottom. If it is PlaceOnTop, the subwindow should be on top of all siblings. If it is PlaceOnBottom, the subwindow should be below all siblings.

### ConfigureRequest Events

The X server can report ConfigureRequest events to clients wanting information about when a different client initiates a configure window request on any child of a specified window. The configure window request attempts to reconfigure a window's size, position, border, and stacking order. The X server generates this event whenever a different client initiates a configure window request on a window by calling , , , , , , , , or .

Events ConfigureRequest
ConfigureRequest

To receive ConfigureRequest events, set the SubstructureRedirectMask bit in the event-mask attribute of the window. ConfigureRequest events are generated when a ConfigureWindow protocol request is issued on a child window by another client. For example, suppose a client application calls to lower a window. If you had selected SubstructureRedirectMask on the parent window and if the override-redirect attribute of the window is set to False, the X server reports a ConfigureRequest event to you and does not lower the specified window.

The structure for this event type contains:

    typedef struct {
         int           type;         /* ConfigureRequest */
         unsigned long serial;       /* # of last request processed by server */
         Bool          send_event;   /* true if this came from a SendEvent request */
         Display       *display;     /* Display the event was read from */
         Window        parent;
         Window        window;
         int           x, y;
         int           width, height;
         int           border_width;
         Window        above;
         int           detail;       /* Above, Below, TopIf, BottomIf, Opposite */
         unsigned long value_mask;
    } XConfigureRequestEvent;

XConfigureRequestEvent

The parent member is set to the parent window. The window member is set to the window whose size, position, border width, and/or stacking order is to be reconfigured. The value_mask member 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.

### MapRequest Events

The X server can report MapRequest events to clients wanting information about a different client's desire to map windows. A window is considered mapped when a map window request completes. The X server generates this event whenever a different client initiates a map window request on an unmapped window whose override_redirect member is set to False. Clients initiate map window requests by calling , , or .

Events MapRequest
MapRequest

To receive MapRequest events, set the SubstructureRedirectMask bit in the event-mask attribute of the window. This means another client's attempts to map a child window by calling one of the map window request functions is intercepted, and you are sent a MapRequest instead. For example, suppose a client application calls to map a window. If you (usually a window manager) had selected SubstructureRedirectMask on the parent window and if the override-redirect attribute of the window is set to False, the X server reports a MapRequest event to you and does not map the specified window. Thus, this event gives your window manager client the ability to control the placement of subwindows.

The structure for this event type contains:

    typedef struct {
         int           type;       /* MapRequest */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        parent;
         Window        window;
    } XMapRequestEvent;

XMapRequestEvent

The parent member is set to the parent window. The window member is set to the window to be mapped.

### ResizeRequest Events

The X server can report ResizeRequest events to clients wanting information about another client's attempts to change the size of a window. The X server generates this event whenever some other client attempts to change the size of the specified window by calling , , or .

Events ResizeRequest
ResizeRequest

To receive ResizeRequest events, set the ResizeRedirect bit in the event-mask attribute of the window. Any attempts to change the size by other clients are then redirected.

The structure for this event type contains:

    typedef struct {
         int           type;        /* ResizeRequest */
         unsigned long serial;      /* # of last request processed by server */
         Bool          send_event;  /* true if this came from a SendEvent request */
         Display       *display;    /* Display the event was read from */
         Window        window;
         int           width, height;
    } XResizeRequestEvent;

XResizeRequestEvent

The window member is set to the window whose size another client attempted to change. The width and height members are set to the inside size of the window, excluding the border.

## Colormap State Change Events

The X server can report ColormapNotify events to clients wanting information about when the colormap changes and when a colormap is installed or uninstalled. The X server generates this event type whenever a client application:

Events ColormapNotify
ColormapNotify

- Changes the colormap member of the XSetWindowAttributes structure by calling , , or

- Installs or uninstalls the colormap by calling or

To receive ColormapNotify events, set the ColormapChangeMask bit in the event-mask attribute of the window.

The structure for this event type contains:

    typedef struct {
         int           type;       /* ColormapNotify */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        window;
         Colormap      colormap;   /* colormap or None */
         Bool          new;
         int           state;      /* ColormapInstalled, ColormapUninstalled */
    } XColormapEvent;

XColormapEvent

The window member is set to the window whose associated colormap is changed, installed, or uninstalled. For a colormap that is changed, installed, or uninstalled, the colormap member is set to the colormap associated with the window. For a colormap that is changed by a call to , the colormap member is set to None. The new member is set to 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. The state member is always set to indicate whether the colormap is installed or uninstalled and can be ColormapInstalled or ColormapUninstalled.

## Client Communication Events

This section discusses:

- ClientMessage events

- PropertyNotify events

- SelectionClear events

- SelectionNotify events

- SelectionRequest events

### ClientMessage Events

The X server generates ClientMessage events only when a client calls the function .

Events ClientMessage
ClientMessage

The structure for this event type contains:

    typedef struct {
         int           type;           /* ClientMessage */
         unsigned long serial;         /* # of last request processed by server */
         Bool          send_event;     /* true if this came from a SendEvent request */
         Display       *display;       /* Display the event was read from */
         Window        window;
         Atom          message_type;
         int           format;
         union         {
                         char  b[20];
                         short s[10];
                         long  l[5];
                       } data;
    } XClientMessageEvent;

XClientMessageEvent

The message_type member is set to an atom that indicates how the data should be interpreted by the receiving client. The format member is set to 8, 16, or 32 and specifies whether the data should be viewed as a list of bytes, shorts, or longs. The data member is a union that contains the members b, s, and l. The b, s, and l members represent data of twenty 8-bit values, ten 16-bit values, and five 32-bit values. Particular message types might not make use of all these values. The X server places no interpretation on the values in the window, message_type, or data members.

### PropertyNotify Events

The X server can report PropertyNotify events to clients wanting information about property changes for a specified window.

Events PropertyNotify
PropertyNotify

To receive PropertyNotify events, set the PropertyChangeMask bit in the event-mask attribute of the window.

The structure for this event type contains:

    typedef struct {
         int           type;       /* PropertyNotify */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        window;
         Atom atom;
         Time time;
         int state;                /* PropertyNewValue or PropertyDelete */
    } XPropertyEvent;

XPropertyEvent

The window member is set to the window whose associated property was changed. The atom member is set to the property's atom and indicates which property was changed or desired. The time member is set to the server time when the property was changed. The state member is set to indicate whether the property was changed to a new value or deleted and can be PropertyNewValue or PropertyDelete. The state member is set to PropertyNewValue when a property of the window is changed using or (even when adding zero-length data using ) and when replacing all or part of a property with identical data using or . The state member is set to PropertyDelete when a property of the window is deleted using or, if the delete argument is True, .

### SelectionClear Events

The X server reports SelectionClear events to the client losing ownership of a selection. The X server generates this event type when another client asserts ownership of the selection by calling .

Events SelectionClear
SelectionClear

The structure for this event type contains:

    typedef struct {
         int           type;       /* SelectionClear */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        window;
         Atom          selection;
         Time          time;
    } XSelectionClearEvent;

XSelectionClearEvent

The selection member is set to the selection atom. The time member is set to the last change time recorded for the selection. The window member is the window that was specified by the current owner (the owner losing the selection) in its call.

### SelectionRequest Events

The X server reports SelectionRequest events to the owner of a selection. The X server generates this event whenever a client requests a selection conversion by calling for the owned selection.

Events SelectionRequest
SelectionRequest

The structure for this event type contains:

    typedef struct {
         int           type;       /* SelectionRequest */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        owner;
         Window        requestor;
         Atom          selection;
         Atom          target;
         Atom          property;
         Time          time;
    } XSelectionRequestEvent;

XSelectionRequestEvent

The owner member is set to the window that was specified by the current owner in its call. The requestor member is set to the window requesting the selection. The selection member is set to the atom that names the selection. For example, PRIMARY is used to indicate the primary selection. The target member is set to the atom that indicates the type the selection is desired in. The property member can be a property name or None. The time member is set to the timestamp or CurrentTime value from the ConvertSelection request.

The owner should convert the selection based on the specified target type and send a SelectionNotify event back to the requestor. A complete specification for using selections is given in the X Consortium standard Inter-Client Communication Conventions Manual.

### SelectionNotify Events

This event is generated by the X server in response to a ConvertSelection protocol request when there is no owner for the selection. When there is an owner, it should be generated by the owner of the selection by using . The owner of a selection should send this event to a requestor when a selection has been converted and stored as a property or when a selection conversion could not be performed (which is indicated by setting the property member to None).

Events SelectionNotify
SelectionNotify

If None is specified as the property in the ConvertSelection protocol request, the owner should choose a property name, store the result as that property on the requestor window, and then send a SelectionNotify giving that actual property name.

The structure for this event type contains:

    typedef struct {
         int           type;       /* SelectionNotify */
         unsigned long serial;     /* # of last request processed by server */
         Bool          send_event; /* true if this came from a SendEvent request */
         Display       *display;   /* Display the event was read from */
         Window        requestor;
         Atom          selection;
         Atom          target;
         Atom          property;   /* atom or None */
         Time          time;
    } XSelectionEvent;

XSelectionEvent

The requestor member is set to the window associated with the requestor of the selection. The selection member is set to the atom that indicates the selection. For example, PRIMARY is used for the primary selection. The target member is set to the atom that indicates the converted type. For example, PIXMAP is used for a pixmap. The property member is set to the atom that indicates which property the result was stored on. If the conversion failed, the property member is set to None. The time member is set to the time the conversion took place and can be a timestamp or CurrentTime.