X Event Translations (Unix Power Tools, 3rd Edition)

6.4. X Event Translations

This article introduces event translations, which are special X Window System resources that control actions of things like mouse clicks. Section 6.3 introduces X resources and shows their syntax. Section 6.5 through Section 6.9 explain how to set and check resources -- as you log in and after.

We've discussed the basics of resource-naming syntax. From the sample resource settings, it appears that what many resource variables do is self-evident or nearly so. Among the less obvious resource variables, there is one type of specification, an event translation, that can be used with many clients and warrants somewhat closer examination.

User input and several other types of information pass from the server to a client in the form of events. An event is a packet of information that gives the client something to act on, such as keyboard input. Moving the pointer or pressing a key causes input events to occur. When a program receives a meaningful event, it responds with some sort of action.

For many clients, the resource manager recognizes mappings between certain input events (such as a pointer button click) and some sort of action by the client program (such as selecting text). A mapping between one or more events and an action is called a translation. A resource containing a list of translations is called a translation table.

Many event translations are programmed into an application and are invisible to the user.[28] For our purposes we are only concerned with very visible translations of certain input events, primarily the translation of keystrokes and pointer button clicks to particular actions by a client program.

[28]For more information on events and translations, see O'Reilly & Associates' X Window System Guide, Volume 4.

The operation of many clients, notably xterm, is partly determined by default input event translations. For example, selecting text with the first pointer button (an event) saves that text into memory (an action).

In this case, the input "event" is actually three separate X events:

Pressing the first pointer button.

Moving the pointer while holding down the first button.[29]

[29]Actually, if there is no text to select, motion is recorded as a series of MotionNotify events.
Releasing the button.

Each of these input events performs a part of the action of selecting text:

Unselects any previously selected text and begins selecting new text.
Extends the selection.
Ends the selection, saving the text into memory (both as the primary selection and CUT_BUFFER0).

The event and action mappings would be expressed in a translation table as follows:

<Btn1Down>: select-start( )\n\
<Btn1Motion>: select-extend( )\n\
<Btn1Up>: select-end(primary,CUT_BUFFER0)

where each event is enclosed in angle brackets (<>) and produces the action that follows the colon (:). A space or TAB generally precedes the action, though this is not mandatory:

<event>: action

A translation table must be a continuous string. To link multiple mappings as a continuous string, each event-action line should be terminated by a newline character (\n), which is in turn followed by a backslash (\) to escape the actual newline.

These are default translations for xterm.[30] All of the events are simple, comprised of a single button motion. As we'll see, events can also have modifiers: i.e., additional button motions or keystrokes (often CTRL or Meta) that must be performed with the primary event to produce the action. (Events can also have modifiers that must not accompany the primary event if the action is to take place.)

[30]They are actually slightly simplified versions of default translations. Before you can understand the actual translations listed in the xterm manual page, you must learn more about the syntax of translations. We cover the basics here; for more information, see O'Reilly & Associates' X Window System Guide, Volume 3M, Appendix F.

As you can see, the default actions of keysym mappings are hardly intuitive. The client's manpage usually lists the event-action mappings that you can modify.

You can specify nondefault translations using a translation table (a resource containing a list of translations). Since actions are part of the client application and cannot be modified, you are actually specifying alternative events to perform an action.[31] Keep in mind that only applications written with the X Toolkit (or an Xt-based toolkit such as the Motif Toolkit) recognize translation-table syntax as described here.

[31]As we'll see, in certain cases you may be able to supply an alternative argument (such as a selection name) to an action. These changes are interpreted by the resource manager.

The basic syntax for specifying a translation table as a resource is as follows:

[object*[subobject...]]*translations:   #override\
        [modifier]<event>:   action

The first line is basically like any other resource specification with a few exceptions. First, the final argument is always translations, indicating that one (or more) of the event-action bindings associated with the [object*[subobject...]] are being modified.

Second, note that #override is not the value of the resource; it is literal and indicates that what follows should override any default translations. In effect, #override is no more than a pointer to the true value of the resource: a new event-action mapping (on the following line) where the event may take a modifier.

A not-so-obvious principle behind overriding translations is that you only literally "override" a default translation when the event(s) of the new translation match the event(s) of a default translation exactly. If the new translation does not conflict with any existing translation, it is merely appended to the defaults.

To be specified as a resource, a translation table must be a single string. The #override is followed by a backslash (\) to indicate that the subsequent line should be a continuation of the first.

In the previous basic syntax example, the value is a single event-action mapping. The value could also be a list of several mappings, linked by the characters \n\ to make the resource a continuous string.

The following xterm translation table shows multiple event-action mappings linked in this manner:

*VT100.Translations:   #override\
        <Btn1Down>:    select-start( )\n\
        <Btn1Motion>:  select-extend( )\n\
        <Btn1Up>:      select-end(primary,CUT_BUFFER0)

--VQ and SJC