Volume 7A: XView Programming Manual

existing input mask for the window. This does not override what the window had previously;

the event mask specified is appended to the input mask for that window. To set an explicit

event mask, the value WIN_NO_EVENTS should be specified first in the list.

xv_set(window,

WIN_EVENT_PROC, sample_event_proc,

WIN_CONSUME_EVENTS,

WIN_NO_EVENTS, WIN_ASCII_EVENTS, WIN_MOUSE_BUTTONS, NULL,

NULL);

All events are cleared at the point in which WIN_NO_EVENTS is given in the list. If it is given

in the middle of the list, then the events specified previous to that point are forgotten. If it is

the only attribute in the list, then the event mask for the window is cleared. Note that this

does not mean that your event handler will receive no events. There are certain events that

are sent to your window, and thus to your event handler, whether you want them or not. This

is addressed later in this chapter.

You can specify which events to ignore in the same way:

xv_set(window,

WIN_IGNORE_EVENTS,

WIN_UP_ASCII_EVENTS, LOC_WINENTER, LOC_WINEXIT,

NULL,

NULL);

Here we are telling the window to ignore the events caused by releasing the ASCII keys on

the keyboard as well as window-enter and window-exit events. As with WIN_X_

EVENT_MASK

, you cannot use WIN_IGNORE_EVENTS to unregister all the events and expect

the event handler to be unregistered. It is perfectly legal to have a window that has no events

registered with it.

While these attributes take a

NULL-terminated list, you can use WIN_CONSUME_EVENT or

WIN_IGNORE_EVENT to consume or ignore one event. Using these attributes, it is not neces-

sary to specify a list of events.

6.3.2.1 Mouse events

The mouse (or locator) resides at an x,y coordinate position in pixels; this position is

transformed by XView to the coordinate space of the window receiving an event. You can

request mouse motion events by specifying LOC_MOVE or LOC_DRAG. A LOC_MOVE event is

reported when the mouse moves, regardless of the state of the locator buttons. If you only

want to know about locator motion when a button is down, then enable

LOC_DRAG instead of

LOC_MOVE

. This will greatly reduce the number of motion events that your application has to

process. If you have both specified, you will only receive one event or the other; you will

never receive one followed by the other.

Even if you do not request move or drag events, you may still monitor when the mouse

moves in and out of windows by specifying LOC_WINENTER and LOC_WINEXIT. In the case

of LOC_WINENTER, the window installs its colormap into the server, and, for LOC_WINEXIT,

the window’s colormap is uninstalled. If you have registered the colormap notify event

(WIN_COLORMAP_NOTIFY), then you will receive the appropriate events when you enter and

leave a window.

120 XView Programming Manual

Each button that is associated with the mouse is assigned an event code; the i-th button is

assigned the code BUT(i). Thus, the event codes MS_LEFT, MS_MIDDLE, and MS_RIGHT cor-

respond to BUT(1), BUT(2) and BUT(3). These are actual key codes, not semantic codes.

You can specify setting the buttons explicitly (as shown here) or as a group

(WIN_MOUSE_BUTTONS) or as semantic events using ACTION_SELECT, ACTION_ADJUST, and

ACTION_MENU.*

If you want your applications to work seamlessly with the mouseless model, you should spec-

ify semantic events. Refer to Section 6.13, The Mouseless Model, for details on using the

keyboard as a locator device.

6.3.2.2 Keyboard events

In order to be notified of keyboard events, you must specify any one of several XView event

types depending on which event you want. Unlike the X event mask KeyPressMask,

which generates events for all keys on the keyboard, including function keys, XView allows

you to be more specific about which keyboard events you are interested in while not having

to specify explicit keys.

The following list contains input event descriptors that may be used:

WIN_ASCII_EVENTS

Enable ASCII keycodes—these are events that fall between 0 and 127 in the ASCII

character set. Using this attribute specifies up-events as well as down-events.

WIN_UP_ASCII_EVENTS

This is used mostly by WIN_IGNORE_EVENTS to turn off receiving the release event

that usually follows a key press.

WIN_UP_EVENTS

This is a general facility for ignoring all release events from mouse buttons and key-

board keys.

The XView event types

KBD_USE and KBD_DONE can be specified to notify you when your

window obtains the keyboard focus. OPEN LOOK specifies the click-to-type method for key-

board focus, so you may not get keyboard focus just because the mouse entered a window.

The user can specify how keyboard focus should work without letting the application know

about it. When a window gets keyboard focus and the window’s event mask has KBD_USE

set, then the window’s event procedure is called.

*If you are writing applications and you use ACTION_SELECT, ACTION_ADJUST, and ACTION_MENU, users can

easily adjust for a left handed mouse with the command xmodmap.

Handling Input

Handling Input 121

6.3.2.3 Resize and repaint events

When the size of a window is changed or the window is moved, (either by the user or pro-

grammatically), a WIN_RESIZE event is generated to give the client a chance to adjust any

relevant internal state to the new window size. You should not repaint the window when

receiving a resize event. You will receive a separate WIN_REPAINT event when a portion of

the window needs to be repainted.

Top level frames and any other top level windows, when moved, may get multiple resize

events, from the server and from the window manager. ICCCM mandates that the window

manager send these events when the top level window is moved or resized. You can detect

this with the test:

event_xevent(event)->xconfigure.send_event

which returns

TRUE on events generated by the window manager. Note that all synthetic

events delivered will follow real events. For more information on the event actions man-

dated by ICCCM and of the coordinate space mapping, refer to Section L.4.1.5 of Inter-Client

Communications Manual in Volume 0, X Protocol Reference Manual.

If you are using a canvas subwindow, you will not need to track resize and repaint events

directly. The CANVAS package receives these events, computes the new window dimensions

or the precise area requiring repainting, and calls your resize or repaint procedures directly.

See Chapter 5, Canvases and Openwin, for more details.

NOTE

You will always get WIN_RESIZE events sent to your event handler routine.

Currently, you cannot prevent these events from being delivered to your event

handler.

As pointed out in Chapter 5, Canvases and Openwin, there may be a WIN_REPAINT event

generated for each region of a window that gets exposed. However, you can set whether or

not all those exposure events are collapsed into one expose event specifying a region that

covers the entire exposed area. The attribute WIN_COLLAPSE_EXPOSURES can be set to TRUE

(the default) or FALSE on the paint window to prevent multiple expose events.

You get graphics exposure events (WIN_GRAPHICS_EXPOSE) whenever you draw into a win-

dow using a GC whose graphics_exposures field is set to True. The same is true for

WIN_NO_EVENTS. These events are not selected via WIN_CONSUME_EVENTS and cannot be

ignored using this method. The only way to avoid receiving these events is by setting the

graphics_exposures field in the GC to False. Choose the best way to deal with it for

your application.

122 XView Programming Manual

6.3.2.4 Client messages

Client messages are events that cannot be ignored by your event handler. Typically, these are

messages that are used to implement a predefined protocol between your application and

other applications that are familiar with the protocol. Because client messages cannot be

ignored, we do not address the issue of client messages in this section. Read Section 6.7,

“Interpreting Client Messages,” for more information on how to interpret these events.

6.3.2.5 Miscellaneous events

Consuming any one of the following events causes all of them to be consumed, as specified

by the X Protocol:

• WIN_CIRCULATE_NOTIFY

• WIN_DESTROY_NOTIFY

• WIN_GRAVITY_NOTIFY

• WIN_MAP_NOTIFY

• WIN_REPARENT_NOTIFY

• WIN_RESIZE

• WIN_UNMAP_NOTIFY

Alternatively, you could just select WIN_STRUCTURE_NOTIFY, which selects all of the above

events.

If you select WIN_CREATE_NOTIFY on a parent object, you will receive this event whenever a

child window of the parent object is created. You will also receive any of the above listed

events on the subwindows whenever WIN_CREATE_NOTIFY, or, alternatively, WIN_SUB-

STRUCTURE_NOTIFY

, is consumed on the parent.

Consuming any one of the following events causes all of them to be consumed, as specified

in the X Protocol:

• WIN_CIRCULATE_REQUEST

• WIN_CONFIGURE_REQUEST

• WIN_MAP_REQUEST

Alternatively, you could just select

WIN_SUBSTRUCTURE_REDIRECT, which selects all of the

above events. A window manager is really the only client that should ever be interested in

any of these.

Handling Input

Handling Input 123

6.4 The Event Handler

When one of the events in which you have expressed interest occurs, your event handler is

called. The form of this routine is:

void

sample_event_proc(window, event, arg)

Xv_Window window;

Event *event;

Notify_arg arg;

The arguments to the routine are the window the event occurred in, a pointer to a data struc-

ture describing information about the event itself, and an optional argument supplied by the

XView package responsible for the function being called.*

The attribute WIN_EVENT_PROC allows you to specify an event procedure for an application’s

window. Events are dispatched so event procedures that you register are the last in line to

receive events. First, events are sent to the base event handler for the package, and then to

the event handler you specify by setting WIN_EVENT_PROC or other callbacks for the individ-

ual packages. XView has a two-tiered scheme in which the packages —panels, canvases,

scrollbars, etc.—interact with the Notifier directly, registering their own callbacks. Your

application, in turn, registers its own callback procedures with the package. You can also

interpose an event handling routine so that your application can intercept events before they

reach the base event handler. See Chapter 20, The Notifier, for a description of interposition.

6.5 The Event Structure

Events that are generated are passed to event handling procedures by the Notifier as Event

pointers (type Event *). This structure is declared in <xview/win_input.h>:

typedef struct inputevent {

short ie_code; /* input code */

short ie_flags;

short ie_shiftmask; /* input code shift state */

short ie_locx, ie_locy; /* mouse position */

struct timeval ie_time; /* time of event */

short action; /* keymapped ie_code */

Xv_object ie_win; /* window receiving event */

char *ie_string; /* keycode binding string */

XEvent *ie_xevent; /* actual XEvent struct */

} Event;

The Event data structure contains all the information about the event. The fields are broken

down as shown in Table 6-1.

*This parameter is currently unused. It is available for new XView packages, extensions to them or for advanced No-

tifier usage. See Section 20.6.2, “Posting with an Argument,” in Chapter 20, The Notifier.

124 XView Programming Manual