Volume 7A: XView Programming Manual

Table 6-1. Event Structure Fields

Field Contents

ie_code Actual XView event ID, as defined in <xview/win_event.h> and

<xview/win_input.h>.* Event codes can take on any value in the

range 0 through 65535. The values are useful when debugging.

ie_flags Indicates whether the event was an up- or down-event, if appli-

cable. A down-event occurs when a mouse button or keyboard

key goes down. There must be a corresponding up-event,

although the client may choose to ignore up-events.

ie_shiftmask If a Shift key, Control key and/or mouse button was down when

the event occurred, this mask will have the appropriate bits set.

ie_locx, ie_locy x,y coordinates of the position of the locator (mouse) relative to

the window in which the event occurred.

ie_time The time of the event.

action Semantic code representing predefined actions specific to the win-

dow manager or OPEN LOOK.

ie_win

Window in which the event took place.

ie_string String in which a keycode (found in ie_code) is bound using

XRebindKeysym().

ie_xevent The actual event structure generated by X. This event structure

arrives untouched by XView for events generated by the server.

6.6 Determining the Event

In the Event structure, there is a pointer to the XEvent structure that was delivered by the

X server as a direct result of the event that it describes. This section discusses how to inter-

pret the event based on information in the Event structure only; it does not address the

XEvent structure.

The header files <xview/win_input.h> and <xview/win_event.h> contain many macros that

should be used rather than referencing fields in the Event data structure. If the structure is

modified in the future, then the macros will be modified to support the changes and your code

will not have to change. For example, to get the window in which the event took place, you

should not use the following (assume event is of type Event *):

window = event->ie_win;

Instead you should use:

window = event_window(event);

*<xview/panel.h> also has a few event definitions, but they are not widely used. See Chapter 7, Panels, for details.

Handling Input

Handling Input 125

To determine the actual event ID, you could use:

event_id(event)

This macro returns the actual event ID that took place, such as MS_LEFT to indicate the left

mouse button. However, as discussed earlier, we recommend that you use the semantic

action events provided by the macro:

event_action(event)

In the case where the user selected the left mouse button, event_action() would return

ACTION_SELECT. The two values do not map to the same thing; consider the case where left-

handed users have re-mapped the mouse settings. On the other hand, if there is no action

associated with an event, event_action() is set to event_id(). For example, con-

sider what happens when the letter a is pressed or when the Expose event is generated.

6.6.0.1 Event states

When a mouse button or keyboard event occurs, the event may be the result of a button or

key being released or pressed. The way to determine this state from a particular event is to

use one of these two macros:

event_is_up(event)

event_is_down(event)

6.6.0.2 Modifier keys

Modifier keys include the left and right Shift keys, the Control key, and the Meta key. The

locations of these keys on the user’s keyboard are dependent on the make and model of your

keyboard. The functions of modifier keys are to modify particular keyboard or mouse states.

For example, the Shift key, when modifying the a key, results in the A key.

Unless you have explicitly requested to be notified of modifier key events, you will not be

informed when their state changes (e.g., when a user presses or releases one of the keys).

You probably do not need to know this anyway. Instead, you only need to know the state of

the key at the time you are evaluating another event. In this case, you can use any of the fol-

lowing macros:

event_shift_is_down(event)

event_ctrl_is_down(event)

event_meta_is_down(event)

6.6.1 Keyboard Events

When XView translates keyboard events into Event codes, it does translation of the key

depending on the state of the modifier keys. For example, when the user types Shift-A,

intending to type an uppercase A, then the event ID (that is, event->ie_code) is A. You

do not need to use event_shift_is_down to translate the key to the uppercase.*

*This is in contrast to the value of XKeyEvent.keycode used by Xlib.

126 XView Programming Manual

The following macro is used to determine if a key event is within the ISO character set:

event_is_iso(event)

Event *event;

You can use the following macro to determine if an event is an ASCII key:*

event_is_ascii(event)

Event *event;

This result does not tell you if you have a printable character. Depending on the font you are

using, you may not be able to print anything with this event code. However, you can use any

of the macros in <ctype.h> to determine whether the character is printable, a control charac-

ter, a digit, a punctuation mark, and so on. Remember, this works because you are using the

already-translated version of the event code.

The macro event_string() can be used to determine the string value associated with the

event ID. This value is the result of a call to XLookupString(). The macro

event_string() only returns a value if the string returned from XLookupString() is

greater than one character long. Thus, for normal ASCII events, event_string() will be

NULL. Only if the application programmer has rebound the key (using XRe-

bindKeysym()) to a string greater than one character will event_string() report that

string:

Display *dpy = (Display *)xv_get(frame, XV_DISPLAY);

char *newstring = "Nine";

XRebindKeysym(dpy, XK_9, 0, 0, newstring, strlen(newstring));

Here, the 9 key is rebound to generate the string “Nine” whenever it is pressed. The follow-

ing macro determines whether or not a string is associated with the event:

event_is_string(event)

In the event callback, the following code could be used:

...

if (event_is_string(event))

printf("string = %s\n", event_string(event));

...

Function keys differ from keyboard to keyboard, and the default key mappings for your

server are configurable (at the time you build your server). However, XView has provisions

for keyboards that are sectioned off into four sets of fifteen function keys: left, top, right, and

*In Version 3, event_is_ascii(event), event_is_iso(event) and event_is_meta(event) use

the XView semantic action to determine whether the event is ASCII, ISO or META, respectively. If the event is a

modified ASCII or ISO key that maps to a semantic action (e.g., Meta-c mapping to ACTION_COPY), then the Ver-

sion 3 macros will return FALSE. In Version 2, the event code was used, which would result in Meta-c returning

TRUE regardless of the semantic action. Applications that want modified ASCII or ISO events (e.g., a terminal emu-

lator) should examine the event code directly by using event_id(event).

Handling Input

Handling Input 127

bottom keys. To determine which set of keys a particular event is associated with, you can

use the following macros:

event_is_key_left(event)

event_is_key_right(event)

event_is_key_top(event)

event_is_key_bottom(event)

To determine which function set a particular function key belongs to, use:

KEY_TOP(key)

KEY_LEFT(key)

KEY_RIGHT(key)

KEY_BOTTOM(key)

Here, you do not pass the event, you pass the event ID. Thus, to test to see if a particular

event were the fifth function key in the top row of keys, you would use:

if (event_is_key_top(event) && event_id(event) == KEY_TOP(5))

/* process the fifth top-function key. */

Notice that we are using event_id() rather than event_action(). The reason for this

is that some function keys are mapped to particular semantic actions, and we want to be sure

the user hits the fifth function key on the top row. Had we used event_action() instead,

the equality test may have failed.

Individual XView applications can define labels for the function keys. Refer to Section 6.12,

“Soft Function Keys and Virtual Keyboards,” for more information on labeling the function

keys.

6.6.1.1 Mouse events

XView supports a locator device (typically a mouse) with up to ten buttons on it. XView

also supports a mouseless locator, which operates through the keyboard and is described in

Section 6.13, “The Mouseless Model.” A mouse locator device may generate various types

of events, such as:

Motion events These events are generated whenever the mouse moves.

Drag events These events are generated when any of the mouse buttons are down and

the mouse moves.

Button events These events are generated whenever the state of a mouse button changes

(e.g., when a button goes up or down).

The following macros determine the state of particular buttons for a three-button mouse (the

most common type).

event_is_button(event)

event_left_is_down(event)

event_middle_is_down(event)

event_right_is_down(event)

event_button_is_down(event)

128 XView Programming Manual

Notice that none of these macros indicates an exclusive button state; that is, if

event_right_is_down returns TRUE, that does not exclude the left button from being

down, too.

You can determine which mouse button is changing state in the same way you determine a

function key position, by passing the ID of the event to:

BUT(i)

To determine whether the second mouse button was down, you could use:

if (event_is_down(event) && event_id(event) == BUT(2))

/* process button-2 event handling */

Again, we recommend that rather than determining the state of a particular mouse button,

you use the semantic codes:

if (event_is_down(event) && event_action(event) == ACTION_ADJUST)

/* process "adjust" event handling */

6.6.1.2 Keyboard focus

One way for the application to explicitly set keyboard focus to a particular window is to use

win_set_kbd_focus(). The calling parameters are the window and the XID of the win-

dow that is supposed to get the focus. For example, if a window gets a LOC_WINENTER event,

the keyboard focus can be obtained:

my_event_proc(window, event)

Xv_Window window;

Event *event;

{

switch (event_id(event)) {

...

case LOC_WINENTER:

win_set_kbd_focus(window, xv_get(window, XV_XID));

break;

...

}

}

The function win_set_kbd_focus() generates a

KBD_USE event for the window that is

getting the focus and a KBD_DONE event for the window that lost focus. Windows that need

to detect KBD_DONE and KBD_USE events must specify KBD_DONE/KBD_USE in their event

masks.

The attribute

WIN_SET_FOCUS

behaves in the same way as win_set_kbd_focus()

except that it checks to see if the window in question has KBD_USE/KBD_DONE selected. If it

does not, the focus is not set on the window. Example usage of WIN_SET_FOCUS (it does not

take any argument):

xv_set(window, WIN_SET_FOCUS, NULL);

Handling Input

Handling Input 129