As we've already seen, the three possible directives are #replace, #override, or #augment.

#replace says to completely replace the value of the translations resource in the widget. If no directive is specified, #replace is the default.

The difference between #override and #augment is more subtle. They differ in how they treat event combinations in the new translation that also appear in the old. With #override, the new translation takes priority, while with #augment, the old one does.

For example, say a widget has a default translation table that includes a translation for the Return key, and an application that uses this widget has an app-defaults file consisting of a translation table that applies to this widget. If the translation table in the app-defaults file began with #override, any translation for the Return key would take priority over the default translation for the Return key. On the other hand, if the translation table in the app-defaults file began with #augment, the default translations would take priority.

Remember that the difference between #augment and #override is only in the treatment of overlapping translations. Any translations added with either directive for events that do not already appear in the existing translation table will always be added.

Because of potential overlap between translations, when you are debugging your intended translations it is best to use #replace at first, then test with #augment or #override as appropriate once you are sure that the translations themselves have the desired effect.

An X event is a packet of data sent by the server to a client in response to user behavior or to window system changes resulting from interactions between windows. There are 33 different types of events defined by X. Most (though not all^[54]) events can be thought of as occurring in a window: the pointer entering or leaving a window, pointer motion within a window, pointer button presses, key presses, and so on. However, most events are not sent to a window unless the window has explicitly selected that event type; events are selected on a per-window basis. In Xlib programming, events are selected by specifying an event mask as a window attribute. Some events, which are sent to all windows regardless of whether a window has selected them or not, are called non-maskable events. One of the most complex aspects of Xlib programming is designing the event loop, which must take into account all of the possible events that can occur in a window.

Xt's translation manager selects the events that are specified in the current translation table for each widget. In translations, events can be specified either by their actual names, as shown in Column 1 of Table 8-1, or by means of the abbreviations shown in Column 2. A complete reference to each event type is provided in Appendix C, Event Reference, in Volume Five, X Toolkit Intrinsics Reference Manual.

Many of these events are handled automatically by the Toolkit separately from the translation mechanism. For example, Expose events are automatically sent to the expose method of the appropriate widget. When there is also a translation for Expose events, the action is called in addition to the expose method. The only reason you would need a translation for Expose events is to add drawing to a Core widget. Because the Core widget doesn't have an expose method, there is rarely, if ever, a case where there is both an expose method and a translation for Expose events for the same widget. The point to remember is that any event can be specified in a translation, even when that event is also used in some other way by Xt.

GraphicsExpose and NoExpose events are useful when your application copies from a visible window with XCopyArea() or XCopyPlane(). They notify the application when part of the source of the copy is obscured. If you want GraphicsExpose and NoExpose events, you must explicitly select them by setting the graphics_exposures GC component in the GC used for the copy. Then you can provide a translation for them, or if you are writing a widget you can have them sent to your expose method by setting the compress_exposure field of the Core structure to a special value, as described in Section 9.7.2, "Event Filters." (While xbitmap and BitmapEdit use XCopyArea() and XCopyPlane(), they copy from an off-screen pixmap that cannot be obscured, and therefore GraphicsExpose and NoExpose events are not needed. For a description of these events, see Chapter 5, The Graphics Context, in Volume One, Xlib Programming Manual.)

Several of the *Notify events are automatically handled by the Toolkit. Xt places this information in internal structures so that it can satisfy queries for widget positions and geometries without querying the server. MappingNotify events are automatically handled; Xt gets the current keyboard mapping from the server. VisibilityNotify events are handled automatically if the visible_interest field in the Core structure is set to True (see Section 9.5, "Visibility Interest").

With the exception of SelectionRequest, the *Request events are intended for use only by window managers. The selection events are described in Chapter 11, Interclient Communications.

The keyboard traversal code built into the Motif Primitive class handles EnterNotify, LeaveNotify, FocusIn, and FocusOut events.

Whether or not they are already handled by Xt or in translations, events can also be selected explicitly by installing event handlers in a widget (as described in Chapter 9, More Input Techniques).

As you've seen, Xt provides special event abbreviations to specify which pointer button was pressed or released. With key events, this approach would be a little impractical, since there are so many keys. Instead, the Translation Manager allows you to follow the event specification with an optional detail field. That is:

<Key>:  doit()

means that you want the doit() action to be invoked when any key has been pressed, while:

<Key>y:  doit()

means that you want the doit() action to be invoked only if the y key has been pressed.

What you actually specify as the detail field of a Key event is a keysym, as defined in the header file <X11/keysymdef.h>.^[55] Keysyms begin with an XK_ prefix, which is omitted when they are used in translations.

Before we explain any further, we need to review X's keyboard model, which, like many things in X, is complicated by the design goal of allowing applications to run equally well on machines with very different hardware.

The keyboard generates KeyPress events, and may or may not also generate KeyRelease events. These events contain a server-dependent code that describes the key pressed, called a keycode. Modifier keys, such as Shift and Control, generate events just like every other key. In addition, all key events also contain information about which modifier keys and pointer buttons were held down at the time the event occurred.

Xt provides a routine that translates keycode and modifier key information from an event into a portable symbolic constant called a keysym. A keysym represents the meaning of the key pressed, which is usually the symbol that appears on the cap of the key. For example, when the a key is pressed, the keysym is XK_a; when the same key is pressed while the Shift key is held down, the resulting keysym is XK_A (uppercase). Note that even though both the a and the A events have the same keycode, they generate a different keysym because they occurred with different modifier keys engaged. (The mapping between keycodes and keysyms is discussed further in Section 14.5, "Keyboard Interpretation.")

You may specify either the keysym name, omitting the XK_ prefix, or its hexadecimal value (also shown in <X11/keysymdef.h>), prefixed by 0x or 0X (zero followed by x or X).

This is fairly straightforward, though there are several provisos:

In sum, the following are all valid key event translations:

<Key>q:  quit()	              invoke quit() when q or Q is pressed
:<Key>?:  help()	             invoke help() when ? (but not /) is pressed
<Key>Return:  newline()       invoke newline() when the Return key is pressed
<Key>:  insert_char()	        invoke insert_char() when any key is pressed

Key events are the most likely to require details, but details are also available for several other event types. They simplify your action function because they instruct Xt to call the action only when the event contains the matching detail. One type of detail, for MotionNotify, actually affects the selection of events.

Trivially, the detail values Button1 through Button5 can be supplied as details for ButtonPress or ButtonRelease events; because of the available abbreviations, though, these button detail values should not often be necessary. It is easier to say:

<Btn1Down>: quit()

than:

<BtnDown>Button1:  quit()

The EnterNotify, LeaveNotify, FocusIn, and FocusOut events can take as details any of the notify mode values shown in Table 8-2.

Normally, EnterNotify and LeaveNotify events are generated when the pointer enters or leaves a window, and FocusIn and FocusOut events are generated when a click-to-type window manager changes the keyboard focus window--the window that receives all keyboard input regardless of pointer position. In these cases the detail is Normal. But these events are also generated when the keyboard or pointer is grabbed by an application with a call to XtGrabPointer(), XtGrabButton(), XtGrabKeyboard(), or XtGrabKey(). A grab, which is usually invoked by a popup window, also causes keyboard and/or pointer input to be constrained to a particular window. When these events are generated because of a grab or the release of a grab, the detail is Grab or Ungrab.

Details for additional events were added in Release 4. For MotionNotify events you can now select normal motion events or motion hints by specifying a detail of Normal or Hint. Normal motion events are used when you need a complete record of the path of the pointer. The compress_motion Core field, described in Chapter 9, is for use with normal motion events. Motion hints are used when you need only periodic pointer position updates. Each time you receive a motion hint you call XQueryPointer() (an Xlib call) to get the current pointer position. Note that the MotionNotify detail is the only one that affects event selection.

For PropertyNotify, SelectionClear, SelectionRequest, SelectionNotify, and ClientMessage events, the detail is an atom described in Table 8-3.

For MappingNotify, the detail can be Modifier, Keyboard, or Pointer. Xt automatically does what is normally required to handle keyboard (and modifier) mapping changes. However, the Pointer detail might be used to make sure that the user has not disabled (by mismapping) any pointer button that is necessary for the safe operation of the application. You would simply write a translations such as <Mapping> Pointer: ButtonMapCheck and then call XGetPointerMapping() in the ButtonMapCheck action to make sure the pointer mapping is still acceptable.

The detail values for each event type corresponds to certain members of the associated event structure, as shown in Table 8-4. See Appendix C, Event Reference, in Volume Five, X Toolkit Intrinsics Reference Manual, for more details.

Certain events include as part of their data the state of the pointer buttons and special keyboard modifier keys at the time the event was generated. The events for which this state is available include ButtonPress, ButtonRelease, MotionNotify, KeyPress, KeyRelease, EnterNotify, and LeaveNotify.

For these events, you can specify a desired modifier state using one or more of the modifier keywords listed in Table 8-5. An error is generated if you specify modifiers with any other types of events.

/* Modifiers */
#define XK_Shift_L              0xFFE1  /* Left shift */
#define XK_Shift_R              0xFFE2  /* Right shift */
#define XK_Control_L            0xFFE3  /* Left control */
#define XK_Control_R            0xFFE4  /* Right control */
#define XK_Caps_Lock            0xFFE5  /* Caps lock */
#define XK_Shift_Lock           0xFFE6  /* Shift lock */
#define XK_Meta_L               0xFFE7  /* Left meta */
#define XK_Meta_R               0xFFE8  /* Right meta */
#define XK_Alt_L                0xFFE9  /* Left alt */
#define XK_Alt_R                0xFFEA  /* Right alt */
#define XK_Super_L              0xFFEB  /* Left super */
#define XK_Super_R              0xFFEC  /* Right super */
#define XK_Hyper_L              0xFFED  /* Left hyper */
#define XK_Hyper_R              0xFFEE  /* Right hyper */

isla% xmodmap
xmodmap:  up to 2 keys per modifier, (keycodes in parentheses):
shift       Shift_L (0x6a),  Shift_R (0x75)
lock        Caps_Lock (0x7e)
control     Control_L (0x53)
mod1        Meta_L (0x7f),  Meta_R (0x81)
mod2
mod3
mod4
mod5

isla% xmodmap -e 'add mod2 = F1'

<Key>q:    quit()

Shift<Key>q:    quit()

Button1<Key>:  doit()

~Button1<Key>:  doit()

~Shift Ctrl<Key>:  doit()

!Shift<Key>q:  quit()

None<Key>q:  quit()

!<Key>q:  quit()

<Key>a:  doit()

<Key>A:  doit()

:<Key>a:  append()  \n\
:<Key>A:  appendToEndOfLine()

~Shift<Key>a:  append()  \n\
Shift<Key>a:  appendToEndOfLine()

~Shift ~Lock<Key>a:  append()  \n\
Shift<Key>a:  appendToEndOfLine()

Shift<Key>A:  doit()

The left-hand side of a translation may specify a single event or a sequence of events that must occur for the action to be invoked. For example, we might want a certain action to be invoked only if the first button is clicked twice in succession.

Each event specified in the sequence is one of the abbreviations for an event type enclosed in angle brackets, optionally led by any set of modifiers and special characters, as described in Section 8.1.5, "Modifiers." Each modifier-list/event pair in the sequence is separated by a comma.

For example, the translation to perform an action in response to a button press followed by a release of the same button (a button click) is the following:

<BtnDown>,<BtnUp> : doit()

Button press events may be specified in the translation table followed by a count in parentheses to distinguish a multiple click. The translation to detect a double click is:

<Btn1Down>(2) : doit()

or:

<Btn1Up>(2) : doit()

Notice that though they have the same effect for the user, these two translations are actually interpreted differently. The first is equivalent to saying:

<Btn1Down>,<Btn1Up>,<Btn1Down>:  doit()

while the second is equivalent to:

<Btn1Down>,<Btn1Up>,<Btn1Down>,<Btn1Up>:  doit()

A plus (+) may appear immediately after the count inside the parentheses to indicate that any number of clicks greater than the specified count should trigger the action.

The following translation detects two or more clicks:

<Btn1Down>(2+) : doit()

The maximum count that can be specified is 9.

Xt uses a timing technique to detect whether two or more clicks should be considered a multi-click or separate single clicks. The time is controlled by the XmNmultiClickTime application resource, which defaults to 200 milliseconds. If 200 milliseconds or more of idle time passes between clicks, Xt does not consider that a match. You can set this resource to different values for each display using XtSetMultiClickTime().

For key events, you need to be careful when you want to make a particular key sequence invoke one action, and a subset of that key sequence to invoke another. For example, consider the following translation:

 <Key>a,<Key>b : something()
 <Key>         : else()

One might expect <Key>b events not preceded by <Key>a events to invoke the else() action. But instead, such <Key>b events are discarded. To get what you expected, use:

 <Key>a,<Key>b : something()
 <Key>b        : else()
 <Key>         : else()

<Btn1Down>:  handleClicks()
Button1<Motion>: handleMotif()

<Motion>:  doit()

Shift<BtnDown>,<BtnUp>:  doit()

Shift<BtnDown>,Shift<BtnUp>:  doit()

Ctrl<Btn2Down>,~Ctrl<Btn2Up>: doit()

Button1<Key>F1:     doit()

<Btn1Down>,<Key>F1:  doit()

!Button1<Button2>:    doC() \n\
!Button2<Button1>:    doC()

"yes":  doit()

<Key>y,<Key>e,<Key>s:  doit()

One of the most difficult things to learn about translations is how to predict the interactions between overlapping translations.

<Key>Return:  gotData()    \n\
<Key>:        insertChar()

<Key>:        insertChar()  \n\
<Key>Return:  gotData()

<Btn1Down>,<Btn1Up>:    actionB() \n\
<Btn1Down>:             actionA()

<Btn1Up>(2):  quit()  \n\
<Btn1Down>,<Btn1Up>:  confirm()

<Btn1Down>,<Btn1Up>:    actionB() \n\
<Btn1Up>:               actionA()

Every widget has an XtNaccelerators resource, inherited from the Core widget class. This resource contains an accelerator table, which is identical in format to a translation table; it maps event sequences to action sequences. Accelerator tables can be set into the XtNaccelerators resource in all the same ways translation tables can. The widget on which the XtNaccelerators resource is set is the widget whose actions are to be invoked from events in other widgets.

Once the XtNaccelerators resource of a widget is set, the application must call XtInstallAccelerators() or XtInstallAllAccelerators() to specify which widget will be the source of the events to invoke the actions specified in the accelerator table.

The MIT Intrinsics documentation refers to these two widgets as the source and destination. This can be confusing, especially since the arguments are referenced in reverse order in the call to XtInstallAccelerators():

void XtInstallAccelerators(destination, source)
     Widget destination;
     Widget source;

Just remember that the source is the widget whose actions you want executed, and the destination is the widget you want the events to be gathered in. To understand the use of the phrase install accelerators, think of the accelerators as the XtNaccelerators resource of the source widget, together with the actions of that widget, and the destination as the widget to which these actions are transplanted (i.e., “installed”).

XtInstallAccelerators() is always called from the application. (Widgets never install accelerators, because by definition they don't know about any other widgets.) In applications, accelerators can be installed any time, before or after the widgets are realized. Just before the XtAppMainLoop() call is a good place.

As an example, we'll add accelerators to the xbox1 application, which is the Athena version of xrowcolumn from Chapter 3, More Techniques for Using Widgets. This application displays two Command widgets in a Box, as shown in Figure 8-1.

Figure 8-1. xbox1: two Command widgets in a Box

To add accelerators requires a single line of code--a call to XtInstallAccelerators(), as shown in Example 8-1.

main(argc, argv)
int argc;
char **argv;
{
    XtAppContext app_context;
    Widget topLevel, box, quit;
      .
      .
      .
    /* allow quit widget's actions to be invoked by events in box. */
    XtInstallAccelerators(box, quit);
    XtAppMainLoop(app_context);
}

The actual value of the accelerator table is set through the resource mechanism. The XtNaccelerators resource is set for the widget whose actions are to be invoked from another widget. Xt stores this accelerator table, in compiled form, in the widget's instance structure when the widget is created. When the application calls XtInstallAccelerators(), the accelerator table stored in the widget is merged with the translation table of the widget that will be capturing the events. (If XtRemoveAccelerators is called, the original translation table, prior to merging with the accelerators from the source widget, is restored.)

Example 8-2 shows a possible app-defaults file.

*quit.label:  Quit
*pressme.label:  Press me
*quit.accelerators: \n\
        <KeyPress>q:    set() notify()

This resource setting will allow a q typed anywhere in the Box widget that comprises the xbox1 application window to invoke the quit widget's notify() action (which, as you may recall from Section 2.4, "Connecting Widgets to Application Code," in turn invokes the Quit callback installed by the application). Notice that the accelerators are specified as a resource of the source widget, even though the events that invoke them will come from the destination widget.

There are some differences in the translation tables that can be used for accelerators.

If you install accelerators in the Box widget as shown in Example 8-2, you will notice that even though the destination widget is Box, keyboard input will also be accepted in the children of box, including not only the quit widget but also the pressme widget. This is because of a characteristic of X called event propagation.

The server sends to the client only the types of events the client selects. Internally, Xt selects events using the Xlib call XSelectInput(). From a Toolkit application, this is hidden because the translation mechanism automatically selects the appropriate event types specified in the translation table. (As we will see in Chapter 9, More Input Techniques, Xt provides a low-level event-handling mechanism that exposes event selection more directly.)

Event selection reduces the amount of network traffic, the number of events the server has to generate, and the number of unneeded events the client must process only to throw away.

Most event types are selected on a per-window basis. Each selected event that arrives at the client contains the window ID of the window it was selected for. (Non-maskable events, the last five event types in Table 8-1, are the exception; they are selected using a different mechanism or are not selected at all.)

Pointer and keyboard events propagate through windows that have not selected them, as shown below in Figure 8-2. That is, if the pressme widget's window has not selected KeyPress events, any key events that occur in that window will be passed on to its parent, the Box widget. If the Box widget's window didn't select them either, they would be passed on to the window created by the top-level Shell widget, and so on. Events propagate through the window hierarchy all the way to the root window, until they reach a window that selected them. (If no window has selected them, they are never sent by the server.) Xt treats an event that originally occurred in some descendent widget just as if it actually happened in the widget that selected the event.

Figure 8-2. Key event propagation in xbox

Propagation is a characteristic of ButtonPress, ButtonRelease, KeyPress, KeyRelease, MotionNotify, EnterNotify, and LeaveNotify events only. As mentioned earlier, keyboard events are the events most often used as accelerators.

In the version of xbox we just looked at, keyboard events propagate through the Command widgets to the Box widget, because they are not selected by the Command widgets. When they reach the Box widget, they match the events specified in the accelerator table and invoke actions from the quit widget.

The Command widgets have a default translation table that includes pointer button events and enter/leave events. Xt, therefore, selects these events for each Command widget. Before accelerators are installed, the Box widget has no translation table and therefore has no events selected for it. When the accelerators are installed, the accelerator table is merged with the (nonexistent) translation table of the Box widget and becomes the Box's translation table. Xt then selects keyboard events for the Box widget.

But consider the resource settings in Example 8-3.

*quit.label:  Quit
*pressme.label:  Press me
*pressme.translations:  #override \n\
        <KeyPress>p:    set() notify()
*quit.accelerators: \n\
        <KeyPress>q:    set() notify()

No key event will propagate through a widget that has a translation for any key event. With the resource settings in Example 8-3, since pressme has a translation for the p key, the q key will not propagate through the widget. Therefore, it is often better to specify all key events as accelerators and install them on a common ancestor.

Accelerators are just merged into translations--they are not a completely different mechanism. The #augment (default) or #override directives used in accelerator tables specify whether the accelerator should override or augment existing translations for the destination widget. For example, if box had a translation of its own that matched the event sequence in the accelerator installed on the same widget, whether the translation or the accelerator would be invoked depends on whether #augment (the default) or #override had been specified as the accelerator directive. (This example is a little farfetched, since the Box widget defines no actions or translations--but it illustrates the point.)

When using or writing widgets, event propagation is usually important only for accelerators, because widgets are rarely layered in such a way that any of the ones that accept input are obscured.

If you want to install accelerators from more than one widget, you can call XtInstallAccelerators() once for every widget whose actions you want executable from the destination. Alternatively, you can call XtInstallAllAccelerators() just once for a whole application, specifying the application's top-level window as both the destination and the source. XtInstallAllAccelerators() recursively traverses the widget tree rooted at the source, and installs the accelerators of each widget onto the destination.

For example, to install accelerators from both the quit and pressme widgets onto box, you could replace the call to XtInstallAccelerators() shown in Example 8-3 with:^[57]

XtInstallAllAccelerators(box, box);

You could then define an app-defaults file such as the following:

*quit.label:  Quit
*pressme.label:  Press me
*pressme.accelerators:   \n\
        <KeyPress>p:    set() notify()
*quit.accelerators:      \n\
        <KeyPress>q:    set() notify()

Because you would be most likely to specify distinct KeyPress events to invoke the actions in each Command widget, you would normally specify each accelerator resource separately, as shown above. But in the unlikely case that you wanted actions of multiple Command widgets to be invoked by the exact same event, you could do this instead. For example:

*Command.accelerators:   \n\
        <KeyPress>:  set() notify()

would invoke the set and notify actions of every Command widget, but not of widgets belonging to other classes.

Or assuming that there were multiple Box widgets in an application, one containing options, and the other commands, you might specify something like this:

*optionsbox*accelerators:   \n\
        <KeyPress>:  set() notify()

to invoke the actions of every Command widget in optionsbox only.

The point is that, like any resource setting, an accelerator table can apply to only one widget, to a group of children of a widget, or to an entire class, depending on how you identify the widgets for which you are setting the XtNaccelerators resource.

If you want to install a default accelerator table from within a program, you must follow similar steps to those used for translations, but with the following differences:

Motif accelerators are keyboard shortcuts for menus, but they are used in a way that is completely different from that of the standard Xt accelerators just described.

When a RowColumn widget has been configured to operate as a popup menu or MenuBar, its XmNmenuAccelerator resource is activated. This resource can be set to a keysym which, when pressed, will pop up the popup menu or move the focus to the first item in the MenuBar. For example, the effective default value for XmNmenuAccelerator for the MenuBar is <KeyUp>F10.

RowColumn also has a subpart which has an XmNbuttonAccelerators resource. The XmNbuttonAccelerators resource is set to an array of keysyms, which when pressed will trigger the respective buttons. The XmNbuttonAcceleratorText resource is an array that lets you provide text that will appear in each button, to show the user the accelerator for each button.

All the resources that begin with XmNbutton can only be used when a menu is created with a function that begins with XmCreateSimple (there is one for each of the six types of Motif menus). These functions create a menu and populate it with children. Here are the other RowColumn subresources that configure the children as they are created:

These resources work only when set while creating a menu using XmCreateSimple*Menu such as XmCreateSimplePopupMenu(). Setting them at any later time will have no effect. Some resources that configure the children of menus are not listed here.

Xt calls the source widget's display_accelerators method when the accelerators are installed. The purpose of this method is to display to the user the installed accelerators. The method is passed a string representation of the accelerator table, which the method can theoretically manipulate into a form understandable by the user.

All Motif widgets just set this method to NULL. All of the Athena widgets inherit the Core widget's display_accelerators method by initializing the appropriate member of the class structure to XtInheritDisplayAccelerators. This default method, as implemented in the MIT distribution, does nothing.