1. When a graphics exposure occurs, the client calculates where to draw points into the exposed area by referring to members of the expose event data structure.
2. The user-defined START_SCROLL routine copies the window contents, less one row of pixels, to the top of the window. The result leaves an exposed area one pixel high at the bottom of the window.
3. The COPY AREA routine copies new points into the exposed area.

Figure 9-10 Window Scrolling

Xlib reports key press and key release events to interested clients. To receive event notification of key presses and releases, pass the window identifier and either the x$m_key_press mask or the x$m_key_release mask when using the selection method described in Section 9.2.

Xlib uses a key event data structure to report key presses and releases to interested clients whenever any key changes state, even when the key is mapped to modifier bits.

9.8 Window State Notification Events

Xlib reports events related to the state of a window when a client does one of the following:

• Circulates a window, changing the order of the window hierarchy
• Configures a window, changing its position, size, or border
• Creates a window
• Destroys a window
• Changes the size of a parent, causing Xlib to move a child window
• Maps a window
• Reparents a window
• Unmaps a window
• Changes the visibility of a window

This section describes handling events that result from these operations. For more information about these events, see the X Window System.

9.8.1 Handling Window Circulation

To receive notification when a client circulates a window, pass either the window identifier and the x$m_structure_notify mask or the identifier of the parent window and the x$m_substructure_notify mask when using a selection method described in Section 9.2.

Xlib reports to interested clients a change in the hierarchical position of a window when a client calls the CIRCULATE SUBWINDOWS, CIRCULATE SUBWINDOWS UP, or CIRCULATE SUBWINDOWS DOWN routines.

Xlib uses the circulate event data structure to report circulate events.

9.8.2 Handling Changes in Window Configuration

To receive notification when window size, position, border, or stacking order changes, pass either the window identifier and the x$m_structure_notify mask or the identifier of the parent window and the x$m_substructure_notify mask when using the selection method described in Section 9.2.

Xlib reports changes in window configuration when any one of the following occurs:

• Window size, position, border, and stacking order change when a client calls the CONFIGURE WINDOW routine.
• Window position in the stacking order changes when a client calls the LOWER WINDOW, RAISE WINDOW, or RESTACK WINDOW routine.
• Window moves when a client calls the MOVE WINDOW routine.
• Window size changes when a client calls the RESIZE WINDOW routine.
• Window size and location change when a client calls the MOVE RESIZE WINDOW routine.
• Border width changes when a client calls the SET WINDOW BORDER WIDTH routine.

For more information about these routines, see Chapter 3.

Xlib reports changes to interested clients using the configure event data structure.

9.8.3 Handling Window Creations

To receive notification when a client creates a window, pass the identifier of the parent window and the x$m_substructure_notify mask when using the selection method described in Section 9.2.

Xlib reports window creations using the create window event data structure.

9.8.4 Handling Window Destructions

To receive notification when a client destroys a window, pass either the window identifier and the x$m_structure_notify mask or the identifier of the parent window and the x$m_substructure_notify mask when using the selection method described in Section 9.2.

Xlib reports window destructions using the destroy window event data structure.

9.8.5 Handling Changes in Window Position

To receive notification when a window is moved because a client has changed the size of its parent, pass the window identifier and the x$m_structure_notify mask or the identifier of the parent window and the x$m_substructure_notify mask when using the selection method described in Section 9.2.

Xlib reports window gravity events using the gravity event data structure.

9.8.6 Handling Window Mappings

To receive notification when a window changes state from unmapped to mapped, pass either the window identifier and the x$m_structure_notify mask or the identifier of the parent window and the x$m_substructure_notify mask when using the selection method described in Section 9.2.

Xlib reports window gravity events using the map event data structure.

9.8.7 Handling Key, Keyboard, and Pointer Mappings

All clients receive notification of changes in key, keyboard, and pointer mapping. Xlib reports these events when a client has successfully done one of the following:

• Called the SET MODIFIER MAPPING routine to indicate which keycodes are modifiers
• Changed keyboard mapping using the CHANGE KEYBOARD MAPPING routine
• Set pointer mapping using the SET POINTER MAPPING routine

Xlib reports key, keyboard, and pointer mapping events using the mapping event data structure.

9.8.8 Handling Window Reparenting

To receive notification when the parent of a window changes, pass either the window identifier and the x$m_structure_notify mask or the identifier of the parent window and the x$m_substructure_notify mask when using the selection method described in Section 9.2.

Xlib reports window reparenting events using the reparent event data structure.

9.8.9 Handling Window Unmappings

To receive notification when a window changes from mapped to unmapped, pass either the window identifier and the x$m_structure_notify mask or the identifier of the parent window and the x$m_substructure_notify mask when using the selection method described in Section 9.2.

Xlib reports window unmapping events using the unmap event data structure.

9.8.10 Handling Changes in Window Visibility

All or part of a window is visible if it is mapped to a screen, if all of its ancestors are mapped, and if it is at least partially visible on the screen. To receive notification when the visibility of a window changes, pass the window identifier and the x$m_structure_notify mask when using the selection method described in Section 9.2.

Xlib reports changes in visibility to interested clients using the visibility event data structure.

9.9 Key Map State Events

Xlib reports changes in the state of the key map immediately after every enter notify and focus in event.

To receive notification of key map state events, pass the window identifier and the x$m_keymap_state mask when using the selection method described in Section 9.2.

Xlib uses the keymap event data structure to report changes in the key map state.

9.10 Color Map State Events

Xlib reports a color map event when the window manager installs, changes, or removes the color map.

To receive notification of color map events, pass the window identifier and the x$m_colormap_change mask when using the selection method described in Section 9.2.

Xlib reports color map events to interested clients when the following occur:

• A client sets the color map member of the set window attributes data structure by calling CHANGE WINDOW ATTRIBUTES. See Chapter 3 for more information on the data structure and routine.
• A client calls the FREE COLORMAP routine. See Section 5.5 for more information about FREE COLORMAP.
• The window manager installs or removes a color map in response to either a client call of the INSTALL COLORMAP or UNINSTALL COLORMAP routine.

Xlib reports color map events using the color map event data structure.

9.11 Client Communication Events

Xlib reports an event when one of the following occurs:

• One client notifies another client that an event has happened.
• A client changes, deletes, rotates, or gets a property.
• A client loses ownership of a window.
• A client requests ownership of a window.

This section describes how to handle communication between clients.

9.11.1 Handling Event Notification from Other Clients

Clients can notify each other of events by calling the SEND EVENT routine.

Xlib sends notification between clients using the client message event data structure.

9.11.2 Handling Changes in Properties

As Chapter 3 notes, a property associates a constant with data of a particular type. Xlib reports a property event when a client does one of the following:

• Changes a property
• Rotates a window property
• Gets a property
• Deletes a property

To receive information about property changes, pass the window identifier and the x$m_property_change mask when using the selection method described in Section 9.2.

Xlib reports changes in properties to interested clients using the property event data structure.

9.11.3 Handling Changes in Selection Ownership

Clients receive notification automatically when they are losing ownership of a window. Xlib reports the event when a client takes ownership of a window by calling the SET SELECTION OWNER routine.

To report the event, Xlib uses the selection clear event data structure.

9.11.4 Handling Requests to Convert a Selection

The server issues a selection request event to the owner of a selection when a client calls the CONVERT SELECTION routine. For information about the CONVERT SELECTION routine, see Section 3.8.

To report the event, Xlib uses the selection request event data structure.

9.11.5 Handling Requests to Notify of a Selection

The server issues a selection notify event to the requestor of a selection after the selection has been converted and stored as a property.

For information about the CONVERT SELECTION routine, see Section 3.8. To report the event, Xlib uses the selection event data structure.

9.12 Event Queue Management

Xlib maintains an input queue known as the event queue. When an event occurs, the server sends the event to Xlib, which places it at the end of an event queue. By using routines described in this section, the client can check, remove, and process the events on the queue. As the client removes an event, remaining events move up the event queue.

Certain routines may block or prevent other routine calls from accessing the event queue. If the blocking routine does not find an event that the client is interested in, Xlib flushes the output buffer and waits until an event is received from the server.

9.12.1 Checking the Contents of the Event Queue

To check the event queue without preventing other routines from accessing the queue, use the EVENTS QUEUED routine. Clients can check events already queued by calling the EVENTS QUEUED routine and specifying one of the following constants:

x$c_queued_already	Returns the number of events already in the event queue and never performs a system call.
x$c_queued_after_flush	Returns the number of events in the event queue if the value is a nonzero. If there are no events in the queue, this routine flushes the output buffer, attempts to read more events out of the client connection, and returns the number read.
x$c_queued_after_reading	Returns the number of events already in the event queue if the value is a nonzero. If there are no events in the queue, this routine attempts to read more events out of the client connection without flushing the output buffer and returns the number read.

To return the number of events in the event queue, use the PENDING routine. If there are no events in the queue, PENDING flushes the output buffer, attempts to read more events out of the client connection, and returns the number read. The PENDING routine is identical to EVENTS QUEUED with constantx$c_queued_after_flush specified.

9.12.2 Returning the Next Event on the Queue

To return the first event on the event queue and copy it into the specified event data structure, use the NEXT EVENT and PEEK EVENT routines. NEXT EVENT returns the first event, copies it into an EVENT structure, and removes it from the queue. PEEK EVENT returns the first event, copies it into an event data structure, but does not remove it from the queue. In both cases, if the event queue is empty, the routine flushes the output buffer and blocks until an event is received.

9.12.3 Selecting Events That Match User-Defined Routines

Xlib enables the client to check all the events on the queue for a specific type of event by specifying a client-defined routine known as a predicate procedure. The predicate procedure determines if the event on the queue is one that the client is interested in.

The client calls the predicate procedure from inside the event routine. The predicate procedure should determine only if the event is useful and must not call Xlib routines. The predicate procedure is called once for each event in the queue until it finds a match.

Table 9-11 lists routines that use a predicate procedure and indicates whether or not the routine blocks.

Table 9-11 Selecting Events Using a Predicate Procedure

Routine	Description	Blocking/ No Blocking
IF EVENT	Checks the event queue for the specified event. If the event matches, removes the event from the queue. This routine is also called each time an event is added to the queue.	Blocking
CHECK IF EVENT	Checks the event queue for the specified event. If the event matches, removes the event from the queue. If the predicate procedure does not find a match, it flushes the output buffer.	No blocking
PEEK IF EVENT	Checks the event queue for the specified event but does not remove it from the queue. This routine is also called each time an event is added to the queue.	Blocking

9.12.4 Selecting Events Using an Event Mask

Xlib enables a client to process events out of order by specifying a window identifier and one of the event masks listed in Table 9-3 when calling routines listed in Table 9-12.

For example, the following specifies keyboard events on window WINDOW by using the event mask name constant x$c_keymap_state_mask.

. . . CALL X$WINDOW_EVENT(DPY, WINDOW, 1 X$C_KEYMAP_STATE_MASK, EVENT)

Table 9-12 lists routines that use event or window masks and indicates whether the routine blocks.

Table 9-12 Routines to Select Events Using a Mask

Routine	Description	Blocking/ No Blocking
WINDOW EVENT	Searches the event queue and removes the next event that matches both the specified window and event mask	Blocking
CHECK WINDOW EVENT	Searches the event queue, then the events available on the server connection, and removes the first event that matches the specified event and window mask	No blocking
MASK EVENT	Searches the event queue and removes the next event that matches the event mask	Blocking
CHECK MASK EVENT	Searches the event queue, then the events available on the server connection, and removes the next event that matches an event mask	No blocking
CHECK TYPED EVENT	Returns the next event in the queue that matches an event type	No blocking
CHECK TYPED WINDOW EVENT	Searches the event queue, then the events available on the server connection, and removes the next event that matches the specified type and window	No blocking

9.12.5 Putting Events Back on Top of the Queue

To push an event back onto the top of the event queue, use the PUT BACK EVENT routine. PUT BACK EVENT is useful when a client returns an event from the queue and decides to use it later. There is no limit to how many times in succession PUT BACK EVENT can be called.

9.12.6 Sending Events to Other Clients

To send an event to a client, use the SEND EVENT routine. For example, owners of a selection should use this routine to send a SELECTION NOTIFY event to a requestor when a selection has been converted and stored as a property.

9.13 Error Handling

Xlib has two default error handlers. One manages fatal errors, such as when the connection to a display is severed due to a system failure. The other handles error events from the server. The default error handlers print an explanatory message and text and then exit.

Each of these error handlers can be replaced by client error handling routines. If a client-supplied routine is passed a null pointer, Xlib reinvokes the default error handler.

This section describes the Xlib event error handling resources including enabling synchronous operation, handling server errors, and handling input/output (I/O) errors.

9.13.1 Enabling Synchronous Operation

When debugging programs, it is convenient to require Xlib to behave synchronously so that errors are reported at the time they occur.

To enable synchronous operation, use the SYNCHRONIZE routine. The client passes the display argument and the onoff argument. The onoff argument passes either a value of zero (disabling synchronization) or a nonzero value (enabling synchronization).