HP OpenVMS Systems Documentation

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

• A destination region could not be computed due to an obscured or out-of-bounds source region. For information about destination and source regions, see Chapter 6.
• A graphics request exposes one or more regions. If the request exposes more than one region, Xlib reports them continuously.

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.

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.

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.

#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

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:

• 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 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:

• 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 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:

• 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 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:

• 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 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:

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.