HP OpenVMS Systems Documentation

An event is a report of either a change in the state of a device (such as a mouse) or the execution of a routine called by a client. An event can be either unsolicited or solicited. Typically, unsolicited events are reports of keyboard or pointer activity. Solicited events are Xlib responses to calls by clients.

Xlib reports events asynchronously. When any event occurs, Xlib processes the event and sends it to clients that have specified an interest in that type of event.

This chapter describes the following concepts needed to manage events:

• Event processing---An overview of types of events
• Event type selection---A description of how clients can specify the types of events Xlib reports to them
• Event handling---A description of handling specific types of events

This chapter provides information for a subset of event types. For a complete reference of event handling routines and data structures, see the DECwindows Motif for OpenVMS Guide to Non-C Bindings and the X Window System.

9.1 Event Processing

Apart from errors, which Section 9.13 describes, Xlib events issue from operations on either windows or pixmaps. Most events result from operations associated with windows. The smallest window that contains the pointer when a window event occurs is the source window.

Xlib searches the window hierarchy upward from the source window until one of the following applies:

• Xlib finds a window that one or more clients have identified as interested in the event. This window is the event window. After Xlib locates an event window, it sends information about the event to appropriate clients.
• Xlib finds a window whose do_not_propagate attribute has been set by a client. Setting this attribute specifies that Xlib should not notify ancestors of the window owned by the client about events occurring in the window and its children. For more information about the do_not_propagate attribute, see Chapter 3.
• Xlib reaches the top of the window hierarchy without finding a window that a client has identified as interested in the event.

While there are many types of window events, events associated with pixmaps occur only when a client cannot compute a destination region because the source region is out-of-bounds (see Chapter 6 for a description of source and destination regions). When a client attempts an operation on an out-of-bounds pixmap region, Xlib puts the event on the event queue and checks a list to determine if a client is interested in the event. If a client is interested, Xlib sends information to the client using an event data structure.

Xlib can report 30 types of events related to keyboards, mice, windowing, and graphics operations. A flag identifies each type to facilitate referring to the event. Table 9-1 lists event types, grouped by category, and the flags that represent them.

Every event type has a corresponding data structure that Xlib uses to pass information to clients. See the sections that describe handling specific event types for a description of the relevant event-specific data structures.

Xlib includes the any event data structure, which clients can use to receive reports of any type of event. The following illustrates the any event data structure:

typedef struct {
        int type;
        unsigned long serial;
        Bool send_event;
        Display *display;
        Window window;
} XAnyEvent;

Table 9-2 describes members of the data structure.

To enable clients to manage multiple types of events easily, Xlib also includes an event data structure, which is composed of the union of individual event data structures.

The following illustrates the event data structure:

typedef union _XEvent {
        int type;
        XAnyEvent xany;
        XKeyEvent xkey;
        XButtonEvent xbutton;
        XMotionEvent xmotion;
        XCrossingEvent xcrossing;
        XFocusChangeEvent xfocus;
        XExposeEvent xexpose;
        XGraphicsExposeEvent xgraphicsexpose;
        XNoExposeEvent xnoexpose;
        XVisibilityEvent xvisibility;
        XCreateWindowEvent xcreatewindow;
        XDestroyWindowEvent xdestroywindow;
        XUnmapEvent xunmap;
        XMapEvent xmap;
        XMapRequestEvent xmaprequest;
        XReparentEvent xreparent;
        XConfigureEvent xconfigure;
        XGravityEvent xgravity;
        XResizeRequestEvent xresizerequest;
        XConfigureRequestEvent xconfigurerequest;
        XCirculateEvent xcirculate;
        XCirculateRequestEvent xcirculaterequest;
        XPropertyEvent xproperty;
        XSelectionClearEvent xselectionclear;
        XSelectionRequestEvent xselectionrequest;
        XSelectionEvent xselection;
        XColormapEvent xcolormap;
        XClientMessageEvent xclient;
        XMappingEvent xmapping;
        XErrorEvent xerror;
        XKeymapEvent xkeymap;
} XEvent;

The type member specifies the type of event being reported. For descriptions of the other members of the event data structure, see the section that describes the specific event type.

9.2 Selecting Event Types

Xlib sends information about an event only to clients that have specified an interest in that event type. Clients use one of the following methods to indicate interest in event types:

• By calling the SELECT INPUT routine. SELECT INPUT indicates to Xlib which events to report.
• By specifying event masks when creating a window.
• By specifying event masks when changing window attributes.
• By specifying the graphics exposure mask when creating the graphics context. For more information about specifying a graphics exposure mask, see Chapter 4.

Note that Xlib always reports client messages, mapping notifications, selection clearings, selection notifications, and selection requests.

See the description of the SELECT INPUT routine in the X Window System for restrictions on event reporting to multiple clients.

9.2.1 Using the SELECT INPUT Routine

Use the SELECT INPUT routine to specify the types of events Xlib reports to a client. Select event types by passing to Xlib one or more of the masks listed in Table 9-3.

The following illustrates using the SELECT INPUT routine:

               .
               .
               .
XSelectInput(dpy,win,StructureNotifyMask);
}

Clients specify the StructureNotifyMask mask to indicate an interest in one or more of the following window operations (see Table 9-3):

To specify event types when calling the CREATE WINDOW routine, use the method described in Section 3.2.2 for setting window attributes. Indicate the type of event Xlib reports to a client by doing the following:

1. Set the event_mask window attribute to one or more masks listed in Table 9-3.
2. Specify the event mask flag using the value_mask argument of the CREATE WINDOW routine.

Example 9-1 illustrates this method of selecting events. The program specifies that Xlib notify the client of exposure events.

Window window;
                  .
                  .
                  .
static void doCreateWindows( )
{
    int windowW = 400;
    int windowH = 300;
    int windowX = (WidthOfScreen(screen)-window1W)>>1;
    int windowY = (HeightOfScreen(screen)-window1H)>>1;
    XSetWindowAttributes xswa;

    /* Create the window1 window */

(1)   xswa.event_mask = ExposureMask;

(2)   window = XCreateWindow(dpy, RootWindowOfScreen(screen),
        windowX, windowY, windowW, windowH, 0,
        DefaultDepthOfScreen(screen), InputOutput,
        DefaultVisualOfScreen(screen), CWEventMask, &xswa);
}

1. Set the event mask of the set window attributes data structure to indicate interest in exposure events.
2. The window attribute is referred to by the constant CWEventMask, which specifies the attribute.

To specify one or more event types when changing window attributes, use the method described in Section 3.7 for changing window attributes. Indicate an interest in event types by doing the following:

1. Set the event_mask window attribute to one or more masks listed in Table 9-3.
2. Specify the event mask flag using the value_mask argument of the CHANGE WINDOW ATTRIBUTES routine.

The following illustrates this method:

                  .
                  .
                  .
    xswa.event_mask = StructureNotify;


    XChangeWindowAttributes(dpy, win, CWEventMask, &xswa);

Xlib reports pointer events to interested clients when the button on the pointing device is pressed or released or when the pointer moves.

This section describes how to handle the following pointer events:

• Pressing a button on the pointing device
• Releasing a button on the pointing device
• Moving the pointing device

The section also describes the button event and motion event data structures.

9.3.1 Handling Button Presses and Releases

To receive event notification of button presses and releases, pass the window identifier and either the ButtonPressMask mask or the ButtonReleaseMask mask when using the selection method described in Section 9.2.

When a button is pressed, Xlib searches for ancestors of the event window from the root window down to determine whether or not a client has specified a passive grab, an exclusive interest in the button. If Xlib finds no passive grab, it starts an active grab, reserving the button for the sole use of the client receiving notification of the event. Xlib also sets the time of the last pointer grab to the current server time. The effect is the same as calling the GRAB BUTTON routine with argument values listed in Table 9-4.

Refer to Chapter 11 for more information about using grabs.

Xlib uses the button event data structure to report button presses and releases. The following illustrates the data structure:

typedef struct {
        int type;
        unsigned long serial;
        Bool send_event;
        Display *display;
        Window window;
        Window root;
        Window subwindow;
        Time time;
        int x, y;
        int x_root, y_root;
        unsigned int state;
        unsigned int button;
        Bool same_screen;
} XButtonEvent;
typedef XButtonEvent XButtonPressedEvent;
typedef XButtonEvent XButtonReleasedEvent;

Table 9-5 describes members of the button event data structure. Note that Xlib defines the button pressed event and button released event data structures as a type button event.

Example 9-2 illustrates the button press event handling routine of the sample program described in Chapter 1. The program calls shutdown routines when the user clicks the mouse button in window2.

/***** Handle events *****/
static void doHandleEvents( )
{
    XEvent event;

    for ( ; ; ) {
        XNextEvent(dpy, &event);
        switch (event.type) {
            case Expose:                doExpose(&event); break;
            case ButtonPress:           doButtonPress(&event); break;
        }
    }
}
                    .
                    .
                    .
static void doButtonPress(eventP)
XEvent *eventP;
{
        if (eventP->xexpose.window != window2) {
        state =1;
        XDrawImageString(dpy, child, gc, 75, 75, message[state],
            strlen(message[state]));
        return;
    }

    /***** Unmap and destroy windows *****/

    XUnmapWindow(dpy, window1);
    XDestroyWindow(dpy, window1);

    XCloseDisplay(dpy);

    sys$exit (1);
}