VMS DECwindows Guide to Xlib (Release 4) Programming: MIT C Binding
Previous Contents Index

9.6.2 Handling Graphics Exposures

Xlib reports graphics exposures when one of the following conditions occurs:

Instead of using the SELECT INPUT routine to indicate an interest in graphics exposure events, assign a value of true to the graphics_exposures member of the GC values data structure. Clients can set the value to true at the time they create a graphics context. If a graphics context exists, use the SET GRAPHICS EXPOSURES routine to set the value of the field. For information about creating a graphics context and using the SET GRAPHICS EXPOSURES routine, see Chapter 4.

Xlib uses the graphics expose event data structure to report graphics exposures. The following illustrates the data structure: 


typedef struct { 
        int type; 
        unsigned long serial; 
        Bool send_event;  
        Display *display; 
        Drawable drawable; 
        int x, y; 
        int width, height; 
        int count;    
        int major_code; 
        int minor_code; 
} XGraphicsExposeEvent;

Table 9-9 describes members of the graphics expose event data structure.

Table 9-9 Graphics Expose Event Data Structure Members
Member Name Contents
type Value defined by the GraphicsExpose constant.
serial Number of the last request processed by the server.
send_event Value defined by the constant true if the event came from a SEND EVENT request.
display Address of the display on which the event occurred.
drawable Drawable reporting the event.
x The x value of the coordinates that define the upper left corner of the exposed region. The coordinates are relative to the origin of the drawable.
y The y value of the coordinates that define the upper left corner of the exposed region. The coordinates are relative to the origin of the drawable.
width Width of the exposed region.
height Height of the exposed region.
count Number of exposure events that are to follow. If Xlib sets the count to zero, no more exposure events follow for this window.
major_code Indicates whether the graphics request was a copy area or a copy plane.
minor_code The value zero. Reserved for use by extensions.

Xlib uses the no expose event data structure to report when a graphics request that might have produced an exposure did not. The following illustrates the data structure: 


typedef struct { 
        int type; 
        unsigned long serial; 
        Bool send_event; 
        Display *display; 
        Drawable drawable; 
        int major_code;   
        int minor_code;  
} XNoExposeEvent;

Table 9-10 describes members of the no expose event data structure.

Table 9-10 No Expose Event Data Structure Members
Member Name Contents
type Value defined by the NoExpose constant.
serial Number of the last request processed by the server.
send_event Value defined by the constant true if the event came from a SEND EVENT request.
display Address of the display on which the event occurred.
drawable Window or pixmap reporting the event.
major_opcode Indicates whether the graphics request was a copy area or a copy plane.
minor_opcode The value zero. Reserved for use by extensions.

Example 9-5 illustrates handling graphics exposure events. The program checks for graphics exposures and no exposures to scroll up a window.

Figure 9-2 shows the resulting output of the program.

Example 9-5 Handling Graphics Exposures 

#define scrollPixels    1 
#define windowWidth     600 
#define windowHeight    600 
             
Display *dpy; 
Window win; 
GC gc;                                                                        
Screen *screen; 
int n; 
int ButtonIsDown; 
int vY = 0; 
                    .
                    .
                    .
 
 
/**** Handle events *****/ 
static void doHandleEvents( ) 
{ 
    XEvent event;         
 
    for ( ; ; ) { 
        XNextEvent(dpy, &event); 
        switch (event.type) {                                                 
            case Expose:                doExpose(&event); break; 
            case ButtonPress:           doButtonPress(&event); break; 
            case GraphicsExpose:        doGraphicsExpose(&event); break; 
            case ButtonRelease:         doButtonRelease(&event); break; 
            case NoExpose:              doNoExpose(&event); break; 
        } 
    }                                           
} 
 
/***** Write a message *****/ 
static void doExpose(eventP) 
XEvent *eventP; 
{ 
    char message1[ ] = {"To scroll, press MB1."};  
    char message2[ ] = {"To exit, click MB2."};           
    
    XDrawImageString(dpy, win, gc, 150, 25, message1, strlen(message1)); 
    XDrawImageString(dpy, win, gc, 150, 50, message2, strlen(message2)); 
} 
 
/***** Start a scroll operation *****/ 
static void startScroll() 
{ 
(1)  XCopyArea(dpy, win, win, gc, 0, scrollPixels, 
        windowWidth, windowHeight, 0, 0); 
    vY += scrollPixels; 
} 
 
/***** Copy the area *****/ 
static void doButtonPress(eventP)                                             
XEvent *eventP; 
{ 
    if (eventP->xbutton.button == Button2) sys$exit(1); 
    ButtonIsDown = 1; 
    startScroll(); 
    return; 
}        
 
/***** Draw points into the exposed area *****/ 
static void doGraphicsExpose(eventP) 
XEvent *eventP; 
{ 
(2)  int x = eventP->xgraphicsexpose.x; 
    int y = eventP->xgraphicsexpose.y; 
    int width = eventP->xgraphicsexpose.width;                                
    int height = eventP->xgraphicsexpose.height; 
    int px, py;   
 
    for (py=y; py<(y+height); py++) 
        for (px=x; px<(x+width); px++) 
            if (!((px+py+vY) % 10)) XDrawPoint(dpy, win, gc, px, py); 
 
    if (ButtonIsDown) startScroll(); 
 
    return; 
} 
 
/***** Quit scrolling when the button is released *****/ 
static void doButtonRelease(eventP) 
XEvent *eventP;                                                               
{ 
    ButtonIsDown = 0; 
    return; 
}                 
 
/***** Draw points in the exposed area when window is obscured *****/ 
static void doNoExpose(eventP) 
XEvent *eventP; 
{                                               
    if (ButtonIsDown) startScroll(); 
    return; 
}

  1. The client-defined startScroll 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.
  2. 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.

Figure 9-2 Window Scrolling

9.7 Key Events

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 KeyPressMask mask or the KeyReleaseMask 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:

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 StructureNotifyMask mask or the identifier of the parent window and the SubstructureNotifyMask 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 routine.

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 StructureNotifyMask mask or the identifier of the parent window and the constant SubstructureNotifyMask when using the selection method described in Section 9.2.

Xlib reports changes in window configuration when the following occur:

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 constant SubstructureNotifyMask 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 constant StructureNotifyMask or the identifier of the parent window and the SubstructureNotifyMask 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 StructureNotifyMask mask or the identifier of the parent window and the SubstructureNotifyMask 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 StructureNotifyMask mask or the identifier of the parent window and the SubstructureNotifyMask mask when using the selection method described in Section 9.2.

Xlib reports window mapping 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:

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 StructureNotifyMask mask or the identifier of the parent window and the SubstructureNotifyMask 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 StructureNotifyMask mask or the identifier of the parent window and the SubstructureNotifyMask 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 StructureNotifyMask 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 KeymapStateMask 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 ColormapChangeMask mask when using the selection method described in Section 9.2.

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

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:

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:

To receive information about property changes, pass the window identifier and the PropertyChangeMask 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 lose ownership of a selection in a window. Xlib reports the event when a client takes ownership of a selection 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.6.

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 after a client calls the CONVERT SELECTION routine. The owner of the selection being converted should initiate this event by calling SEND EVENT when either the selection has been converted and stored as a property or the selection conversion could not be performed. For information about converting selections, see Section 3.6.

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:
QueuedAlready Returns the number of events already in the event queue and never performs a system call.
QueuedAfterFlush 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.
QueuedAfterReading 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 constant QueuedAfterFlush specified.

Previous Next Contents Index