diff options
Diffstat (limited to 'libXt/specs/appB')
| -rw-r--r-- | libXt/specs/appB | 783 |
1 files changed, 783 insertions, 0 deletions
diff --git a/libXt/specs/appB b/libXt/specs/appB new file mode 100644 index 000000000..3eb9ccc7b --- /dev/null +++ b/libXt/specs/appB @@ -0,0 +1,783 @@ +.\" $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 = [ ``^'' | ``$'' | ``\\\\'' ] <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 = {<Latin 1 character except space, tab, ``,'', ``\\\\n'', ``)''>} +.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, ``:<Key>a'' is distinct from ``:<Key>A'', +and ``:Shift<Key>A'' is distinct from ``:<Key>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, ``<Key>A'' and ``<Key>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 <event> detail +Any modifiers: <event> detail +Only these modifiers: ! mod1 mod2 <event> detail +These modifiers and any others: mod1 mod2 <event> 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 ``@'' <keysym> 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, <Key>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, <Message>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 = ``@'' <keysym> | <see canonical modifier names below> +event_type = <see canonical event types below> +detail = <event-specific details> +rhs = { name ``('' [params] ``)'' } +name = namechar { namechar } +namechar = { ``a''-``z'' | ``A''-``Z'' | ``0''-``9'' | ``_'' | ``-'' } +params = string {``,'' string} +string = quoted_string +quoted_string = ``"'' {<Latin 1 character> | 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 <Btn1Down> : twas()\\n\\ +<Btn1Down> : brillig() +.De +.LP +.IP \(bu 5 +For double-click on Button1 Up with Shift, use this specification: +.IP +.Ds +Shift<Btn1Up>(2) : and() +.DE +.IP +This is equivalent to the following line with appropriate timers set +between events: +.IP +.Ds +Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down>,Shift<Btn1Up> : and() +.De +.IP \(bu 5 +For double-click on Button1 Down with Shift, use this specification: +.IP +.Ds +Shift<Btn1Down>(2) : the() +.De +.IP +This is equivalent to the following line with appropriate timers set +between events: +.IP +.Ds +Shift<Btn1Down>,Shift<Btn1Up>,Shift<Btn1Down> : 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 +<Btn1Down>,<Btn1Up> : 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 +<Btn1Down>,<Btn1Up> : toves()\\n\\ +<Btn1Up> : 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 <Btn1Down>, Shift Meta<Btn1Up>: 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 <Btn1Up>(2+) : and() +.De +.IP \(bu 5 +To indicate +.PN EnterNotify +with any modifiers, use this specification: +.IP +.Ds +<Enter> : gimble() +.De +.IP \(bu 5 +To indicate +.PN EnterNotify +with no modifiers, use this specification: +.IP +.Ds +None <Enter> : 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 <Enter> : the() +.De +.IP \(bu 5 +To indicate +.PN EnterNotify +with Button1 down and Button2 down exclusively, use this specification: +.IP +.Ds +! Button1 Button2 <Enter> : wabe() +.De +.IP +You do not need to use a tilde (~) with an exclamation point (!). |