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

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:

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:

  1. Set the X$L_SWDA_EVENT_MASK window attribute to one or more masks listed in Table 9-3.
  2. 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)

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

  1. Set the X$L_SWDA_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: 


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

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:

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:

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

Previous Next Contents Index