E

Event Reference

This appendix describes each event structure in detail and briefly shows how each event type is used. It covers the most common uses of each event type, the information contained in each event structure, how the event is selected, and the side effects of the event, if any. Each event is described on a separate reference page.

Table E-1 lists each event mask, its associated event types, and the associated structure definition. See Volume One, Chapter 8, Events for more information on events.

Table E-1. Event Masks, Event Types, and Event Structures

images

images

Meaning of Common Structure Elements

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, Section 8.2.2).

Example E-1. XEvent union and XAnyEvent structure

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'll 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 don't are selection events (SelectionNotify, SelectionRequest, and SelectionClear) 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 Volume One, Section 8.3.2. 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 don't 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.

ButtonPress, ButtonRelease

—xbutton

When Generated

There are two types of pointer button events: ButtonPress and ButtonRelease. Both contain the same information.

Select With

May be selected separately, using ButtonPressMask and ButtonReleaseMask.

XEvent Structure Name

typedef union _XEvent {
    ...
    XButtonEvent xbutton;
    ...
} XEvent;

Event Structure

typedef struct {
   int type;             /* of event */
   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 under */
   Window subwindow;     /* child window */
   Time time;            /* when event occurred, in milliseconds */
   int x, y;             /* pointer coords relative to receiving window *
   int x_root, y_root;   /* coordinates relative to root */
   unsigned int state;   /* mask of all buttons and modifier keys */
   unsigned int button;  /* button that triggered event */
   Bool same_screen;     /* same screen flag */
} XButtonEvent;
typedef XButtonEvent XButtonPressedEvent;
typedef XButtonEvent XButtonReleasedEvent;

Event Structure Members

subwindow If the source window is the child of the receiving window, then the subwindow member is set to the ID of that child.
time The server time when the button event occurred, in milliseconds. Time is declared as unsigned long, so it wraps around when it reaches the maximum value of a 32 bit number (every 49.7 days).
x, y If the receiving window is on the same screen as the root window specified by root, then x and y are the pointer coordinates relative to the receiving window's origin. Otherwise, x and y are zero.

When active button grabs and pointer grabs are in effect (see Volume One, Section 9.4), the coordinates relative to the receiving window may not be within the window (they may be negative or greater than window height or width).

x_root, y_root The pointer coordinates relative to the root window which is an ancestor of the event window. If the pointer was on a different screen, these are zero.
state The state of all the buttons and modifier keys just before the event, represented by a mask of the button and modifier key symbols: Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, ShiftMask, ControlMask, LockMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask. If a modifier key is pressed and released when no other modifier keys are held, the ButtonPress will have a state member of 0 and the ButtonRelease will have a nonzero state member indicating that itself was held just before the event.
button A value indicating which button changed state to trigger this event. One of the constants: Button1, Button2, Button3, Button4, or Button5.
same_screen Indicates whether the pointer is currently on the same screen as this window. This is always True unless the pointer was actively grabbed before the automatic grab could take place.

Notes

Unless an active grab already exists, or a passive grab on the button combination that was pressed already exists at a higher level in the hierarchy than where the ButtonPress occured, an automatic active grab of the pointer takes place when a ButtonPress occurs. Because of the automatic grab, the matching ButtonRelease is sent to the same application that received the ButtonPress event. If OwnerGrabButtonMask has been selected, the ButtonRelease event is delivered to the window which contained the pointer when the button was released, as long as that window belongs to the same client as the window in which the ButtonPress event occurred. If the ButtonRelease occurs outside or the client's windows, or OwnerGrabButtonMask was not selected, the ButtonRelease is delivered to the window in which the ButtonPress occurred. The grab is terminated when all buttons are released. During the grab, the cursor associated with the grabbing window will track the pointer anywhere on the screen.

If the application has invoked a passive button grab on an ancestor of the window in which the ButtonPress event occurs, then that grab takes precedence over the automatic grab, and the ButtonRelease will go to that window, or it will be handled normally by that client depending on the owner_events flag in the XGrabButton call.

CirculateNotify

—xcirculate

When Generated

CirculateNotify events are generated when a window is actually restacked from a call to either XCirculateWindowUp or XCirculateWindowDown. If the window manager prevents such an operation, then no XCirculateNotify event is generated.

Select With

This event type is selected using StructureNotifyMask in the XSelectInput call for the window to be raised, or by selecting SubstructureNotifyMask for the parent of the window to be raised.

XEvent Structure Name

typedef union _XEvent {
    ...
    XCirculateEvent xcirculate;
    ...
} XEvent;

Event Structure

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 event;
    Window window;
    int place;                  /* PlaceOnTop, PlaceOnBottom */
} XCirculateEvent;

Event Structure Members

event The window receiving the event. If the event was selected by StructureNotifyMask, event will be the same as window. If the event was selected by SubstructureNotifyMask, event will be the parent of window.
window The window that was restacked.
place Either PlaceOnTop or PlaceOnBottom. Indicates whether the window was raised to the top or bottom of the stack.

CirculateRequest

xcirculaterequest—

When Generated

CirculateRequest events report when another client calls XCirculateSubwindows, XCirculateSubwindowsUp or XCirculateSubwindowsDown for a specified parent window, and the stacking order is actually changed. If this event type is selected, the window is not moved in the stacking order. This gives the client that selects this event (usually the window manager) the opportunity to review the request in the light of its window management policy, before executing the circulate request itself, or deny the request.

Select With

This event type is selected for the parent window with the SubstructureRedirectMask.

XEvent Structure Name

typedef union _XEvent {
    ...
    XCirculateRequestEvent xcirculaterequest;
    ...
} XEvent;

Event Structure

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 parent;
    Window window;
    int place;             /* PlaceOnTop, PlaceOnBottom */
} XCirculateRequestEvent;

Event Structure Members

parent The parent of the window that was restacked. This is the window that selected the event.
window The window being restacked.
place PlaceOnTop or PlaceOnBottom. Indicates whether the window was to be placed on top or on the bottom of the stacking order.

ClientMessage

—xclient

When Generated

ClientMessage events are generated only when a client calls the function XSendEvent. Any type of event can be sent with XSendEvent, but it will be distinguished from normal events by the the send_event member being set to True. If your program wants to be able to treat events sent with XSendEvent as different from normal events, you can read this member.

Select With

There is no event mask for ClientMessage events and they are not selected with XSelectInput. Instead, XSendEvent directs them to a specific window, which is given as a window ID: the PointerWindow or the InputFocus.

XEvent Structure Name

typedef union _XEvent {
    ...
    XClientMessageEvent xclient;
    ...
} XEvent;

Event Structure

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;
    Atom message_type;
    int format;
    union {
         char b[20] ;
         short s [10];
         int 1 [5];
    } data;
} XClientMessageEvent;

Event Structure Members

message_type An atom that specifies how the data is to be interpreted by the receiving client. The X server places no interpretation on the type or the data, but it must be a list of 8-bit, 16-bit, or 32-bit quantities, so that the X server can correctly swap bytes as necessary. The data always consists of twenty 8-bit values, ten 16-bit values, or five 32-bit values, although each particular message might not make use of all of these values.
format Specifies the format of the property specified by message_type. This will be on of the values 8, 16, or 32.

ColormapNotify

xcolormap—

When Generated

ColormapNotify events herald changes relating to the colormap specified in the colormap attribute for a particular window, or changes to the attribute itself.

Select With

To receive this event type, pass ColormapChangeMask to XSelectInput.

XEvent Structure Name

typedef union _XEvent {
    ...
    XColormapEvent xcolormap;
    ...
} XEvent;

Event Structure

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;
    Colormap colormap;       /* Colormap or None */
    Bool new;
    int state;               /* ColormapInstalled, ColormapUninstalled */
} XColormapEvent;

Event Structure Members

window The window whose associated colormap or attribute changes.
colormap The colormap associated with the window, either a colormap ID or the constant None. It will be None only if this event was generated due to an XFreeColormap call.
new True when the colormap attribute has been changed, or False when the colormap is installed or uninstalled.
state Either ColormapInstalled or ColormapUninstalled; it indicates whether the colormap is installed or uninstalled.

ConfigureNotify

—xconfigure

When Generated

ConfigureNotify events announce actual changes to a window's configuration (size, position, border, stacking order).

Select With

To receive this event type for a single window, specify the window ID of that window and pass StructureNotifyMask as the event_mask argument to XSelectInput. To receive this event for all children of a window, specify the parent window ID and pass SubstructureNotifyMask.

XEvent Structure Name

typedef union _XEvent {
    ...
    XConfigureEvent xconfigure;
    ...
} XEvent;

Event Structure

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 event;
    Window window;
    int x, y;
    int width, height;
    int border_width;
    Window above;
    Bool override_redirect;
} XConfigureEvent;

Event Structure Members

event The window that selected the event. The event and window members are identical if the event was selected with StructureNotifyMask.
window The window whose configuration was changed.
x, y The final coordinates of the reconfigured window relative to its parent.
width, height The width and height in pixels of the window after reconfiguration.
border_width The width in pixels of the border after reconfiguration.
above If this member is None, then the window is on the bottom of the stack with respect to its siblings. Otherwise, the window is immediately on top of the specified sibling window.
override_redirect The override_redirect attribute of the reconfigured window. If True, it indicates that the client wants this window to be immune to interception by the window manager of configuration requests. Window managers normally should ignore this event if override_redirect is True.

ConfigureRequest

—xconfigurerequest

When Generated

ConfigureRequest events announce another client's attempt to change a window's size, position, border, and/or stacking order. The X server generates this event type when another client attempts to reconfigure the window with XConfigureWindow or another configuration control function. If this event type is selected, the window is not reconfigured. This gives the client that selects this event (usually the window manager) the opportunity to revise the requested configuration before executing the XConfigureWindow request itself, or to deny the request.

Select With

To receive this event type for any window in a group of children, specify the parent window and pass SubstructureRedirectMask to XSelectInput.

XEvent Structure Name

typedef union _XEvent {
    ...
    XConfigureRequestEvent xconfigurerequest;
    ...
} XEvent;

Event Structure

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 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;

Event Structure Members

parent The window that selected the event. This is the parent of the window being configured.
window The window that is being configured.
x, y The requested position for the upper-left pixel of the window's border relative to the origin of the parent window.
width, height The requested width and height in pixels for the window.
border_width The requested border width for the window.
above None, Above, Below, TopIf, BottomIf, or Opposite. Specifies the sibling window on top of which the specified window should be placed. If this member has the constant None, then the specified window should be placed on the bottom.

Notes

The geometry is derived from the XConfigureWindow request that triggered the event.

CreateNotify

—xcreatewindow

When Generated

The X server reports CreateNotify events to clients when windows are created.

Select With

To receive this event type on children of a window, specify the parent window ID and pass SubstructureNotifyMask. Note that this event type cannot selected by StructureNotifyMask.

XEvent Structure Name

typedef union _XEvent {
    ...
    XCreateWindowEvent xcreatewindow;
    ...
} XEvent;

Event Structure

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 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;

Event Structure Members

parent The ID of the created window's parent.
window The ID of the created window.
x, y The coordinates of the created window relative to its parent.
width, height The width and height in pixels of the created window.
border_width The width in pixels of the border of the created window.
override_redirect The override_redirect attribute of the created window. If True, it indicates that the client wants this window to be immune to interception by the window manager of configuration requests. Window managers normally should ignore this event if override_redirect is True.

Notes

For descriptions of these members, see the XCreatewindow function and the XSetWindowAttributes structure.

DestroyNotify

xdestroywindow—

When Generated

DestroyNotify events announce that a window has been destroyed.

Select With

To receive this event type on children of a window, specify the parent window ID and pass SubstructureNotifyMask as part of the event_mask argument to XSelectInput. This event type cannot be selected with StructureNotifyMask.

XEvent Structure Name

typedef union _XEvent {
    ...
    XDestroyWindowEvent xdestroywindow;
    ...
} XEvent;

Event Structure

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 event;
    Window window;
} XDestroyWindowEvent;

Event Structure Members

event The window that selected the event.
window The window that was destroyed.

EnterNotify, LeaveNotify

—xcrossing

When Generated

EnterNotify and LeaveNotify events occur when the pointer enters or leaves a window.

When the pointer crosses a window border, a LeaveNotify event occurs in the window being left and an EnterNotify event occurs in the window being entered. Whether or not each event is queued for any application depends on whether any application selected the right event on the window in which it occured.

In addition, EnterNotify and LeaveNotify events are delivered to windows that are virtually crossed. These are windows that are between the origin and destination windows in the hierarchy but not on the screen. Further explanation of virtual crossing is provided two pages following.

Select With

Each of these events can be selected separately with XEnterWindowMask and XLeaveWindowMask.

XEvent Structure Name

typedef union _XEvent {
    ...
    XCrossingEvent xcrossing;
    ...
} XEvent;

Event Structure

typedef struct {
    int type;               /* of event */
    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;          /* 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 receiving 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;

Event Structure Members

The following list describes the members of the XCrossingEvent structure.

subwindow In a LeaveNotify event, if the pointer began in a child of the receiving window then the child member is set to the window ID of the child. Otherwise, it is set to None. For an EnterNotify event, if the pointer ends up in a child of the receiving window then the child member is set to the window ID of the child. Otherwise, it is set to None.
time The server time when the crossing event occurred, in milliseconds. Time is declared as unsigned long, so it wraps around when it reaches the maximum value of a 32 bit number (every 49.7 days).
x, y The point of entry or exit of the pointer relative to the event window.
x_root, y_root The point of entry or exit of the pointer relative to the root window.
mode Normal crossing events or those caused by pointer warps have mode NotifyNormal; events caused by a grab have mode NotifyGrab; and events caused by a released grab have mode NotifyUngrab.
detail The value of the detail member depends on the hierarchical relationship between the origin and destination windows and the direction of pointer transfer. Determining which windows receive events and with which detail members is quite complicated. This topic is described in the next section.
same_screen Indicates whether the pointer is currently on the same screen as this window. This is always True unless the pointer was actively grabbed before the automatic grab could take place.
focus If the receiving window is the focus window or a descendant of the focus window, the focus member is True; otherwise it is False.
state The state of all the buttons and modifier keys just before the event, represented by a mask of the button and modifier key symbols: Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, ShiftMask, ControlMask, LockMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.

Virtual Crossing and the detail Member

Virtual crossing occurs when the pointer moves between two windows that do not have a parent-child relationship. Windows between the origin and destination windows in the hierarchy receive EnterNotify and LeaveNotify events. The detail member of each of these events depends on the hierarchical relationship of the origin and destination windows and the direction of pointer transfer.

Virtual crossing is an advanced topic that you shouldn't spend time figuring out unless you have an important reason to use it. I have never seen an application that uses this feature, and I know of no reason for its extreme complexity. With that word of warning, proceed.

Let's say the pointer has moved from one window, the origin, to another, the destination. First we'll specify what types of events each window gets, and then the detail member of each of those events.

The window of origin receives a LeaveNotify event and the destination window receives an EnterNotify event, if they have requested this type of event. If one is an inferior of the other, the detail member of the event received by the inferior is NotifyAncestor and the detail of the event received by the superior is NotifyInferior. If the crossing is between parent and child, these are the only events generated.

However, if the origin and destination windows are not parent and child, other windows are virtually crossed and also receive events. If neither window is an ancestor of the other, ancestors of each window up to but not including the least common ancestor receive LeaveNotify events if they are in the same branch of the hierarchy as the origin and EnterNotify events if they are in the same branch as the destination. These events can be used to track the motion of the pointer through the hierarchy.

  • In the case of a crossing between a parent and a child of a child, the middle child receives a LeaveNotify with detail NotifyVirtual.
  • In the case of a crossing between a child and the parent of its parent, the middle child receives an EnterNotify with detail NotifyVirtual.
  • In a crossing between windows whose least common ancestor is two or more windows away, both the origin and destination windows receive events with detail NotifyNonlinear. The windows between the origin and the destination in the hierarchy, up to but not including their least common ancestor, receive events with detail NotifyNonlinearVirtual. The least common ancestor is the lowest window from which both are descendants.
  • If the origin and destination windows are on separate screens, the events and details generated are the same as for two windows not parent and child, except that the root windows of the two screens are considered the least common ancestor. Both root windows also receive events.

Table E-2 shows the event types generated by a pointer crossing from window A to window B when window C is the least common ancestor of A and B.

Table E-2. Border Crossing Events and Window Relationship

LeaveNotify EnterNotify
Origin window (A) Destination window (B)
Windows between A and B exclusive if A is inferior Windows between A and B exclusive if B is inferior
Windows between A and C exclusive Windows between B and C exclusive
Root window on screen of origin if different from screen of destination Root window on screen of destination if different from screen of origin

Table E-3 lists the detail members in events generated by a pointer crossing from window A to window B.

Table E-3. Event detail Member and Window Relationship

detail Flag Window Delivered To
NotifyAncestor Origin or destination when either is descendant
NotifyInferior Origin or destination when either is ancestor
NotifyVirtual Windows between A and B exclusive if either is descendant
NotifyNonlinear Origin and destination when A and B are two or more windows distant from least common ancestor C
NotifyNonlinearVirtual Windows between A and C exclusive and between B and C exclusive when A and B have least common ancestor C. Also on both root windows if A and B are on different screens.

For example, Figure E-1 shows the events that are generated by a movement from a window (window A) to a child (window B1) of a sibling (window B). This would generate three events: a LeaveNotify with detail NotifyNonlinear for the window A, an EnterNotify with detail NotifyNonlinearVirtual for its sibling window B, and an EnterNotify with detail NotifyNonlinear for the child (window B1).

images

Figure E-1. Events generated by a move between windows

EnterNotify and LeaveNotify events are also generated when the pointer is grabbed, if the pointer was not already inside the grabbing window. In this case, the grabbing window receives an EnterNotify and the window containing the pointer receives a LeaveNotify event, both with mode NotifyUngrab. The pointer position in both events is the position before the grab. The result when the grab is released is exactly the same except that the two windows receive EnterNotify instead of LeaveNotify and vice versa.

Figure E-2 demonstrates the events and details caused by various pointer transitions, indicated by heavy arrows.

images

Figure E-2. Border crossing events and detail member for pointer movement from window A to window B, for various window relationships

Expose

—xexpose

When Generated

Expose events are generated when a window becomes visible or a previously invisible part of a window becomes visible. Only InputOutput windows generate or need to respond to Expose events; InputOnly windows never generate or need to respond to them. The Expose event provides the position and size of the exposed area within the window, and a rough count of the number of remaining exposure events for the current window.

Select With

ExposureMask

XEvent Structure Name

typedef union _XEvent {
    ...
    XExposeEvent xexpose;
    ...
} XEvent;

Event Structure

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;
    int x, y;
    int width, height;
    int count;              /* if nonzero, at least this many more */
} XExposeEvent;

Event Structure Members

x, y The coordinates of the upper-left corner of the exposed region relative to the origin of the window.
width, height The width and height in pixels of the exposed region.
count The approximate number of remaining contiguous Expose events that were generated as a result of a single function call.

Notes

A single action such as a window movement or a function call can generate several exposure events on one window or on several windows. The server guarantees that all exposure events generated from a single action will be sent contiguously, so that they can all be handled before moving on to other event types. This allows an application to keep track of the rectangles specified in contiguous Expose events, set the clip_mask in a GC to the areas specified in the rectangle using XSetRegion or XSetClipRectangles, and then finally redraw the window clipped with the GC in a single operation after all the Expose events have arrived.

The last event to arrive is indicated by a count of 0. In Release 2, XUnionRectWithRegion can be used to add the rectangle in Expose events to a region before calling XSetRegion.

If your application is able to redraw partial windows, you can also read each exposure event in turn and redraw each area.

FocusIn, FocusOut

—xfocus

When Generated

FocusIn and FocusOut events occur when the keyboard focus window changes, as a result of an XSetInputFocus call. They are much like EnterNotify and LeaveNotify events except that they track the focus rather than the pointer.

Select With

FocusIn and FocusOut events are selected with FocusChangeMask. They cannot be selected separately.

XEvent Structure Name

typedef union _XEvent {
    ...
    XFocusChangeEvent xfocus;
    ...
} XEvent;

Event Structure

typedef struct {
    int type;               /* FocusIn or FocusOut */
    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 of event */
    int mode;               /* NotifyNormal, NotifyGrab, NotifyUngrab */
    int detail;             /* NotifyAncestor, NotifyVirtual, Notify-
                             * Inferior, NotifyNonLinear, NotifyNonLinear-
                             * Virtual, NotifyPointer, NotifyPointerRoot,
                             * NotifyDetailNone */
} XFocusChangeEvent;
typedef XFocusChangeEvent XFocusInEvent;
typedef XFocusChangeEvent XFocusOutEvent;

Event Structure Members

mode For events generated when the keyboard is not grabbed, mode is NotifyNormal; when the keyboard is grabbed, mode is NotifyGrab; and when a keyboard is ungrabbed, mode is NotifyUngrab.
detail The detail member identifies the relationship between the window that receives the event and the origin and destination windows. It will be described in detail after the description of which windows get what types of events.

Notes

The keyboard focus is a window that has been designated as the one to receive all keyboard input irrespective of the pointer position. Only the keyboard focus window and its descendants receive keyboard events. By default, the focus window is the root window. Since all Most window managers allow the user to set a focus window, to avoid the problem where the pointer sometimes gets bumped into the wrong window and your typing doesn't go to the intended window. If the pointer is pointing at the root window, all typing is usually lost since there is no application for this input to propagate to. Some applications may set the keyboard focus so that they can get all keyboard input for a given period of time, but this practice is not encouraged.

Focus events are used when an application wants to act differently when the keyboard focus is set to another window or to itself. FocusChangeMask. is used to select FocusIn and FocusOut events.

FocusOut events are delivered to the old focus window and FocusIn events to the window which receives the focus. Windows in between in the hierarchy are virtually crossed and receive focus change events depending on the relationship and direction of transfer between the origin and destination windows. Some or all of the windows between the window containing the pointer at the time of the focus change and that window's root can also receive focus change events. By checking the detail member of FocusIn and FocusOut events, an application can tell which of its windows can receive input.

The detail member gives clues about the relationship of the event receiving window to the origin and destination of the focus. The detail member of FocusOut and FocusIn events is analogous to the detail member of LeaveNotify and EnterNotify events, but with even more permutations to make life complicated.

Virtual Focus Crossing and the detail Member

We will now embark on specifying the types of events sent to each window and the detail member in each event, depending on the relative position in the hierarchy of the origin window (old focus), destination window (new focus), and the pointer window (window containing pointer at time of focus change). Don't even try to figure this out unless you have to.

Table E-4 shows the event types generated by a focus transition from window A to window B when window C is the least common ancestor of A and B, and P is the window containing the pointer. This table includes most of the events generated, but not all of them. It is quite possible for a single window to receive more than one focus change event from a single focus change.

Table E-4. FocusIn and FocusOut Events and Window Relationship

FocusOut FocusIn
origin window (A) destination window (B)
windows between A and B exclusive if A is inferior windows between A and B exclusive if B is inferior
windows between A and C exclusive windows between B and C exclusive
root window on screen of origin if different from screen of destination root window on screen of destination if different from screen of origin
pointer window up to but not including origin window if pointer window is descendant of origin pointer window up to but not including destination window if pointer window is descendant of destination
pointer window up to and including pointer window's root if transfer was from PointerRoot pointer window up to and including pointer window's root if transfer was to PointerRoot

Table E-5 lists the detail members in events generated by a focus transition from window A to window B, with P being the window containing the pointer.

Table E-5. Event detail Member and Window Relationship

detail Flag Window Delivered To
NotifyAncestor Origin or destination when either is descendant
NotifyInferior Origin or destination when either is ancestor
NotifyVirtual Windows between A and B exclusive if either is descendant
NotifyNonlinear Origin and destination when A and B are two or more windows distant from least common ancestor C
NotifyNonlinearVirtual Windows between A and C exclusive and between Band C exclusive when A and B have least common ancestor C. Also on both root windows if A and Bare on different screens
NotifyPointer Window P and windows up to but not including the origin or destination windows
NotifyPointerRoot Window P and all windows up to its root, and all other roots, when focus is set to or from PointerRoot
NotifyNone All roots, when focus is set to or from None

The following two pages show all the possible combinations of focus transitions and of origin, destination, and pointer windows and shows the types of events that are generated and their detail member. Solid lines indicate branches of the hierarchy. Dotted arrows indicate the direction of transition of the focus. At each end of this arrow are the origin and destination windows, windows A to B. Arrows ending in a bar indicate that the event type and detail described are delivered to all windows up to the bar.

In any branch, there may be windows that are not shown. Windows in a single branch between two boxes shown will get the event types and details shown beside the branch.

images

images

Figure E-3. FocusIn and FocusOut event schematics

FocusIn and FocusOut events are also generated when the keyboard is grabbed, if the focus was not already assigned to the grabbing window. In this case, all windows receive events as if the focus was set from the current focus to the grab window. When the grab is released, the events generated are just as if the focus was set back.

GraphicsExpose, NoExpose

—xnoexpose

When Generated

GraphicsExpose events indicate that the source area for a XCopyArea or XCopyPlane request was not available because it was outside the source window or obscured by a window. NoExpose events indicate that the source region was completely available.

Select With

These events are not selected with XSelectInput, but are sent if the GC in the XCopyArea or XCopyPlane request had its graphics_exposures flag set to True. If graphics_exposures is True in the GC used for the copy, either one NoExpose event or one or more GraphicsExpose events will be generated for every XCopyArea or XCopyPlane call made.

XEvent Structure Name

typedef union _XEvent {
    ...
    XNoExposeEvent xnoexpose;
    ...
} XEvent;

Event Structure

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 */
    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;

    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 */
    Drawable drawable;
    int major_code;         /* core is CopyArea or CopyPlane */
    int minor_code;         /* not defined in the core */
} XNoExposeEvent;

Event Structure Members

drawable A window or an off-screen pixmap. This specifies the destination of the graphics request that generated the event.
x, y The coordinates of the upper-left corner of the exposed region relative to the origin of the window.
width, height The width and height in pixels of the exposed region.
count The approximate number of remaining contiguous GraphicsExpose events that were generated as a result of the XCopyArea or XCopyPlane call.
major_code The graphics request used. This may be one of the symbols CopyArea or CopyPlane, or a symbol defined by a loaded extension.
minor_code Zero unless the request is part of an extension.

Notes

Expose events and GraphicsExpose events both indicate the region of a window that was actually exposed (x, y, width, and height). Therefore they can often be handled similarly.

GravityNotify

—xgravity

When Generated

GravityNotify events report when a window is moved because of a change in the size of its parent. This happens when the win_gravity attribute of the child window is something other than StaticGravity or UnmapGravity.

Select With

To receive this event type for a single window, specify the window ID of that window and use StructureNotifyMask as part of the event_mask argument to XSelectInput. To receive notification of movement due to gravity for a group of siblings, specify the parent window ID and use SubstructureNotifyMask.

XEvent Structure Name

typedef union _XEvent {
    ...
    XGravityEvent xgravity;
    ...
} XEvent;

Event Structure

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 event;
    Window window;
    int x, y;
} XGravityEvent;

Event Structure Members

event The window that selected the event.
window The window that was moved.
x, y The new coordinates of the window relative to its parent.

KeymapNotify

xkeymap—

When Generated

KeymapNotify events are reported immediately after EnterNotify or FocusIn events.

This is a way for the application to read the keyboard state as the application is “woken up,” since the two triggering events usually indicate that the application is about to receive user input.

Select With

KeymapStateMask

XEvent Structure Name

typedef union _XEvent {
    ...
    XKeymapEvent xkeymap;
    ...
} XEvent;

Event Structure

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;
    char key_vector[32];
} XKeymapEvent;

Event Structure Members

window Reports the window which was reported in the window member of the preceeding EnterNotify or FocusIn event.
key_vector A bit vector or mask, each bit representing one physical key, with a total of 256 bits. For a given key, its keycode is its position in the keyboard vector. You can also get this bit vector by calling XQueryKeymap.

Notes

The serial member of KeymapNotify does not contain the serial number of the most recent Protocol Request processed, because this event always follows immediately after FocusIn or EnterNotify events in which the serial member is valid.

KeyPress, KeyRelease

—xkey

When Generated

KeyPress and KeyRelease events are generated for all keys, even those mapped to modifier keys such as Shift or Control.

Select With

Each type of keyboard event may be selected separately with KeyPressMask and KeyReleaseMask.

XEvent Structure Name

typedef union _XEvent {
    ...
    XKeyEvent xkey;
    ...
} XEvent;

Event Structure

typedef struct {
    int type;              /* of event */
    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;         /* 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 coords relative to receiving window */
    int x_root, y_root;    /* coordinates relative to root */
    unsigned int state;    /* modifier key and button mask */
    unsigned int keycode;  /* server-dependent code for key */
    Bool same_screen;      /* same screen flag */
} XKeyEvent;
    typedef XKeyEvent XKeyPressedEvent;
    typedef XKeyEvent XKeyReleasedEvent;

Event Structure Members

subwindow If the source window is the child of the receiving window, then the subwindow member is set to the ID of that child.
time The server time when the button event occurred, in milliseconds. Time is declared as unsigned long, so it wraps around when it reaches the maximum value of a 32-bit number (every 49.7 days).
x, y If the receiving window is on the same screen as the root window specified by root, then x and y are the pointer coordinates relative to the receiving window's origin. Otherwise, x and y are zero.

When active button grabs and pointer grabs are in effect (see Volume One, Section 9.4), the coordinates relative to the receiving window may not be within the window (they may be negative or greater than window height or width).

x_root, y_root The pointer coordinates relative to the root window which is an ancestor of the event window. If the pointer was on a different screen, these are zero.
state The state of all the buttons and modifier keys just before the event, represented by a mask of the button and modifier key symbols: Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, ShiftMask, ControlMask, LockMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.
keycode The keycode member contains a server-dependent code for the key that changed state. As such it should be translated into the portable symbol called a keysym before being used. It can also be converted directly into ASCII with XLookupString. For a description and examples of how to translate keycodes, see Volume One, Section 9.1.1.

Notes

Remember that not all hardware is capable of generating release events, and that only the main keyboard (a-z, A-Z, 0-9), Shift, and Control keys are always found.

Keyboard events are analogous to button events, though of course there are many more keys than buttons, and the keyboard is not automatically grabbed between press and release.

All the structure members have the same meaning as described for ButtonPress and ButtonRelease events except that button is replaced by keycode.

MapNotify, UnmapNotify

—xmap, xunmap

When Generated

The X server generates MapNotify and UnmapNotify events when a window changes state from unmapped to mapped or vice versa.

Select With

To receive these events on a single window, use StructureNotifyMask in the call to XSelectInput for the window. To receive these events for all children of a particular parent, specify the parent window ID and use SubstructureNotifyMask.

XEvent Structure Name

typedef union _XEvent {
    ...
    XMapEvent xmap;
    XUnmapEvent xunmap;
    ...
} XEvent;

Event Structure

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 event;
    Window window;
    Bool override_redirect; /* Boolean, is override set */
} XMapEvent;

    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 event;
    Window window;
    Bool from_configure;
} XUnmapEvent;

Event Structure Members

event The window that selected this event.
window The window that was just mapped or unmapped.
override_redirect (XMapEvent only) True or False. The value of the override_redirect attribute of the window that was just mapped.
from_configure (XUnmapEvent only) 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. See the description of the win_gravity attribute in Volume One, Section 4.3.4. False otherwise.

MappingNotify

—xmapping

When Generated

MappingNotify events occur when any of the following are changed by another client: the mapping between physical keyboard keys (keycodes) and keysyms; the mapping between modifier keys and logical modifiers; or the mapping between physical and logical pointer buttons. These events are triggered by a call to XSetModifierMapping or XSetPointerMapping if the return status is MappingSuccess, or by any call to ChangeKeyboardMapping.

This event type should not be confused with the event that occurs when a window is mapped; that is a MapNotify event. Nor should it be confused with the KeymapNotify event, which reports the state of the keyboard as a mask instead of as a keycode.

Select With

The X server sends MappingNotify events to all clients. It is never selected, and cannot be masked with the window attributes.

XEvent Structure Name

typedef union _XEvent {
    ...
    XMappingEvent xmapping;
    ...
} XEvent;

Event Structure

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;         /*  unused */
    int request;           /*  one of MappingModifier, MappingKeyboard,
                            *  MappingPointer */
    int first_keycode;     /*  first keycode */
    int count;             /*  range of change with first_keycode*/
} XMappingEvent;

Event Structure Members

request The kind of mapping change that occurred: MappingModifier for a successful XSetModifierMapping (keyboard Shift, Lock, Control, Meta keys), MappingKeyboard for a successful XChangeKeyboardMapping (other keys), and MappingPointer for a successful XSetPointerMapping (pointer button numbers).
first_keycode If the request member is MappingKeyboard or MappingModifier, then first_keycode indicates the first in a range of keycodes with altered mappings. Otherwise it is not set.
count If the request member is MappingKeyboard or MappingModifier, then count indicates the number of keycodes with altered mappings. Otherwise it is not set.

Notes

If the request member is MappingKeyboard, clients should call XRefreshKeyboardMapping.

The normal response to a request member of MappingPointer or MappingModifier is no action. This is because the clients should use the logical mapping of the buttons and modifiers to allow the user to customize the keyboard if desired. If the application requires a particular mapping regardless of the user's preferences, it should call XGetModifierMapping or XGetPointerMapping to find out about the new mapping.

MapRequest

—xmaprequest

When Generated

The X server generates MapRequest events when the functions XMapRaised and XMapWindow are called. If this event type is selected, the window is not mapped. This gives the client that selects this event (usually the window manager) the opportunity to revise the size or position of the window before executing the map request itself, or deny the request.

Select With

To receive this event type, you specify the window ID of the parent of the receiving window and pass SubstructureRedirectMask as the event_mask argument to XSelectInput. In addition, the override_redirect member of the XSetwindowAttributes structure for the specified window must be False.

XEvent Structure Name

typedef union _XEvent {
    ...
    XMapRequestEvent xmaprequest;
    ...
} XEvent;

Event Structure

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 parent;
    Window window;
} XMapRequestEvent;

Event Structure Members

parent The ID of the parent of the window being mapped.
window The ID of the window being mapped.

MotionNotify

xmotion—

When Generated

The X server generates MotionNotify events when the user moves the pointer, or when a program warps the pointer to a new position within a single window.

Select With

This event type is selected with PointerMotionMask, PointerMotionHintMask, ButtonMotionMask, Button1MotionMask, Button2MotionMask, Button3MotionMask, Button4MotionMask, and Button5MotionMask. These masks determine the specific conditions under which the event is generated. See Volume One, Section 8.3.3.3 for a description of selecting button events.

XEvent Structure Name

typedef union _XEvent {
    ...
    XMotionEvent xmotion;
    ...
} XEvent;

Event Structure

typedef struct {
    int type;               /* of event */
    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;          /* 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 coords relative to receiving window *
    int x_root, y_root;     /* coordinates relative to root */
    unsigned int state;     /* button and modifier key mask */
    char is_hint;           /* is this a motion hint */
    Bool same_screen;       /* same screen flag */
} XMotionEvent;
typedef XMotionEvent XPointerMovedEvent;

Event Structure Members

subwindow If the source window is the child of the receiving window, then the subwindow member is set to the ID of that child.
time The server time when the button event occurred, in milliseconds. Time is declared as unsigned long, so it wraps around when it reaches the maximum value of a 32 bit number (every 49.7 days).
x, y If the receiving window is on the same screen as the root window specified by root, then x and y are the pointer coordinates relative to the receiving window's origin. Otherwise, x and y are zero.

When active button grabs and pointer grabs are in effect (see Volume One, Section 9.4), the coordinates relative to the receiving window may not be within the window (they may be negative or greater than window height or width).

x_root, y_root The pointer coordinates relative to the root window which is an ancestor of the event window. If the pointer was on a different screen, these are zero.
state The state of all the buttons and modifier keys just before the event, represented by a mask of the button and modifier key symbols: Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, ShiftMask, ControlMask, LockMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, and Mod5Mask.
is_hint Either the constant NotifyNormal or NotifyHint. NotifyHint indicates that the PointerMotionHintMask was selected. In this case, just one event is sent when the mouse moves, and the current position can be found by calling XQueryPointer, or by examining the motion history buffer with XGetMotionEvents, if a motion history buffer is available on the server. NotifyNormal indicates that the event is real, but it may not be up to date since there may be many more later motion events on the queue.
same_screen Indicates whether the pointer is currently on the same screen as this window. This is always True unless the pointer was actively grabbed before the automatic grab could take place.

Notes

If the processing you have to do for every motion event is fast, you can probably handle all of them without requiring motion hints. However, if you have extensive processing to do for each one, you might be better off using the hints and calling XQueryPointer or using the history buffer if it exists. XQueryPointer is a round-trip request, so it can be slow.

EnterNotify and LeaveNotify events are generated instead of MotionEvents if the pointer starts and stops in different windows.

PropertyNotify

xproperty—

When Generated

PropertyNotify events indicate that a property of a window has changed, or at least that a zero-length append has been done in order to get the X server time.

Select With

They can be selected with PropertyChangeMask.

XEvent Structure Name

typedef union _XEvent {
    ...
    XPropertyEvent xproperty;
    ...
} XEvent;

Event Structure

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;
    Atom atom;
    Time time;
    int state;            /* NewValue, Deleted */
} XPropertyEvent;

Event Structure Members

window The window whose property was changed, not the window that selected the event.
atom The property that was changed.
state Either PropertyNewValue or PropertyDelete. Whether the property was changed to a new value or deleted.
time The time member specifies the server time when the property was changed.

ReparentNotify

—xreparent

When Generated

ReparentNotify events report information about the changing of a window's parent.

Select With

To receive this event type, specify the window ID of the old or the new parent window and pass SubstructureNotifyMask as the event_mask argument to XSelectInput, or specify the window ID and pass StructureNotifyMask.

The X server generates this event type when it reparents the specified window.

XEvent Structure Name

typedef union _XEvent {
    ...
    XReparentEvent xreparent;
    ...
} XEvent;

Event Structure

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 event;
    Window window;
    Window parent;
    int x, y;
    Bool override_redirect;
} XReparentEvent;

Event Structure Members

window the window whose parent window was changed.
parent The new parent of the window.
x, y the coordinates of the upper-left pixel of the window's border relative to the new parent window's origin.
override_redirect The override_redirect attribute of the reparented window. If True, it indicates that the client wants this window to be immune to meddling by the window manager. Window managers normally should not have reparented this window to begin with.

ResizeRequest

xresizerequest—

When Generated

ResizeRequest events report another client's attempt to change the size of a window. The X server generates this event type when another client calls XConfigureWindow, XResizeWindow, or XMoveResizeWindow. If this event type is selected, the window is not resized. This gives the client that selects this event (usually the window manager) the opportunity to revise the new size of the window before executing the resize request itself, or to deny the request

Select With

To receive this event type, specify a window ID and pass ResizeRedirectMask as part of the event_mask argument to XSelectInput. Only one client can select this event on a particular window. When selected, this event is triggered instead of resizing the window.

XEvent Structure Name

typedef union _XEvent {
    ...
    XResizeRequestEvent xresizerequest;
    ...
} XEvent;

Event Structure

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;
    int width, height;
} XResizeRequestEvent;

Event Structure Members

window The window whose size another client attempted to change.
width, height The requested size of the window, not including its border.

SelectionClear

—xselectionclear

When Generated

The X server reports SelectionClear events to the current owner of a selection when a new owner is being defined.

Select With

This event is not selected. It is sent to the previous selection owner when another client calls XSetSelectionOwner for the same selection.

XEvent Structure Name

typedef union _XEvent {
    ...
    XSelectionClearEvent xselectionclear;
    ...
} XEvent;

Event Structure

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;
    Atom selection;
    Time time;
} XSelectionClearEvent;

Event Structure Members

window The window that is receiving the event and losing the selection.
selection The selection atom specifying the selection that is changing ownership.
time The last-change time recorded for the selection.

SelectionNotify

xselection—

When Generated

SelectionNotify events are sent only by clients, not by the server. They are sent by calling XSendEvent. The owner of a selection sends this event to a requester (a client that calls XConvertSelection for a given property) when a selection has been converted and stored as a property, or when a selection conversion could not be performed (indicated with property None).

Select With

There is no event mask for SelectionNotify events and they are not selected with XSelectInput. Instead, XSendEvent directs them to a specific window, which is given as a window ID: the PointerWindow or the InputFocus.

XEvent Structure Name

typedef union _XEvent {
    ...
    XSelectionEvent xselection;
    ...
} XEvent;

Event Structure

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 requester;      /* must be next after type */
    Atom selection;
    Atom target;
    Atom property;         /* Atom or None */
    Time time;
} XSelectionEvent;

Event Structure Members

The members of this structure have the values specified in the XConvertSelection call that triggers the selection owner to send this event, except that the property member will return either the atom specifying a property on the requestor window with the data type specified in target, or it will be None, which indicates that the data could not be converted into the target type.

SelectionRequest

—xselectionrequest

When Generated

SelectionRequest events are sent to the owner of a selection when another client requests the selection by calling XConvertSelection.

Select With

There is no event mask for SelectionRequest events and they are not selected with XSelectInput.

XEvent Structure Name

typedef union _XEvent {
    ...
    XSelectionRequestEvent xselectionrequest;
    ...
} XEvent;

Event Structure

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 owner;         /* must be next after type */
    Window requester;
    Atom selection;
    Atom target;
    Atom property;
    Time time;
} XSelectionRequestEvent;

Event Structure Members

The members of this structure have the values specified in the XConvertSelection call that triggers this event.

The owner should convert the selection based on the specified target type, if possible. If a property is specified, the owner should store the result as that property on the requester window, and then send a SelectionNotify event to the requester by calling XSendEvent. If the selection cannot be converted as requested, the owner should send a SelectionNotify event with property set to the constant None.

VisibilityNotify

xvisibility—

When Generated

VisibilityNotify events report any change in the visibility of the specified window. This event type is never generated on windows whose class is InputOnly. All of the window's subwindows are ignored when calculating the visibility of the window.

Select With

This event is selected with VisibilityChangeMask.

XEvent Structure Name

typedef union _XEvent {
    ...
    XVisibilityEvent xvisibility;
    ...
} XEvent;

Event Structure

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;
    int state;             /* Visibility Unobscured,*/
                           /* Visibility Partially Obscured, or */
                           /* Visibility Obscured */

} XVisibilityEvent;

Event Structure Members

state A symbol indicating the final visibility status of the window: VisibilityUnobscured, VisibilityPartiallyObscured, or VisibilityObscured.

Notes

Table E-5 lists the transitions that generate VisibilityNotify events and the corresponding state member of the XVisibilityEvent structure.

Table E-6. The State Element of the XVisibilityEvent Structure

images

Get Xlib Reference Manual for Version 11 of the X Window System now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.