xref: /xsrc/external/mit/libXt/dist/specs/appB.xml

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<appendix id='Translation_Table_Syntax'>
<title>Translation Table Syntax</title>
<para><emphasis role='strong'>Notation</emphasis></para>

<para>
Syntax is specified in EBNF notation with the following conventions:
</para>

<informaltable frame='none'>
  <?dbfo keep-together="auto" ?>
  <tgroup cols='2' align='left' colsep='0' rowsep='0'>
  <colspec colwidth='0.1*' colname='c1'/>
  <colspec colwidth='1.0*' colname='c2'/>
  <tbody>
    <row>
      <entry>[ a ]</entry>
      <entry>Means either nothing or &ldquo;a&rdquo;</entry>
    </row>
    <row>
      <entry>{ a }</entry>
      <entry>Means zero or more occurrences of &ldquo;a&rdquo;</entry>
    </row>
    <row>
      <entry>( a | b )</entry>
      <entry>Means either &ldquo;a&rdquo; or &ldquo;b&rdquo;</entry>
    </row>
    <row>
      <entry>\\n</entry>
      <entry>Is the newline character</entry>
    </row>
  </tbody>
  </tgroup>
</informaltable>

<para>
All terminals are enclosed in double quotation marks ("&nbsp;").
Informal descriptions are enclosed in angle brackets (&lt; &gt;).
Syntax
</para>

<para>The syntax of a translation table is</para>
<informaltable frame='none'>
  <?dbfo keep-together="auto" ?>
  <tgroup cols='2' align='left' colsep='0' rowsep='0'>
  <colspec colwidth='0.2*' colname='c1'/>
  <colspec colwidth='1.0*' colname='c2'/>
  <tbody>
    <row>
      <entry>translationTable</entry>
      <entry>= [ directive ] { production }</entry>
    </row>
    <row>
      <entry>directive</entry>
      <entry>= ( &ldquo;#replace&rdquo; | &ldquo;#override&rdquo; | &ldquo;#augment&rdquo; ) &ldquo;\\n&rdquo;</entry>
    </row>
    <row>
      <entry>production</entry>
      <entry>= lhs &ldquo;:&rdquo; rhs &ldquo;\\n&rdquo;</entry>
    </row>
    <row>
      <entry>lhs</entry>
      <entry>= ( event | keyseq ) { &ldquo;,&rdquo; (event | keyseq) }</entry>
    </row>
    <row>
      <entry>keyseq</entry>
      <entry>= &ldquo;"&rdquo; keychar {keychar} &ldquo;"&rdquo;</entry>
    </row>
    <row>
      <entry>keychar</entry>
      <entry>= [ &ldquo;^&rdquo; | &ldquo;$&rdquo; | &ldquo;\\&rdquo; ] &lt;ISO Latin 1 character&gt;</entry>
    </row>
    <row>
      <entry>event</entry>
      <entry>= [modifier_list] &ldquo;&lt;&rdquo;event_type&ldquo;&gt;&rdquo; [ &ldquo;(&rdquo; count[&ldquo;+&rdquo;] &ldquo;)&rdquo; ] {detail}</entry>
    </row>
    <row>
      <entry>modifier_list</entry>
      <entry>= ( [&ldquo;!&rdquo;] [&ldquo;:&rdquo;] {modifier} ) | &ldquo;None&rdquo;</entry>
    </row>
    <row>
      <entry>modifier</entry>
      <entry>= [&ldquo;~&rdquo;] modifier_name</entry>
    </row>
    <row>
      <entry>count</entry>
      <entry>= (&ldquo;1&rdquo; | &ldquo;2&rdquo; | &ldquo;3&rdquo; | &ldquo;4&rdquo; | ...)</entry>
    </row>
    <row>
      <entry>modifier_name</entry>
      <entry>= &ldquo;@&rdquo; &lt;keysym&gt; | &lt;see ModifierNames table below&gt;</entry>
    </row>
    <row>
      <entry>event_type</entry>
      <entry>= &lt;see Event Types table below&gt;</entry>
    </row>
    <row>
      <entry>detail</entry>
      <entry>= &lt;event specific details&gt;</entry>
    </row>
    <row>
      <entry>rhs</entry>
      <entry>= { name &ldquo;(&rdquo; [params] &ldquo;)&rdquo; }</entry>
    </row>
    <row>
      <entry>name</entry>
      <entry>= namechar { namechar }</entry>
    </row>
    <row>
      <entry>namechar</entry>
      <entry>= { &ldquo;a&rdquo;&ndash;&ldquo;z&rdquo; | &ldquo;A&rdquo;&ndash;&ldquo;Z&rdquo; | &ldquo;0&rdquo;&ndash;&ldquo;9&rdquo; | &ldquo;_&rdquo; | &ldquo;&ndash;&rdquo; }</entry>
    </row>
    <row>
      <entry>params</entry>
      <entry>= string {&ldquo;,&rdquo; string}</entry>
    </row>
    <row>
      <entry>string</entry>
      <entry>= quoted_string | unquoted_string</entry>
    </row>
    <row>
      <entry>quoted_string</entry>
      <entry>= <quote>"</quote> {&lt;Latin 1 character&gt; | escape_char} [&ldquo;\\"&rdquo; ] <quote>"</quote></entry>
    </row>
    <row>
      <entry>escape_char</entry>
      <entry>= &ldquo;\\"&rdquo;</entry>
    </row>
    <row>
      <entry>unquoted_string</entry>
      <entry>= {&lt;Latin 1 character except space, tab, &ldquo;,&rdquo;, &ldquo;\\n&rdquo;, &ldquo;)&rdquo;&gt;}</entry>
    </row>
  </tbody>
  </tgroup>
</informaltable>

<para>
The <emphasis remap='I'>params</emphasis> field is parsed into a list of
<function>String</function>
values that will be passed to the named action procedure.  A
<emphasis remap='I'>quoted string</emphasis> may contain an embedded quotation mark if the
quotation mark is preceded by a single backslash (\).  The
three-character sequence &ldquo;\\"&rdquo; is interpreted as &ldquo;single backslash
followed by end-of-string&rdquo;.
</para>
<para><emphasis role='strong'>Modifier Names</emphasis></para>

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

<itemizedlist spacing='compact'>
  <listitem>
    <para>
If the modifier list has no entries and is not &ldquo;None&rdquo;,
it means &ldquo;don't care&rdquo; on all modifiers.
    </para>
  </listitem>
  <listitem>
    <para>
If an exclamation point (!) is specified at the beginning
of the modifier list,
it means that the listed modifiers must be in the correct state
and no other modifiers can be asserted.
    </para>
  </listitem>
  <listitem>
    <para>
If any modifiers are specified
and an exclamation point (!) is not specified,
it means that the listed modifiers must be in the
correct state and &ldquo;don't care&rdquo; about any other modifiers.
    </para>
  </listitem>
  <listitem>
    <para>
If a modifier is preceded by a tilde (~),
it means that that modifier must not be asserted.
    </para>
  </listitem>
  <listitem>
    <para>
If &ldquo;None&rdquo; is specified, it means no modifiers can be asserted.
    </para>
  </listitem>
  <listitem>
    <para>
If a colon (:) is specified at the beginning of the modifier list,
it directs the Intrinsics to apply any standard modifiers in the
event to map the event keycode into a KeySym.
The default standard modifiers are Shift and Lock,
with the interpretation as defined in <emphasis remap='I'>X Window
System Protocol</emphasis>, Section 5.
The resulting KeySym must exactly match the specified
KeySym, and the nonstandard modifiers in the event must match the
modifier list.
For example, &ldquo;:&lt;Key&gt;a&rdquo; is distinct from &ldquo;:&lt;Key&gt;A&rdquo;,
and &ldquo;:Shift&lt;Key&gt;A&rdquo; is distinct from &ldquo;:&lt;Key&gt;A&rdquo;.
    </para>
  </listitem>
  <listitem>
    <para>
If both an exclamation point (!) and a colon (:) are specified at
the beginning of the modifier list, it means that the listed
modifiers must be in the correct state and that no other modifiers
except the standard modifiers can be asserted.  Any standard
modifiers in the event are applied as for colon (:) above.
    </para>
  </listitem>
  <listitem>
    <para>
If a colon (:) is not specified,
no standard modifiers are applied.
Then, for example, &ldquo;&lt;Key&gt;A&rdquo; and &ldquo;&lt;Key&gt;a&rdquo; are equivalent.
    </para>
  </listitem>
</itemizedlist>

<para>
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:
</para>

<programlisting>
No modifiers:                   None &lt;event&gt; detail
Any modifiers:                  &lt;event&gt; detail
Only these modifiers:           ! mod1 mod2 &lt;event&gt; detail
These modifiers and any others: mod1 mod2 &lt;event&gt; detail
</programlisting>

<para>
The use of &ldquo;None&rdquo; for a modifier list is identical to the use
of an exclamation point with no modifers.
</para>

<informaltable frame='topbot'>
  <?dbfo keep-together="auto" ?>
  <tgroup cols='3' align='left' colsep='0' rowsep='0'>
  <colspec colwidth='1.0*' colname='c1'/>
  <colspec colwidth='1.0*' colname='c2'/>
  <colspec colwidth='1.0*' colname='c3'/>
  <thead>
    <row rowsep='1'>
      <entry>Modifier</entry>
      <entry>Abbreviation</entry>
      <entry>Meaning</entry>
    </row>
  </thead>
  <tbody>
    <row>
      <entry>Ctrl</entry>
      <entry>c</entry>
      <entry>Control modifier bit</entry>
    </row>
    <row>
      <entry>Shift</entry>
      <entry>s</entry>
      <entry>Shift modifier bit</entry>
    </row>
    <row>
      <entry>Lock</entry>
      <entry>l</entry>
      <entry>Lock modifier bit</entry>
    </row>
    <row>
      <entry>Meta</entry>
      <entry>m</entry>
      <entry>Meta key modifier</entry>
    </row>
    <row>
      <entry>Hyper</entry>
      <entry>h</entry>
      <entry>Hyper key modifier</entry>
    </row>
    <row>
      <entry>Super</entry>
      <entry>su</entry>
      <entry>Super key modifier</entry>
    </row>
    <row>
      <entry>Alt</entry>
      <entry>a</entry>
      <entry>Alt key modifier</entry>
    </row>
    <row>
      <entry>Mod1</entry>
      <entry></entry>
      <entry>Mod1 modifier bit</entry>
    </row>
    <row>
      <entry>Mod2</entry>
      <entry></entry>
      <entry>Mod2 modifier bit</entry>
    </row>
    <row>
      <entry>Mod3</entry>
      <entry></entry>
      <entry>Mod3 modifier bit</entry>
    </row>
    <row>
      <entry>Mod4</entry>
      <entry></entry>
      <entry>Mod4 modifier bit</entry>
    </row>
    <row>
      <entry>Mod5</entry>
      <entry></entry>
      <entry>Mod5 modifier bit</entry>
    </row>
    <row>
      <entry>Button1</entry>
      <entry></entry>
      <entry>Button1 modifier bit</entry>
    </row>
    <row>
      <entry>Button2</entry>
      <entry></entry>
      <entry>Button2 modifier bit</entry>
    </row>
    <row>
      <entry>Button3</entry>
      <entry></entry>
      <entry>Button3 modifier bit</entry>
    </row>
    <row>
      <entry>Button4</entry>
      <entry></entry>
      <entry>Button4 modifier bit</entry>
    </row>
    <row>
      <entry>Button5</entry>
      <entry></entry>
      <entry>Button5 modifier bit</entry>
    </row>
    <row>
      <entry>None</entry>
      <entry></entry>
      <entry>No modifiers</entry>
    </row>
    <row>
      <entry>Any</entry>
      <entry></entry>
      <entry>Any modifier combination</entry>
    </row>
  </tbody>
  </tgroup>
</informaltable>

<para>
A key modifier is any modifier bit one of whose corresponding KeyCodes
contains the corresponding left or right KeySym.
For example,
&ldquo;m&rdquo; or &ldquo;Meta&rdquo; 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.
</para>

<para>
Because it is possible to associate arbitrary KeySyms with modifiers, the set of
key modifiers is extensible.  The &ldquo;@&rdquo; &lt;keysym&gt; syntax means any
modifier bit whose corresponding KeyCode contains the specified KeySym name.
</para>

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

<orderedlist>
  <listitem>
    <para>
If a colon (:) is used, the Intrinsics call the display's
<xref linkend='XtKeyProc' xrefstyle='select: title'/>
with the KeyCode and modifiers.
To match, (<emphasis remap='I'>modifiers</emphasis> &amp; ~<emphasis remap='I'>modifiers_return</emphasis>) must equal <emphasis remap='I'>modifier_list</emphasis>, and
<emphasis remap='I'>keysym_return</emphasis> must equal the given KeySym.
    </para>
  </listitem>
  <listitem>
    <para>
If (:) is not used, the Intrinsics mask off all don't-care bits from the
modifiers.
This value must be equal to <emphasis remap='I'>modifier_list</emphasis>.
Then, for each possible combination of
don't-care modifiers in the modifier list, the Intrinsics call the display's
<xref linkend='XtKeyProc' xrefstyle='select: title'/>
with the KeyCode and that combination ORed with the cared-about modifier bits
from the event.
<emphasis remap='I'>Keysym_return</emphasis> must match the KeySym in the translation.
    </para>
  </listitem>
</orderedlist>

<para><emphasis role='strong'>Event Types</emphasis></para>

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

<informaltable frame='topbot'>
  <?dbfo keep-together="auto" ?>
  <tgroup cols='2' align='left' colsep='0' rowsep='0'>
  <colspec colwidth='1.0*' colname='c1'/>
  <colspec colwidth='1.0*' colname='c2'/>
  <thead>
    <row rowsep='1'>
      <entry>Type</entry>
      <entry>Meaning</entry>
    </row>
  </thead>
  <tbody>
    <row>
      <entry>Key</entry>
      <entry><function>KeyPress</function></entry>
    </row>
    <row>
      <entry>KeyDown</entry>
      <entry><function>KeyPress</function></entry>
    </row>
    <row>
      <entry>KeyUp</entry>
      <entry><function>KeyRelease</function></entry>
    </row>
    <row>
      <entry>BtnDown</entry>
      <entry><function>ButtonPress</function></entry>
    </row>
    <row>
      <entry>BtnUp</entry>
      <entry><function>ButtonRelease</function></entry>
    </row>
    <row>
      <entry>Motion</entry>
      <entry><function>MotionNotify</function></entry>
    </row>
    <row>
      <entry>PtrMoved</entry>
      <entry><function>MotionNotify</function></entry>
    </row>
    <row>
      <entry>MouseMoved</entry>
      <entry><function>MotionNotify</function></entry>
    </row>
    <row>
      <entry>Enter</entry>
      <entry><function>EnterNotify</function></entry>
    </row>
    <row>
      <entry>EnterWindow</entry>
      <entry><function>EnterNotify</function></entry>
    </row>
    <row>
      <entry>Leave</entry>
      <entry><function>LeaveNotify</function></entry>
    </row>
    <row>
      <entry>LeaveWindow</entry>
      <entry><function>LeaveNotify</function></entry>
    </row>
    <row>
      <entry>FocusIn</entry>
      <entry><function>FocusIn</function></entry>
    </row>
    <row>
      <entry>FocusOut</entry>
      <entry><function>FocusOut</function></entry>
    </row>
    <row>
      <entry>Keymap</entry>
      <entry><function>KeymapNotify</function></entry>
    </row>
    <row>
      <entry>Expose</entry>
      <entry><function>Expose</function></entry>
    </row>
    <row>
      <entry>GrExp</entry>
      <entry><function>GraphicsExpose</function></entry>
    </row>
    <row>
      <entry>NoExp</entry>
      <entry><function>NoExpose</function></entry>
    </row>
    <row>
      <entry>Visible</entry>
      <entry><function>VisibilityNotify</function></entry>
    </row>
    <row>
      <entry>Create</entry>
      <entry><function>CreateNotify</function></entry>
    </row>
    <row>
      <entry>Destroy</entry>
      <entry><function>DestroyNotify</function></entry>
    </row>
    <row>
      <entry>Unmap</entry>
      <entry><function>UnmapNotify</function></entry>
    </row>
    <row>
      <entry>Map</entry>
      <entry><function>MapNotify</function></entry>
    </row>
    <row>
      <entry>MapReq</entry>
      <entry><function>MapRequest</function></entry>
    </row>
    <row>
      <entry>Reparent</entry>
      <entry><function>ReparentNotify</function></entry>
    </row>
    <row>
      <entry>Configure</entry>
      <entry><function>ConfigureNotify</function></entry>
    </row>
    <row>
      <entry>ConfigureReq</entry>
      <entry><function>ConfigureRequest</function></entry>
    </row>
    <row>
      <entry>Grav</entry>
      <entry><function>GravityNotify</function></entry>
    </row>
    <row>
      <entry>ResReq</entry>
      <entry><function>ResizeRequest</function></entry>
    </row>
    <row>
      <entry>Circ</entry>
      <entry><function>CirculateNotify</function></entry>
    </row>
    <row>
      <entry>CircReq</entry>
      <entry><function>CirculateRequest</function></entry>
    </row>
    <row>
      <entry>Prop</entry>
      <entry><function>PropertyNotify</function></entry>
    </row>
    <row>
      <entry>SelClr</entry>
      <entry><function>SelectionClear</function></entry>
    </row>
    <row>
      <entry>SelReq</entry>
      <entry><function>SelectionRequest</function></entry>
    </row>
    <row>
      <entry>Select</entry>
      <entry><function>SelectionNotify</function></entry>
    </row>
    <row>
      <entry>Clrmap</entry>
      <entry><function>ColormapNotify</function></entry>
    </row>
    <row>
      <entry>Message</entry>
      <entry><function>ClientMessage</function></entry>
    </row>
    <row>
      <entry>Mapping</entry>
      <entry><function>MappingNotify</function></entry>
    </row>
  </tbody>
  </tgroup>
</informaltable>

<para>The supported abbreviations are:</para>

<informaltable frame='topbot'>
  <?dbfo keep-together="auto" ?>
  <tgroup cols='3' align='left' rowsep='0' colsep='0'>
  <colspec colwidth='1.0*' colname='c1'/>
  <colspec colwidth='1.0*' colname='c2'/>
  <colspec colwidth='1.0*' colname='c3'/>
  <thead>
    <row rowsep='1'>
      <entry>Abbreviation</entry>
      <entry>Event Type</entry>
      <entry>Including</entry>
    </row>
  </thead>
  <tbody>
    <row>
      <entry>Ctrl</entry>
      <entry><function>KeyPress</function></entry>
      <entry>with Control modifier</entry>
    </row>
    <row>
      <entry>Meta</entry>
      <entry><function>KeyPress</function></entry>
      <entry>with Meta modifier</entry>
    </row>
    <row>
      <entry>Shift</entry>
      <entry><function>KeyPress</function></entry>
      <entry>with Shift modifier</entry>
    </row>
    <row>
      <entry>Btn1Down</entry>
      <entry><function>ButtonPress</function></entry>
      <entry>with Button1 detail</entry>
    </row>
    <row>
      <entry>Btn1Up</entry>
      <entry><function>ButtonRelease</function></entry>
      <entry>with Button1 detail</entry>
    </row>
    <row>
      <entry>Btn2Down</entry>
      <entry><function>ButtonPress</function></entry>
      <entry>with Button2 detail</entry>
    </row>
    <row>
      <entry>Btn2Up</entry>
      <entry><function>ButtonRelease</function></entry>
      <entry>with Button2 detail</entry>
    </row>
    <row>
      <entry>Btn3Down</entry>
      <entry><function>ButtonPress</function></entry>
      <entry>with Button3 detail</entry>
    </row>
    <row>
      <entry>Btn3Up</entry>
      <entry><function>ButtonRelease</function></entry>
      <entry>with Button3 detail</entry>
    </row>
    <row>
      <entry>Btn4Down</entry>
      <entry><function>ButtonPress</function></entry>
      <entry>with Button4 detail</entry>
    </row>
    <row>
      <entry>Btn4Up</entry>
      <entry><function>ButtonRelease</function></entry>
      <entry>with Button4 detail</entry>
    </row>
    <row>
      <entry>Btn5Down</entry>
      <entry><function>ButtonPress</function></entry>
      <entry>with Button5 detail</entry>
    </row>
    <row>
      <entry>Btn5Up</entry>
      <entry><function>ButtonRelease</function></entry>
      <entry>with Button5 detail</entry>
    </row>
    <row>
      <entry>BtnMotion</entry>
      <entry><function>MotionNotify</function></entry>
      <entry>with any button modifier</entry>
    </row>
    <row>
      <entry>Btn1Motion</entry>
      <entry><function>MotionNotify</function></entry>
      <entry>with Button1 modifier</entry>
    </row>
    <row>
      <entry>Btn2Motion</entry>
      <entry><function>MotionNotify</function></entry>
      <entry>with Button2 modifier</entry>
    </row>
    <row>
      <entry>Btn3Motion</entry>
      <entry><function>MotionNotify</function></entry>
      <entry>with Button3 modifier</entry>
    </row>
    <row>
      <entry>Btn4Motion</entry>
      <entry><function>MotionNotify</function></entry>
      <entry>with Button4 modifier</entry>
    </row>
    <row>
      <entry>Btn5Motion</entry>
      <entry><function>MotionNotify</function></entry>
      <entry>with Button5 modifier</entry>
    </row>
  </tbody>
  </tgroup>
</informaltable>

<para>
The detail field is event-specific and normally corresponds to the
detail field of the corresponding event as described
by <emphasis remap='I'>X Window System Protocol</emphasis>, Section 11.
The detail field is supported for the following event types:
</para>

<informaltable frame='none'>
  <?dbfo keep-together="auto" ?>
  <tgroup cols='2' align='left' rowsep='0' colsep='0'>
  <colspec colwidth='0.5*' colname='c1'/>
  <colspec colwidth='1.0*' colname='c2'/>
  <tbody>
    <row>
      <entry>KeyPress</entry>
      <entry>KeySym from event <emphasis>detail</emphasis> (keycode)</entry>
    </row>
    <row>
      <entry>KeyRelease</entry>
      <entry>KeySym from event <emphasis>detail</emphasis> (keycode)</entry>
    </row>
    <row>
      <entry>ButtonPress</entry>
      <entry>button from event <emphasis>detail</emphasis></entry>
    </row>
    <row>
      <entry>ButtonRelease</entry>
      <entry>button from event <emphasis>detail</emphasis></entry>
    </row>
    <row>
      <entry>MotionNotify</entry>
      <entry>event <emphasis>detail</emphasis></entry>
    </row>
    <row>
      <entry>EnterNotify</entry>
      <entry>event <emphasis>mode</emphasis></entry>
    </row>
    <row>
      <entry>LeaveNotify</entry>
      <entry>event <emphasis>mode</emphasis></entry>
    </row>
    <row>
      <entry>FocusIn</entry>
      <entry>event <emphasis>mode</emphasis></entry>
    </row>
    <row>
      <entry>FocusOut</entry>
      <entry>event <emphasis>mode</emphasis></entry>
    </row>
    <row>
      <entry>PropertyNotify</entry>
      <entry><emphasis>atom</emphasis></entry>
    </row>
    <row>
      <entry>SelectionClear</entry>
      <entry><emphasis>selection</emphasis></entry>
    </row>
    <row>
      <entry>SelectionRequest</entry>
      <entry><emphasis>selection</emphasis></entry>
    </row>
    <row>
      <entry>SelectionNotify</entry>
      <entry><emphasis>selection</emphasis></entry>
    </row>
    <row>
      <entry>ClientMessage</entry>
      <entry><emphasis>type</emphasis></entry>
    </row>
    <row>
      <entry>MappingNotify</entry>
      <entry><emphasis>request</emphasis></entry>
    </row>
  </tbody>
  </tgroup>
</informaltable>

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

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

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

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

<para><emphasis role='strong'>Canonical Representation</emphasis></para>

<para>
Every translation table has a unique, canonical text representation. This
representation is passed to a widget's
<function>display_accelerator</function>
procedure to describe the accelerators installed on that widget.
The canonical representation of a translation table is (see also
&ldquo;Syntax&rdquo;)
</para>

<informaltable frame='none'>
  <?dbfo keep-together="auto" ?>
  <tgroup cols='2' align='left' colsep='0' rowsep='0'>
  <colspec colwidth='0.2*' colname='c1'/>
  <colspec colwidth='1.0*' colname='c2'/>
  <tbody>
    <row>
      <entry>translationTable</entry>
      <entry>= { production }
      </entry>
    </row>
    <row>
      <entry>production</entry>
      <entry>= lhs &ldquo;:&rdquo; rhs &ldquo;\\n&rdquo;
      </entry>
    </row>
    <row>
      <entry>lhs</entry>
      <entry>=event { &ldquo;,&rdquo; event }
      </entry>
    </row>
    <row>
      <entry>event</entry>
      <entry>=[modifier_list] &ldquo;&lt;&rdquo;event_type&ldquo;&gt;&rdquo; [ &ldquo;(&rdquo; count[&ldquo;+&rdquo;] &ldquo;)&rdquo; ] {detail}
      </entry>
    </row>
    <row>
      <entry>modifier_list</entry>
      <entry>= [&ldquo;!&rdquo;] [&ldquo;:&rdquo;] {modifier}
      </entry>
    </row>
    <row>
      <entry>modifier</entry>
      <entry>= [&ldquo;~&rdquo;] modifier_name
      </entry>
    </row>
    <row>
      <entry>count</entry>
      <entry>=(&ldquo;1&rdquo; | &ldquo;2&rdquo; | &ldquo;3&rdquo; | &ldquo;4&rdquo; | ...)
      </entry>
    </row>
    <row>
      <entry>modifier_name</entry>
      <entry>= &ldquo;@&rdquo; &lt;keysym&gt; | &lt;see canonical modifier names below&gt;
      </entry>
    </row>
    <row>
      <entry>event_type</entry>
      <entry>= &lt;see canonical event types below&gt;
      </entry>
    </row>
    <row>
      <entry>detail</entry>
      <entry>=&lt;event-specific details&gt;
      </entry>
    </row>
    <row>
      <entry>rhs</entry>
      <entry>={ name &ldquo;(&rdquo; [params] &ldquo;)&rdquo; }
      </entry>
    </row>
    <row>
      <entry>name</entry>
      <entry>=namechar { namechar }
      </entry>
    </row>
    <row>
      <entry>namechar</entry>
      <entry>= { &ldquo;a&rdquo;&ndash;&ldquo;z&rdquo; | &ldquo;A&rdquo;&ndash;&ldquo;Z&rdquo; | &ldquo;0&rdquo;&ndash;&ldquo;9&rdquo; | &ldquo;_&rdquo; | &ldquo;-&rdquo; }
      </entry>
    </row>
    <row>
      <entry>params</entry>
      <entry>=string {&ldquo;,&rdquo; string}
      </entry>
    </row>
    <row>
      <entry>string</entry>
      <entry>=quoted_string
      </entry>
    </row>
    <row>
      <entry>quoted_string</entry>
      <entry>= <quote>"</quote> {&lt;Latin 1 character&gt; | escape_char} [&ldquo;\\"&rdquo; ] <quote>"</quote>
      </entry>
    </row>
    <row>
      <entry>escape_char</entry>
      <entry>= &ldquo;\\"&rdquo;
      </entry>
    </row>
  </tbody>
  </tgroup>
</informaltable>

<para>The canonical modifier names are</para>

<programlisting>
     Ctrl     Mod1         Button1
     Shift    Mod2         Button2
     Lock     Mod3         Button3
     Mod4     Button4
     Mod5     Button5
</programlisting>

<para>The canonical event types are</para>

<informaltable frame='none'>
  <?dbfo keep-together="auto" ?>
  <tgroup cols='2' align='left' colsep='0' rowsep='0'>
  <colspec colwidth='1.0*' colname='c1'/>
  <colspec colwidth='1.0*' colname='c2'/>
  <tbody>
    <row>
      <entry>KeyPress</entry>
      <entry>KeyRelease</entry>
    </row>
    <row>
      <entry>ButtonPress</entry>
      <entry>ButtonRelease</entry>
    </row>
    <row>
      <entry>MotionNotify</entry>
      <entry>EnterNotify</entry>
    </row>
    <row>
      <entry>LeaveNotify</entry>
      <entry>FocusIn</entry>
    </row>
    <row>
      <entry>FocusOut</entry>
      <entry>KeymapNotify</entry>
    </row>
    <row>
      <entry>Expose</entry>
      <entry>GraphicsExpose,</entry>
    </row>
    <row>
      <entry>NoExpose</entry>
      <entry>VisibilityNotify</entry>
    </row>
    <row>
      <entry>CreateNotify</entry>
      <entry>DestroyNotify</entry>
    </row>
    <row>
      <entry>UnmapNotify</entry>
      <entry>MapNotify</entry>
    </row>
    <row>
      <entry>MapRequest</entry>
      <entry>ReparentNotify</entry>
    </row>
    <row>
      <entry>ConfigureNotify</entry>
      <entry>ConfigureRequest</entry>
    </row>
    <row>
      <entry>GravityNotify</entry>
      <entry>ResizeRequest</entry>
    </row>
    <row>
      <entry>CirculateNotify</entry>
      <entry>CirculateRequest</entry>
    </row>
    <row>
      <entry>PropertyNotify</entry>
      <entry>SelectionClear</entry>
    </row>
    <row>
      <entry>SelectionRequest</entry>
      <entry>SelectionNotify</entry>
    </row>
    <row>
      <entry>ColormapNotify</entry>
      <entry>ClientMessage</entry>
    </row>
  </tbody>
  </tgroup>
</informaltable>

<para><emphasis role='strong'>Examples</emphasis></para>

<itemizedlist spacing='compact'>
  <listitem>
    <para>
Always put more specific events in the table before more general ones:
    </para>
<programlisting>
    Shift &lt;Btn1Down&gt; : twas()\n\
    &lt;Btn1Down&gt; : brillig()
</programlisting>
  </listitem>
  <listitem>
    <para>
For double-click on Button1 Up with Shift, use this specification:
    </para>
<programlisting>
Shift&lt;Btn1Up&gt;(2) : and()
</programlisting>
  </listitem>
  <listitem>
    <para>
This is equivalent to the following line with appropriate timers set
between events:
    </para>
<programlisting>
Shift&lt;Btn1Down&gt;,Shift&lt;Btn1Up&gt;,Shift&lt;Btn1Down&gt;,Shift&lt;Btn1Up&gt; : and()
</programlisting>
  </listitem>
  <listitem>
    <para>
For double-click on Button1 Down with Shift, use this specification:
    </para>
<programlisting>
Shift&lt;Btn1Down&gt;(2) : the()
</programlisting>
  </listitem>
  <listitem>
    <para>
This is equivalent to the following line with appropriate timers set
between events:
    </para>
<programlisting>
Shift&lt;Btn1Down&gt;,Shift&lt;Btn1Up&gt;,Shift&lt;Btn1Down&gt; : the()
</programlisting>
  </listitem>
  <listitem>
    <para>
Mouse motion is always discarded when it occurs between events in a table
where no motion event is specified:
    </para>
<programlisting>
&lt;Btn1Down&gt;,&lt;Btn1Up&gt; : slithy()
</programlisting>
    <para>
This is taken, even if the pointer moves a bit between the down and
up events.
Similarly, any motion event specified in a translation matches any number
of motion events.
If the motion event causes an action procedure to be invoked,
the procedure is invoked after each motion event.
    </para>
  </listitem>
  <listitem>
    <para>
If an event sequence consists of a sequence of events that is also a
noninitial subsequence of another translation,
it is not taken if it occurs in the context of the longer sequence.
This occurs mostly in sequences like the following:
    </para>
<programlisting>
&lt;Btn1Down&gt;,&lt;Btn1Up&gt; : toves()\n\
&lt;Btn1Up&gt; :  did()
</programlisting>
    <para>
The second translation is taken only if the button release is not
preceded by a button press or if there are intervening events between the
press and the release.
Be particularly aware of this when using the repeat notation, above,
with buttons and keys,
because their expansion includes additional events;
and when specifying motion events, because they are implicitly included
between any two other events.
In particular,
pointer motion and double-click translations cannot coexist in the same
translation table.
    </para>
  </listitem>
  <listitem>
    <para>
For single click on Button1 Up with Shift and Meta, use this specification:
    </para>
  </listitem>
  <listitem>
<programlisting>
Shift Meta &lt;Btn1Down&gt;, Shift Meta&lt;Btn1Up&gt;: gyre()
</programlisting>
  </listitem>
  <listitem>
    <para>
For multiple clicks greater or equal to a minimum number,
a plus sign (+) may be appended to the final (rightmost)
count in an event sequence.  The actions will be invoked
on the <emphasis remap='I'>count</emphasis>-th click and each subsequent one arriving
within the multi-click time interval.  For example:
    </para>
<programlisting>
Shift &lt;Btn1Up&gt;(2+) : and()
</programlisting>
  </listitem>
  <listitem>
    <para>
To indicate
<function>EnterNotify</function>
with any modifiers, use this specification:
    </para>
<programlisting>
&lt;Enter&gt; : gimble()
</programlisting>
  </listitem>
  <listitem>
    <para>
To indicate
<function>EnterNotify</function>
with no modifiers, use this specification:
    </para>
<programlisting>
None &lt;Enter&gt; : in()
</programlisting>
  </listitem>
  <listitem>
    <para>
To indicate
<function>EnterNotify</function>
with Button1 Down and Button2 Up and &ldquo;don't care&rdquo; about
the other modifiers, use this specification:
    </para>
<programlisting>
Button1 ~Button2 &lt;Enter&gt; : the()
</programlisting>
  </listitem>
  <listitem>
    <para>
To indicate
<function>EnterNotify</function>
with Button1 down and Button2 down exclusively, use this specification:
    </para>
<programlisting>
! Button1 Button2 &lt;Enter&gt; : wabe()
</programlisting>
    <para>
You do not need to use a tilde (~) with an exclamation point (!).
    </para>
  </listitem>
</itemizedlist>
</appendix>