Translation Table Syntax

This appendix describes the basic syntax of translation table resources, described in Chapter 9, Setting Resources.

In This Chapter:

Event Types and Modifiers

Detail Field


Complex Translation Examples


Translation Table Syntax

This appendix explains some of the more complex aspects of translation table syntax. It probably gives more detail than the average user will need, but we’ve included it to help clarify this rather complicated topic.

Event Types and Modifiers

The syntax of the translation table is sufficiently general to encompass a wide variety of events and circumstances. Event translations can be specified to handle characteristic user interface idioms like double clicking, dragging, or combining keyboard modifiers with pointer button input. To specify translations that use these features, it is necessary to learn more about the detailed syntax used to specify translations.

An activity susceptible to translation is a sequence of events and modifiers (that perform an action). Events are specified in angle brackets and modifiers precede the event they modify. The legal events that can be specified in a translation are as shown in Table H-1.

Table H-1. Event Types and Their Abbreviations

Event Name Event Type Abbreviations/Synonyms
KeyPress Keyboard Key, KeyDown
KeyUp Keyboard KeyRelease
ButtonPress Mouse Button BtnDown
ButtonRelease Mouse Button BtnUp
Btn1Down Mouse Button Press
Btn1Up Mouse Button Release
MotionNotify Mouse Motion Motion, MouseMoved, PtrMoved
ButtonMotion Motion w/any Button Down BtnMotion
ButtonlMotion Motion w/Button Down BtnlMotion
  .   .
Button5Motion Btn5Motion
EnterNotify Mouse in Window Enter,EnterWindow
LeaveNotify LeaveWindow, Leave
Focusln Keyboard Input Focus
KeymapNotify Changed Key Map Keymap
ColormapNotify Changed Color Map Clrmap
Expose Related Exposure Events
GraphicsExpose GrExp
NoExpose NoExp
VisibilityNotify Visible
CreateNotify Window Management Create
DestroyNotify Destroy
UnmapNotify Unmap
MapNotify Map
MapRequest MapReq
ReparentNotify Reparent
ConfigureNotify Configure
ConfigureRequest ConfigureReq
GravityNotify Grav
ResizeRequest ResReq
CirculateNotify Circ
CirculateRequest CircReq
PropertyNotify Prop
SelectionClear Intra-client Selection SelClr
SelectionRequest SelReq
SelectionNotify Select

The possible modifiers of an event are listed in the table. The modifiers Mod1 through Mod5 are highly system-dependent, and may not be implemented by all servers.

Table H-2. Key Modifiers

Event Modifiers Abbreviation
Ctrl c
Meta m
Shift s
Lock l
Mod1 1
. .
. .
Mod5 5

Detail Field

To provide finer control over the translation process, the event part of the translation can include an additional “detail.” For example, if you want the event to require an additional keystroke, for instance, an A key, or a Ctrl-T, then that keystroke can be specified as a translation detail. The default detail field is ANY.

The valid translation details are event-dependent. For example, to specify the above example for keypress events, you would use:





Key fields can be specified by the keysym value, as well as by the keysym symbolic name. For example, the keysym value of the Delete key is 0xffff. Keysym values can be determined by examining the file <X11/keysymdef.h> or by using the xmodmap client. (See Chapter 11, Setup Clients, for information about xmodmap.) Unfortunately, with some translations the keysym value may actually be required, since not all keysym symbolic names may be properly interpreted.


Modifiers can be closely controlled to define exactly which events can be specified. For example, if you want the action to be performed by pointer button clicks, but not by pointer button clicks with the Control or Shift key down, these limitations can be specified. Similarly, if you don’t care if there are modifiers present, this can also be specified.

Table H-3 lists the available event modifiers.

Table H-3. Event Modifiers and their Meanings

Modifier Meaning
None <event> No modifiers allowed.
<event> Doesn’t care. Any modifiers ok.
Mod1 Mod Mod1 and Mod2, plus any others (i.e., anything that includes m1 and m2).
!Mod1 Mod2<event> Mod1 and Mod2 but nothing else.
Mod1 ˜Mod2<event> Mod1 and not Mod2.

Complex Translation Examples

The following translation specifies that function f is to be invoked when both the Shift key and the third pointer button are pressed.

Shift<Btn3Down>: f()

To specify that both the Control and Shift keys are to be pressed use:

Ctrl Shift<Btn3Down>: f()

To specify an optional repeat count for an activity, put a number in parentheses after the action. The number refers to the whole translation. To make the last example require a double-click, with both Control and Shift keys pressed, use:

Ctrl Shift<Btn3Down> (2) : f()

The server distinguishes between single-clicks and double-clicks based on a pre-programmed timing interval. If a second click occurs before the interval expires, then the event is interpreted as a double-click; otherwise the event is interpreted as two single-clicks. The variable clickTime is maintained deep in the internals of X. Unfortunately, thus far there is no way to set this time interval to match user preference. Currently it is set to be 200 milliseconds.

A translation involving two or more clicks can be specified as (2+) in the previous example. In general, a plus sign following the number n would mean n or more occurrences of the event.

Multiple events can be specified by separating them with commas on the translation line. To indicate pressing button 1, pressing button 2, then releasing button 1, and finally releasing button 2, use:

<Btn1Down>,<Btn2Down>,<Btn1Up>,<Btn2Up>: f()

Another way to describe this action in English would be to say “while button 1 is down, click button 2.” “Meaningless” pointer movement is generally ignored. In the previous case, for example, if pointer motion occurred while the buttons were down, it would not interfere with detection of the event Thus, inadvertent pointer jiggling will not thwart even the most complex user-input sequences.

Get X Window System User's Guide for X11 R3 and R4 of the X Window System now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.