Example E-1 shows the XEvent union and a simple event structure that is one member of the union. Several of the members of this structure are present in nearly every event structure. They are described here before we go into the event-specific members (see also Volume One, “Event Types and XEvent Union” in Chapter 8).

typedef union _XEvent {
   int type;   /* Must not be changed; first member */
   XAnyEvent xany;
   XButtonEvent xbutton;
   XCirculateEvent xcirculate;
   XCirculateRequestEvent xcirculaterequest;
   XClientMessageEvent xclient;
   XColormapEvent xcolormap;
   XConfigureEvent xconfigure;
   XConfigureRequestEvent xconfigurerequest;
   XCreateWindowEvent xcreatewindow;
   XDestroyWindowEvent xdestroywindow;
   XCrossingEvent xcrossing;
   XExposeEvent xexpose;
   XFocusChangeEvent xfocus;
   XNoExposeEvent xnoexpose;
   XGraphicsExposeEvent xgraphicsexpose;
   XGravityEvent xgravity;
   XKeymapEvent xkeymap;
   XKeyEvent xkey;
   XMapEvent xmap;
   XUnmapEvent xunmap;
   XMappingEvent xmapping;
   XMapRequestEvent xmaprequest;
   XMotionEvent xmotion;
   XPropertyEvent xproperty;
   XReparentEvent xreparent;
   XResizeRequestEvent xresizerequest;
   XSelectionClearEvent xselectionclear;
   XSelectionEvent xselection;
   XSelectionRequestEvent xselectionrequest;
   XVisibilityEvent xvisibility;
} XEvent;
typedef struct {
   int type;
   unsigned long serial;   /* # of last request processed by server */
   Bool send_event;        /* True if this came from SendEvent 
                            * request */
   Display *display;       /* Display the event was read from */
   Window window;          /* window on which event was requested 
                            * in event mask */
} XAnyEvent;

The first member of the XEvent union is the type of event. When an event is received (with XNextEvent, for example), the application checks the type member in the XEvent union. Then the specific event type is known and the specific event structure (such as xbutton) is used to access information specific to that event type.

Before the branching depending on the event type, only the XEvent union is used. After the branching, only the event structure which contains the specific information for each event type should be used in each branch. For example, if the XEvent union were called report, the report.xexpose structure should be used within the branch for Expose events.

You will notice that each event structure also begins with a type member. This member is rarely used, since it is an identical copy of the type member in the XEvent union.

Most event structures also have a window member. The only ones that do not are certain selection events (SelectionNotify and SelectionRequest) and events selected by the graphics_exposures member of the GC (GraphicsExpose and NoExpose). The window member indicates the event window that selected and received the event. This is the window where the event arrives if it has propagated through the hierarchy as described in “Propagation of Device Events” in Chapter 8, of Volume One. One event type may have two different meanings to an application, depending on which window it appears in.

Many of the event structures also have a display and/or root member. The display member identifies the connection to the server that is active. The root member indicates which screen the window that received the event is linked to in the hierarchy. Most programs only use a single screen and therefore do not need to worry about the root member. The display member can be useful, since you can pass the display variable into routines by simply passing a pointer to the event structure, eliminating the need for a separate display argument.

All event structures include a serial member that gives the number of the last protocol request processed by the server. This is useful in debugging, since an error can be detected by the server but not reported to the user (or programmer) until the next routine that gets an event. That means several routines may execute successfully after the error occurs. The last request processed will often indicate the request that contained the error.

All event structures also include a send_event flag, which, if True, indicates that the event was sent by XSendEvent (i.e., by another client rather than by the server).

The following pages describe each event type in detail. The events are presented in alphabetical order, each on a separate page. Each page describes the circumstances under which the event is generated, the mask used to select it, the structure itself, its members, and useful programming notes. Note that the description of the structure members does not include those members common to many structures. If you need more information on these members, please refer to this introductory section.