.\" $Xorg: appB,v 1.3 2000/08/17 19:42:48 cpqbld Exp $ .\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994 .\" X Consortium .\" .\" Permission is hereby granted, free of charge, to any person obtaining .\" a copy of this software and associated documentation files (the .\" "Software"), to deal in the Software without restriction, including .\" without limitation the rights to use, copy, modify, merge, publish, .\" distribute, sublicense, and/or sell copies of the Software, and to .\" permit persons to whom the Software is furnished to do so, subject to .\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included .\" in all copies or substantial portions of the Software. .\" .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. .\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR .\" OTHER DEALINGS IN THE SOFTWARE. .\" .\" Except as contained in this notice, the name of the X Consortium shall .\" not be used in advertising or otherwise to promote the sale, use or .\" other dealings in this Software without prior written authorization .\" from the X Consortium. .\" .\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994 .\" Digital Equipment Corporation, Maynard, Massachusetts. .\" .\" Permission to use, copy, modify and distribute this documentation for any .\" purpose and without fee is hereby granted, provided that the above copyright .\" notice appears in all copies and that both that copyright notice and this .\" permission notice appear in supporting documentation, and that the name of .\" Digital not be used in in advertising or publicity pertaining .\" to distribution of the software without specific, written prior permission. .\" Digital makes no representations about the suitability of the .\" software described herein for any purpose. .\" It is provided ``as is'' without express or implied warranty. .\" .bp \& .sp 1 .ce 3 \s+1\fBAppendix B\fP\s-1 \s+1\fBTranslation Table Syntax\fP\s-1 .sp 2 .LP .XS \fBAppendix B \(em Translation Table Syntax\fP .XE .IN "Translation tables" .SH Notation .LP Syntax is specified in EBNF notation with the following conventions: .TS l l. [ a ] Means either nothing or ``a'' { a } Means zero or more occurrences of ``a'' ( a | b ) Means either ``a'' or ``b'' \\\\n Is the newline character .TE .LP All terminals are enclosed in double quotation marks (`` ''). Informal descriptions are enclosed in angle brackets (< >). .SH Syntax .LP The syntax of a translation table is .TS l l . translationTable = [ directive ] { production } directive = ( ``#replace'' | ``#override'' | ``#augment'' ) ``\\\\n'' production = lhs ``:'' rhs ``\\\\n'' lhs = ( event | keyseq ) { ``,'' (event | keyseq) } keyseq = ``"'' keychar {keychar} ``"'' keychar = [ ``^'' | ``$'' | ``\\\\'' ] event = [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail} modifier_list = ( [``!''] [``:''] {modifier} ) | ``None'' modifier = [``~''] modifier_name count = (``1'' | ``2'' | ``3'' | ``4'' | ...) modifier_name = ``@'' | event_type = detail = rhs = { name ``('' [params] ``)'' } name = namechar { namechar } namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' } params = string {``,'' string} string = quoted_string | unquoted_string quoted_string = ``"'' { | escape_char} [``\\\\\\\\'' ] ``"'' escape_char = ``\\\\"'' unquoted_string = {} .TE .LP The \fIparams\fP field is parsed into a list of .PN String values that will be passed to the named action procedure. A \fIquoted string\fP 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''. .SH Modifier Names .LP The modifier field is used to specify standard X keyboard and button modifier mask bits. Modifiers are legal on event types .PN KeyPress , .PN KeyRelease , .PN ButtonPress , .PN ButtonRelease , .PN MotionNotify , .PN EnterNotify , .PN LeaveNotify , and their abbreviations. An error is generated when a translation table that contains modifiers for any other events is parsed. .IP \(bu 5 If the modifier list has no entries and is not ``None'', it means ``don't care'' on all modifiers. .IP \(bu 5 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. .IP \(bu 5 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 ``don't care'' about any other modifiers. .IP \(bu 5 If a modifier is preceded by a tilde (~), it means that that modifier must not be asserted. .IP \(bu 5 If ``None'' is specified, it means no modifiers can be asserted. .IP \(bu 5 If a colon (:) is specified at the beginning of the modifier list, it directs the \*(xI 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 \fI\*(xP\fP, 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, ``:a'' is distinct from ``:A'', and ``:ShiftA'' is distinct from ``:A''. .IP \(bu 5 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. .IP \(bu 5 If a colon (:) is not specified, no standard modifiers are applied. Then, for example, ``A'' and ``a'' are equivalent. .LP 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: .LP .Ds 0 .TA 2.5i .ta 2.5i No modifiers: None detail Any modifiers: detail Only these modifiers: ! mod1 mod2 detail These modifiers and any others: mod1 mod2 detail .De .LP The use of ``None'' for a modifier list is identical to the use of an exclamation point with no modifers. .LP .TS H lw(1i) lw(1i) lw(3i). _ .sp 6p Modifier Abbreviation Meaning .sp 6p _ .sp 6p .R .TH Ctrl c Control modifier bit Shift s Shift modifier bit Lock l Lock modifier bit Meta m Meta key modifier Hyper h Hyper key modifier Super su Super key modifier Alt a 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 .sp 6p _ .TE .LP .IN "key modifier" 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. .LP Because it is possible to associate arbitrary KeySyms with modifiers, the set of key modifiers is extensible. The ``@'' syntax means any modifier bit whose corresponding KeyCode contains the specified KeySym name. .LP A modifier_list/KeySym combination in a translation matches a modifiers/KeyCode combination in an event in the following ways: .IP 1. 5 If a colon (:) is used, the \*(xI call the display's .PN XtKeyProc with the KeyCode and modifiers. To match, (\fImodifiers\fP & ~\fImodifiers_return\fP) must equal \fImodifier_list\fP, and \fIkeysym_return\fP must equal the given KeySym. .IP 2. 5 If (:) is not used, the \*(xI mask off all don't-care bits from the modifiers. This value must be equal to \fImodifier_list\fP. Then, for each possible combination of don't-care modifiers in the modifier list, the \*(xI call the display's .PN XtKeyProc with the KeyCode and that combination ORed with the cared-about modifier bits from the event. \fIKeysym_return\fP must match the KeySym in the translation. .SH Event Types .LP The event-type field describes XEvent types. In addition to the standard Xlib symbolic event type names, the following event type synonyms are defined: .TS H lw(1.5i) lw(3i). _ .sp 6p Type Meaning .sp 6p _ .sp 6p .TH Key T{ .PN KeyPress T} KeyDown T{ .PN KeyPress T} KeyUp T{ .PN KeyRelease T} BtnDown T{ .PN ButtonPress T} BtnUp T{ .PN ButtonRelease T} Motion T{ .PN MotionNotify T} PtrMoved T{ .PN MotionNotify T} MouseMoved T{ .PN MotionNotify T} Enter T{ .PN EnterNotify T} EnterWindow T{ .PN EnterNotify T} Leave T{ .PN LeaveNotify T} LeaveWindow T{ .PN LeaveNotify T} FocusIn T{ .PN FocusIn T} FocusOut T{ .PN FocusOut T} Keymap T{ .PN KeymapNotify T} Expose T{ .PN Expose T} GrExp T{ .PN GraphicsExpose T} NoExp T{ .PN NoExpose T} Visible T{ .PN VisibilityNotify T} Create T{ .PN CreateNotify T} Destroy T{ .PN DestroyNotify T} Unmap T{ .PN UnmapNotify T} Map T{ .PN MapNotify T} MapReq T{ .PN MapRequest T} Reparent T{ .PN ReparentNotify T} Configure T{ .PN ConfigureNotify T} ConfigureReq T{ .PN ConfigureRequest T} Grav T{ .PN GravityNotify T} ResReq T{ .PN ResizeRequest T} Circ T{ .PN CirculateNotify T} CircReq T{ .PN CirculateRequest T} Prop T{ .PN PropertyNotify T} SelClr T{ .PN SelectionClear T} SelReq T{ .PN SelectionRequest T} Select T{ .PN SelectionNotify T} Clrmap T{ .PN ColormapNotify T} Message T{ .PN ClientMessage T} Mapping T{ .PN MappingNotify T} .sp 6p _ .TE The supported abbreviations are: .TS H lw(1.5i) lw(1.25i) lw(1.75i). _ .sp 6p Abbreviation Event Type Including .sp 6p _ .sp 6p .TH .R Ctrl T{ .PN KeyPress T} with Control modifier Meta T{ .PN KeyPress T} with Meta modifier Shift T{ .PN KeyPress T} with Shift modifier Btn1Down T{ .PN ButtonPress T} with Button1 detail Btn1Up T{ .PN ButtonRelease T} with Button1 detail Btn2Down T{ .PN ButtonPress T} with Button2 detail Btn2Up T{ .PN ButtonRelease T} with Button2 detail Btn3Down T{ .PN ButtonPress T} with Button3 detail Btn3Up T{ .PN ButtonRelease T} with Button3 detail Btn4Down T{ .PN ButtonPress T} with Button4 detail Btn4Up T{ .PN ButtonRelease T} with Button4 detail Btn5Down T{ .PN ButtonPress T} with Button5 detail Btn5Up T{ .PN ButtonRelease T} with Button5 detail BtnMotion T{ .PN MotionNotify T} with any button modifier Btn1Motion T{ .PN MotionNotify T} with Button1 modifier Btn2Motion T{ .PN MotionNotify T} with Button2 modifier Btn3Motion T{ .PN MotionNotify T} with Button3 modifier Btn4Motion T{ .PN MotionNotify T} with Button4 modifier Btn5Motion T{ .PN MotionNotify T} with Button5 modifier .sp 6p _ .TE .sp .LP The detail field is event-specific and normally corresponds to the detail field of the corresponding event as described by \fI\*(xP\fP, Section 11. The detail field is supported for the following event types: .LP .TS H l l . _ .sp 6p Event Event Field .sp 6p _ .TH .sp 6p KeyPress KeySym from event \fIdetail\fP (keycode) KeyRelease KeySym from event \fIdetail\fP (keycode) ButtonPress button from event \fIdetail\fP ButtonRelease button from event \fIdetail\fP MotionNotify event \fIdetail\fP EnterNotify event \fImode\fP LeaveNotify event \fImode\fP FocusIn event \fImode\fP FocusOut event \fImode\fP PropertyNotify \fIatom\fP SelectionClear \fIselection\fP SelectionRequest \fIselection\fP SelectionNotify \fIselection\fP ClientMessage \fItype\fP MappingNotify \fIrequest\fP .sp 6p _ .TE .LP If the event type is .PN KeyPress or .PN KeyRelease , the detail field specifies a KeySym name in standard format which is matched against the event as described above, for example, A. .LP For the .PN PropertyNotify , .PN SelectionClear , .PN SelectionRequest , .PN SelectionNotify , and .PN ClientMessage events the detail field is specified as an atom name; for example, WM_PROTOCOLS. For the .PN MotionNotify , .PN EnterNotify , .PN LeaveNotify , .PN FocusIn , .PN FocusOut , and .PN MappingNotify events, either the symbolic constants as defined by \fI\*(xP\fP, Section 11, or the numeric values may be specified. .LP If no detail field is specified, then any value in the event detail is accepted as a match. .LP 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 0x21. Standard KeySym names are as defined in .Pn < X11/keysymdef.h > with the ``XK_'' prefix removed. .LP .SH Canonical Representation .LP Every translation table has a unique, canonical text representation. This representation is passed to a widget's .PN display_accelerator procedure to describe the accelerators installed on that widget. The canonical representation of a translation table is (see also ``Syntax'') .TS l l . translationTable = { production } production = lhs ``:'' rhs ``\\\\n'' lhs = event { ``,'' event } event = [modifier_list] ``<''event_type``>'' [ ``('' count[``+''] ``)'' ] {detail} modifier_list = [``!''] [``:''] {modifier} modifier = [``~''] modifier_name count = (``1'' | ``2'' | ``3'' | ``4'' | ...) modifier_name = ``@'' | event_type = detail = rhs = { name ``('' [params] ``)'' } name = namechar { namechar } namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' } params = string {``,'' string} string = quoted_string quoted_string = ``"'' { | escape_char} [``\\\\\\\\'' ] ``"'' escape_char = ``\\\\"'' .TE .LP The canonical modifier names are .LP .Ds .TA 1i 2.5i .ta 1i 2.5i Ctrl Mod1 Button1 Shift Mod2 Button2 Lock Mod3 Button3 Mod4 Button4 Mod5 Button5 .De .LP The canonical event types are .IP .TS l l. T{ .PN KeyPress T} T{ .PN KeyRelease T} T{ .PN ButtonPress T} T{ .PN ButtonRelease T} T{ .PN MotionNotify T} T{ .PN EnterNotify T} T{ .PN LeaveNotify T} T{ .PN FocusIn T} T{ .PN FocusOut T} T{ .PN KeymapNotify T} T{ .PN Expose T} T{ .PN GraphicsExpose, T} T{ .PN NoExpose T} T{ .PN VisibilityNotify T} T{ .PN CreateNotify T} T{ .PN DestroyNotify T} T{ .PN UnmapNotify T} T{ .PN MapNotify T} T{ .PN MapRequest T} T{ .PN ReparentNotify T} T{ .PN ConfigureNotify T} T{ .PN ConfigureRequest T} T{ .PN GravityNotify T} T{ .PN ResizeRequest T} T{ .PN CirculateNotify T} T{ .PN CirculateRequest T} T{ .PN PropertyNotify T} T{ .PN SelectionClear T} T{ .PN SelectionRequest T} T{ .PN SelectionNotify T} T{ .PN ColormapNotify T} T{ .PN ClientMessage T} .TE .LP .SH Examples .LP .IP \(bu 5 Always put more specific events in the table before more general ones: .LP .Ds Shift : twas()\\n\\ : brillig() .De .LP .IP \(bu 5 For double-click on Button1 Up with Shift, use this specification: .IP .Ds Shift(2) : and() .DE .IP This is equivalent to the following line with appropriate timers set between events: .IP .Ds Shift,Shift,Shift,Shift : and() .De .IP \(bu 5 For double-click on Button1 Down with Shift, use this specification: .IP .Ds Shift(2) : the() .De .IP This is equivalent to the following line with appropriate timers set between events: .IP .Ds Shift,Shift,Shift : the() .De .IP \(bu 5 Mouse motion is always discarded when it occurs between events in a table where no motion event is specified: .IP .Ds , : slithy() .De .IP 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. .IP \(bu 5 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: .IP .Ds , : toves()\\n\\ : did() .De .IP 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. .IP \(bu 5 For single click on Button1 Up with Shift and Meta, use this specification: .IP .Ds Shift Meta , Shift Meta: gyre() .De .IP \(bu 5 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 \fIcount\fP-th click and each subsequent one arriving within the multi-click time interval. For example: .IP .Ds Shift (2+) : and() .De .IP \(bu 5 To indicate .PN EnterNotify with any modifiers, use this specification: .IP .Ds : gimble() .De .IP \(bu 5 To indicate .PN EnterNotify with no modifiers, use this specification: .IP .Ds None : in() .De .IP \(bu 5 To indicate .PN EnterNotify with Button1 Down and Button2 Up and ``don't care'' about the other modifiers, use this specification: .IP .Ds Button1 ~Button2 : the() .De .IP \(bu 5 To indicate .PN EnterNotify with Button1 down and Button2 down exclusively, use this specification: .IP .Ds ! Button1 Button2 : wabe() .De .IP You do not need to use a tilde (~) with an exclamation point (!).