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

Get Volume 7A: XView Programming Manual now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.