HP OpenVMS Systems Documentation

VMS DECwindows Guide to Xlib (Release 4) Programming: VAX Binding

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.

**Table 9-3 Event Masks**
Event Mask	Event Reported (Event Type)
x$m_button_motion	At least one button on the pointing device is pressed while the pointer moves (x$c_motion_notify).
x$m_button1_motion	Pointing device button 1 is pressed while the pointer moves (x$c_motion_notify).
x$m_button2_motion	Pointing device button 2 is pressed while the pointer moves (x$c_motion_notify).
x$m_button3_motion	Pointing device button 3 is pressed while the pointer moves (x$c_motion_notify).
x$m_button4_motion	Pointing device button 4 is pressed while the pointer moves (x$c_motion_notify).
x$m_button5_motion	Pointing device button 5 is pressed while the pointer moves (x$c_button_press).
x$m_button_press	Any pointing device button is pressed (x$c_button_press).
x$m_button_release	Any pointing device button is released (x$c_button_release).
x$m_colormap_change	A client installs, changes, or removes a color map (x$c_colormap_notify).
x$m_enter_window	The pointer enters a window (x$c_enter_notify).
x$m_exposure	A window becomes visible, a graphics region cannot be computed, a graphics request exposes a region or all source available, and a no expose generated (x$c_expose, x$c_graphics_expose, x$c_graphics_noexpose).
x$m_leave_window	The pointer leaves a window (x$c_leave_notify).
x$m_focus_change	The keyboard focus changes (x$c_focus_in, x$c_focus_out).
x$m_keymap_state	The key map changes (x$c_keymap_notify).
x$m_key_press	A key is pressed or released (x$c_key_press, x$c_key_release).
x$m_owner_grab_button	Not applicable.
x$m_pointer_motion	The pointer moves (x$c_motion_notify).
x$m_pointer_motion_hint	Xlib is free to report only one pointer-motion event (x$c_motion_notify) until one of the following occurs: Either the key or button state changes. The pointer leaves the window. The client calls QUERY POINTER or GET MOTION EVENTS.
x$m_property_change	A client changes a property (x$c_property_notify).
x$m_structure_notify	One of the following operations occurs on a window: Circulate (x$c_circulate_notify) Configure (x$c_configure_notify) Destroy (x$c_destroy_notify) Move (x$c_gravity_notify) Map (x$c_map_notify) Reparent (x$c_reparent_notify) Unmap (x$c_unmap_notify)
x$m_substructure_notify	One of the following operations occurs on the child of a window: Circulate (x$c_circulate_notify) Configure (x$c_configure_notify) Create (x$c_create_notify) Destroy (x$c_destroy_notify) Move (x$c_gravity_notify) Map (x$c_map_notify) Reparent (x$c_reparent_notify) Unmap (x$c_unmap_notify)
x$m_visibility_change	The visibility of a window changes (x$c_visibility_notify).

The following illustrates using the SELECT INPUT routine:

                         .
                         .
                         .
        CALL X$SELECT_INPUT(DPY, WINDOW, X$M_STRUCTURE_NOTIFY)

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

Circulating	Configuring
Destroying	Reparenting
Changing gravity	Mapping and unmapping
Moving

9.2.2 Specifying Event Types When Creating a Window

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:

Set the X$L_SWDA_EVENT_MASK window attribute to one or more masks listed in Table 9-3.
Specify the event mask flag in 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.

Example 9-1 Selecting Event Types Using the CREATE WINDOW Routine

       INTEGER*4 WINDOW_1
                         .
                         .
                         .
       PARAMETER WINDOW_W = 400, WINDOW_H = 300

C
C       Create the WINDOW_1 window
C
        WINDOW_1X = (X$WIDTH_OF_SCREEN(SCREEN) - WINDOW_1W) / 2
        WINDOW_1Y = (X$HEIGHT_OF_SCREEN(SCREEN) - WINDOW_1H) / 2

        DEPTH = X$DEFAULT_DEPTH_OF_SCREEN(SCREEN)
        CALL X$DEFAULT_VISUAL_OF_SCREEN(SCREEN,VISUAL)
        ATTR_MASK = X$M_CW_EVENT_MASK .OR. X$M_CW_BACK_PIXEL

(1)      XSWDA.X$L_SWDA_EVENT_MASK = X$M_EXPOSURE .OR. X$M_BUTTON_PRESS
        XSWDA.X$L_SWDA_BACKGROUND_PIXEL =
        1   DEFINE_COLOR(DPY, SCREEN, VISUAL, 1)

(2)      WINDOW_1 = X$CREATE_WINDOW(DPY,
        1   X$ROOT_WINDOW_OF_SCREEN(SCREEN),
        1   WINDOW_1X, WINDOW_1Y, WINDOW_1W, WINDOW_1H, 0,
        1   DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA)

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

9.2.3 Specifying Event Types When Changing Window Attributes

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

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

The following illustrates this method:

                         .
                         .
                         .
        ATTR_MASK = X$M_STRUCTURE_NOTIFY

        CALL X$CHANGE_WINDOW_ATTRIBUTES(DPY, WINDOW, ATTR_MASK, XSWA)

9.3 Pointer Events

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 x$m_button_press or the x$m_button_release 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.

**Table 9-4 Values Used for Grabbing Buttons**
Argument	Value
window_id	Event window.
event_mask	Client pointer motion mask.
pointer_mode	The value specified by the constant x$c_grab_mode_async.
keyboard_mode	The value specified by the constant x$c_grab_mode_async.
owner_events	True, if the owner has specified x$m_owner_grab_button. Otherwise, false.
confine_to	None.
cursor	None.

Xlib terminates the grab automatically when the button is released. Clients can modify the active grab by calling the UNGRAB POINTER and CHANGE ACTIVE POINTER GRAB routines.

Xlib uses the button event data structure to report button presses and releases. Figure 9-3 illustrates the data structure.

Figure 9-3 Button Event Data Structure

Table 9-6 describes members of the data structure.

Table 9-6 Motion Event Data Structure Members

Member Name

Contents

X$L_MTEV_TYPE

Type of event reported. The member can have only the value specified by the constant x$c_motion_notify.

X$L_MTEV_SERIAL

Number of the last request processed by the server.

X$L_MTEV_SEND_EVENT

Value defined by the constant true if the event came from a SEND EVENT request.

X$A_MTEV_DISPLAY

Display on which the event occurred.

X$L_MTEV_WINDOW

Event window.

X$L_MTEV_ROOT

Root window in which the event occurred.

X$L_MTEV_SUBWINDOW

Source window in which the event occurred.

X$L_MTEV_TIME

Time in milliseconds at which the event occurred.

X$L_MTEV_X

The x value of the pointer coordinates in the source window.

X$L_MTEV_Y

The y value of the pointer coordinates in the source window.

X$L_MTEV_X_ROOT

The x value of the pointer coordinates relative to the root window.

X$L_MTEV_Y_ROOT

The y value of the pointer coordinates relative to the root window.

X$L_MTEV_STATE

State of the button just prior to the event. Xlib can set this member to the bitwise OR of one or more of the following masks:

x$m_button1	x$m_button2
x$m_button3	x$m_button4
x$m_button5	x$m_mod1
x$m_mod2	x$m_mod3
x$m_mod4	x$m_mod5

X$B_MTEV_IS_HINT

Indicates that motion hints are active. No other events reported until pointer moves out of window.

X$L_MTEV_SAME_SCREEN

Indicates whether or not the event window is on the same screen as the root window.

Example 9-3 illustrates pointer motion event handling.

Example 9-3 Handling Pointer Motion

                         .
                         .
                         .
            IF (EVENT.EVNT_TYPE .EQ. X$C_MOTION_NOTIFY) THEN

            X = EVENT.EVNT_MOTION.X$L_MTEV_X
            Y = EVENT.EVNT_MOTION.X$L_MTEV_Y

            CALL X$FILL_RECTANGLE(DPY, WINDOW, GC, X, Y, WIDTH, LENGTH)
            ENDIF
                         .
                         .
                         .

Each time the pointer moves, the program draws a filled rectangle at the resulting x and y coordinates.

To receive pointer motion events, the client specifies the x$c_motion_notify flag when removing events from the queue. The client indicated an interest in pointer motion events when creating window WINDOW, as follows:

        XSWDA.X$L_SWDA_EVENT_MASK = X$M_EXPOSURE
        1       .OR. X$M_BUTTON_PRESS
        1       .OR. X$M_POINTER_MOTION
        XSWDA.X$L_SWDA_BACKGROUND_PIXEL =
        1   DEFINE_COLOR(DPY, SCREEN, VISUAL, 1)

        WINDOW = X$CREATE_WINDOW(DPY,
        1   X$ROOT_WINDOW_OF_SCREEN(SCREEN),
        1   WINDOW_X, WINDOW_Y, WINDOW_W, WINDOW_H, 0,
        1   DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA)

The server reports pointer movement. Xlib records the resulting position of the pointer in a motion data structure, one of the event structures that constitute the event structure. The client determines the origin of the filled rectangle it draws by referring to the motion event data structure x and y members.

9.4 Window Entries and Exits

Xlib reports window entries and exits to interested clients when one of the following occurs:

The pointer moves into or out of a window due to either pointer movement or to a change in window hierarchy. This is normal window entry and exit.
A client calls WARP POINTER, which moves the pointer to any specified point on the screen.
A client calls CHANGE ACTIVE POINTER GRAB, GRAB KEYBOARD, GRAB POINTER, or UNGRAB POINTER. This is pseudomotion, which simulates window entry or exit without actual pointer movement.

To receive event notification of window entries and exits, pass the window identifier and either the x$m_enter_window mask or the x$m_leave_window mask when using the selection method described in Section 9.2.

Xlib uses the crossing event data structure to report window entries and exits. Figure 9-5 illustrates the data structure.

Figure 9-5 Crossing Event Data Structure

Table 9-8 describes members of the data structure.

**Table 9-8 Expose Event Data Structure Members**
Member Name	Contents
X$L_EXEV_TYPE	Value defined by the x$c_expose constant.
X$L_EXEV_SERIAL	Number of the last request processed by the server.
X$L_EXEV_SEND_EVENT	Value defined by the constant true if the event came from a SEND EVENT request.
X$A_EXEV_DISPLAY	Display on which the event occurred.
X$L_EXEV_WINDOW	Event window.
X$L_EXEV_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.
X$L_EXEV_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.
X$L_EXEV_WIDTH	Width of the exposed region.
X$L_EXEV_HEIGHT	Height of the exposed region.
X$L_EXEV_COUNT	Number of exposure events that are to follow. If Xlib sets the count to zero, no more exposure events follow for this window. Clients that do not optimize redisplay by distinguishing between subareas of its windows can ignore all exposure events with nonzero counts and perform full redisplays on events with zero counts.

The following fragment from the sample program in Chapter 1 illustrates window exposure event handling:

                    .
                    .
                    .
            IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE .AND.
        1       EVENT.EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. WINDOW_2) THEN
                CALL X$CLEAR_WINDOW(DPY, WINDOW_2)
                CALL X$DRAW_IMAGE_STRING(DPY, WINDOW_2, GC,
        1           75, 75, 'Click here to exit')
            END IF
                    .
                    .
                    .

The program checks exposure events to verify that the server has mapped the second window. After the window is mapped, the program writes text into it.

9.6.2 Handling Graphics Exposures

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 X$L_GCVL_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. Figure 9-8 illustrates the data structure.

Figure 9-8 Graphics Expose Event Data Structure

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

**Table 9-10 No Expose Event Data Structure Members**
Member Name	Contents
X$L_NEEV_TYPE	Value defined by the constant x$c_no_expose.
X$L_NEEV_SERIAL	Number of the last request processed by the server.
X$L_NEEV_SEND_EVENT	Value defined by the constant true if the event came from a SEND EVENT request.
X$A_NEEV_DISPLAY	Display on which the event occurred.
X$L_NEEV_DRAWABLE	Window or pixmap reporting the event.
X$L_NEEV_MAJOR_CODE	Indicates whether the graphics request was a copy area or a copy plane.
X$L_NEEV_MINOR_CODE	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-10 shows the resulting output of the program.

Example 9-5 Handling Graphics Exposures

        INTEGER*4 X, Y
        INTEGER*4 PX, PY
        INTEGER*4 WIDTH, HEIGHT
        INTEGER*4 BUTTON_IS_DOWN
        INTEGER*4 VY
                    .
                    .
                    .
C
C       Handle events
C
        DO WHILE (.TRUE.)

            CALL X$NEXT_EVENT(DPY, EVENT)
            IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE) THEN
                CALL X$DRAW_IMAGE_STRING(DPY, WINDOW, GC,
        1           150, 25, 'To scroll, press MB1.')
                CALL X$DRAW_IMAGE_STRING(DPY, WINDOW, GC,
        1           150, 75, 'To exit, click MB2.')
            END IF
            IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND.
        1       EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN
                BUTTON_IS_DOWN = 1
                CALL START_SCROLL(DPY, WINDOW, GC, SCROLL_PIXELS,
        1           WINDOW_W, WINDOW_H, VY)
            END IF
            IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND.
        1       EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON2) THEN
                CALL SYS$EXIT(%VAL(1))
            END IF
            IF (EVENT.EVNT_TYPE .EQ. X$C_GRAPHICS_EXPOSE) THEN
(1)              X = EVENT.EVNT_GRAPHICS_EXPOSE.X$L_GEEV_X
                Y = EVENT.EVNT_GRAPHICS_EXPOSE.X$L_GEEV_Y
                WIDTH = EVENT.EVNT_GRAPHICS_EXPOSE.X$L_GEEV_WIDTH
                HEIGHT = EVENT.EVNT_GRAPHICS_EXPOSE.X$L_GEEV_HEIGHT
                DO PY = Y, Y + HEIGHT-1
                    DO PX = X, X + WIDTH-1
                        IF (MOD(PX + PY + VY, 10) .EQ. 0) THEN
                            CALL X$DRAW_POINT (DPY, WINDOW, GC, PX, PY)
                        END IF
                    END DO
                END DO
                IF (BUTTON_IS_DOWN .NE. 0) THEN
                CALL START_SCROLL(DPY, WINDOW, GC, SCROLL_PIXELS,
        1           WINDOW_W, WINDOW_H, VY)
                END IF
            END IF
            IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_RELEASE) THEN
                BUTTON_IS_DOWN = 0
            END IF

            IF (EVENT.EVNT_TYPE .EQ. X$C_NO_EXPOSE) THEN
                IF (BUTTON_IS_DOWN .NE. 0) THEN
                    CALL START_SCROLL(DPY, WINDOW, GC, SCROLL_PIXELS,
        1               WINDOW_W, WINDOW_H, VY)
                END IF
            END IF
        END DO
                    .
                    .
                    .
C
C
C       START SCROLL SUBPROGRAM
C
(2)      SUBROUTINE START_SCROLL(DISP, WIN, GCONTEXT, SCR_PIX, WIN_W,
        1       WIN_H, VEC_Y)

        INTEGER*4 DISP, WIN, GCONTEXT, SCR_PIX
        INTEGER*4 WIN_W, WIN_H, VEC_Y

(3)      CALL X$COPY_AREA(DISP, WIN, WIN, GCONTEXT, 0,
        1    SCR_PIX, WIN_W, WIN_H, 0, 0)
        VEC_Y = SCR_PIX + VEC_Y

        END

Contents

Index