Appendix B

Translation Table Syntax


Syntax is specified in EBNF notation with the following conventions:

[ a ] Means either nothing or "a"
{ a } Means zero or more occurrences of "a"
( a | b ) Means either "a" or "b"
\\nIs the newline character

All terminals are enclosed in double quotation marks (" "). Informal descriptions are enclosed in angle brackets (< >).


The syntax of a translation table is

translationTable = [ directive ] { production }
directive = ( "#replace" | "#override" | "#augment" ) "\\n"
production = lhs ":" rhs "\\n"
lhe= ( event | keyseq ) ( "," (event | keyseq) )
keyseq = """ keychar (keychar) """
keychar = [ "^" | "$" | "\\" ] <ISO Latin 1 character>
event = [modifier_list] "<"event_type">" [ "(" count["+"] ")" ] {detail}
modifier_list = ( ["!"] [":"] {modifier} ) | "None"
modifier = ["~"] modifier_name
count = (" 1 " | "2" | "3" | "4" |... )
modifier_name = "@" <keysym> | <see ModifierNames table below>
event_type = <see Event Types table below>
detail = <event specific details>
rhs= { name "(" [params] ")" }
name = namechar { namechar }
namechar = { "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-" }
params = string { "," string }
string = quoted_string | unquoted_string
quoted_string = """ {<Latin 1 character> | escape_char) ["\\\\" ] """
escape_char = "\\""
unquoted_string = t<Latin 1 character except space, tab, ",", "\\n", ")">)

The params field is parsed into a list of String values that will be passed to the named action procedure. A quoted string may contain an embedded quotation mark if the quotation mark is preceded by a single backslash (\). The three-character sequence "\\" " is interpreted as " single backslash followed by end-of-string".

Modifier Names

The modifier field is used to specify standard X keyboard and button modifier mask bits. Modifiersare legal on event types KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotify, EnterNotify, LeaveNotify, and their abbreviations. An error is generated when a translation table that contains modifiers for any other events is parsed.

In key sequences, a circumflex (^) is an abbreviation for the Control modifier, a dollar sign ($) is an abbreviation for Meta, and a backslash (\) can be used to quote any character, in particular a double quote ("), a circumflex (^), a dollar sign ($), and another backslash (\). Briefly:
No Modifiers: None <event> detail
Any Modifiers: <event> detail
Only these Modifiers: ! mod1 mod2 <event> detail
These modifiers and any others: mod1 mod2 <event> detail

The use of "None" for a modifier list is identical to the use of an exclamation point with no modifiers.

Modifier Abbreviation Meaning
Ctrl cControl modifier bit
Shift s Shift modifier bit
Lock lLock modifier bit
Meta mMeta key modifier
Hyper hHyper key modifier
SupersuSuper key modifier
Alta Alt key modifier
Mod1 Mod1 modifier bit
Mod2 Mod2 modifier bit
Mod3 Mod3 modifier bit
Mod4 Mod4 modifier bit
Mod5 Mod5 modifier bit
Button1 Button1 modifier bit
Button2 Button2 modifier bit
Button3 Button3 modifier bit
Button4 Button4 modifier bit
Button5 Button5 modifier bit
None No modifiers
Any Any modifier combination

A key modifier is any modifier bit one of whose corresponding KeyCodes contains the corresponding left or right KeySym. For example, "m" or "Meta" means any modifier bit mapping to a KeyCode whose KeySym list contains XK_Meta_L or XK_Meta_R. Note that this interpretation is for each display, not global or even for each application context. The Control, Shift, and Lock modifier names refer explicitly to the corresponding modifier bits; there is no additional interpretation of KeySyms for these modifiers.

Because it is possible to associate arbitrary KeySyms with modifiers, the set of key modifiers is extensible. The "@" <keysym> syntax means any modifier bit whose corresponding KeyCode contains the specified KeySym name.

A modifier_list/KeySym combination in a translation matches a modifiers/KeyCode combination in an event in the following ways:

  1. If a colon (:) is used, the Intrinsics call the display's XtKeyProc with the KeyCode and modifiers. To match, (modifiers & ~modifiers_return) must equal modifier_list, and keysym_return must equal the given KeySym.

  2. If (:) is not used, the Intrinsics mask off all don't-care bits from the modifiers. This value must be equal to modifier_list. Then, for each possible combination of don't-care modifiers in the modifier list, the Intrinsics call the display's XtKeyProc with the KeyCode and that combination ORed with the cared-about modifier bits from the event. Keysym_return must match the KeySym in the translation.

Event Types

The event-type field describes XEvent types. In addition to the standard Xlib symbolic event type names, the following event type synonyms are defined:

Type Meaning
KeyDown KeyPress
KeyUp KeyRelease
BtnDown ButtonPress
Motion MotionNotify
PtrMoved MotionNotify
MouseMoved MotionNotify
Enter EnterNotify
EnterWindow EnterNotify
Leave LeaveNotify
LeaveWindow LeaveNotify
FocusIn FocusIn
FocusOut FocusOut
Keymap KeymapNotify
Expose Expose
GrExp GraphicsExpose
NoExp NoExpose
Visible VisibilityNotify
Create CreateNotify
Destroy DestroyNotify
Unmap UnmapNotify
MapReq MapRequest
Reparent ReparentNotify
Configure ConfigureNotify
ConfigureReq ConfigureRequest
Grav GravityNotify
ResReq ResizeRequest
Circ CirculateNotify
CircReq CirculateRequest
Prop PropertyNotify
SelClr SelectionClear
SelReq SelectionRequest
Select SelectionNotify
Clrmap ColormapNotify
Message ClientMessage
Mapping MappingNotify

The supported abbreviations are:

Abbreviation Event Type Including
Ctrl KeyPress with Control modifier
Meta KeyPress with Meta modifier
Shift KeyPress with Shift modifier
BtnlDown ButtonPress with Button1 detail
Btn1Up ButtonRelease with Button1 detail
Btn2Down ButtonPress with Button2 detail
Btn2Up ButtonRelease with Button2 detail
Btn3DownButtonPress with Button3 detail
Btn3UpButtonRelease with Button3 detail
Btn4Down ButtonPress with Button4 detail
Btn4Up ButtonRelease with Button4 detail
Btn5Down ButtonPress with Button5 detail
Btn5Up ButtonRelease with Button5 detail
BtnMotion MotionNotify with any button modifier
BtnlMotion MotionNotify with Button1 modifier
Btn2Motion MotionNotify with Button2 modifier
Btn3Motion MotionNotify with Button3 modifier
Btn4Motion MotionNotify with Button4 modifier
Btn5Motion MotionNotify with Button5 modifier

The detail field is event-specific and normally corresponds to the detail field of the corresponding event as described by X Window System Protocol, Section 11. The detail field is supported for the following event types:

Event Event Field
KeyPress KeySym from event detail (keycode)
KeyRelease KeySym from event detail (keycode)
ButtonPress button from event detail
ButtonRelease button from event detail
MotionNotify event detail
EnterNotify event mode
LeaveNotify event mode
FocusIn event mode
FocusOut event mode
PropertyNotify atom
SelectionClear selection
SelectionRequest selection
SelectionNotify selection
ClientMessage type
MappingNotify request

If the event type is KeyPress or KeyRelease, the detail field specifies a KeySym name in standard format which is matched against the event as described above, for example, <Key>A.

For the PropertyNotify, SelectionClear, SelectionRequest, SelectionNotify and ClientMessage events the detail field is specified as an atom name; for example, <Message>WM_PROTOCOLS. For the MotionNotify, EnterNotify, LeaveNotify, FocusIn, FocusOut and MappingNotify events, either the symbolic constants as defined by X Window System Protocol, Section 11, or the numeric values may be specified.

If no detail field is specified, then any value in the event detail is accepted as a match.

A KeySym can be specified as any of the standard KeySym names, a hexadecimal number prefixed with "0x" or "0X", an octal number prefixed with "0" or a decimal number. A KeySym expressed as a single digit is interpreted as the corresponding Latin 1 KeySym, for example, "0" is the KeySym XK_0. Other single character KeySyms are treated as literal constants from Latin 1, for example, "!" is treated as 021. Standard KeySym names are as defined in <X11/keysymdef.h> with the "XK_" prefix removed.

Canonical Representation

Every translation table has a unique, canonical text representation. This representation is passed to a widget's display_accelerator procedure to describe the accelerators installed on that widget. The canonical representation of a translation table is (see also "Syntax")

translationTable = {production}
production = lhs ":" rhs "\\n"
lhs=event { "," event }
event = [modifier_list] "<"event_type">" [ "(" count["+"] ")" ] {detail}
modifier_list = ["l"] [":"] {modifier}
modifier = ["~"] modifier_name
count = ("1" | "2" | "3" | "4" | )
modifier_name = "@" <keysym> | <see canonical modifier names below>
event_type = <see canonical event types below>
detail = <event specific details>
rhs= { name "(" [params] ")" }
name = namechar { namechar }
narnechar = { "a"-"z" | "A"-"Z" | "0"-"9"| "_" | "-" }
params = string ("," string)
string = quoted_string
quoted_string = """ {<Latin 1 character> | escape_char} ["\\\\" ] """
escape_char = "\\""

The canonical modifier names are
Ctrl Mod1Button1
Shift Mod2Button2
Lock Mod3Button3
Mod4 Button4
Mod5 Button5

The canonical event types are

KeyPress KeyRelease
ButtonPress ButtonRelease
MotionNotify EnterNotify
LeaveNotify FocusIn
FocusOut KeymapNotify
Expose GraphicsExpose,
NoExpose VisibilityNotify
CreateNotify Destroy Not ify
UnmapNotify MapNotify
MapRequest ReparentNotify
ConfigureNotify ConfigureRequest
GravityNotify ResizeRequest
CirculateNotify CirculateRequest
PropertyNotify Selection Clear
SelectionRequest SelectionNotify
ColormapNotify ClientMessage



Contents Previous Chapter Next Chapter