Appendix A

Keyboard Mapping File Format

The Keyboard Mapping file has two sections, [KEYS] and [COMPOSERS_XKK], each consisting of keysym statements and possible comments. Text entered after a ';' sign is ignored and will be treated as a comment.

A keysym specification uses a set of standard X numbers to describe a symbol. For example, a lowercase 'a' has a special number code.

The KEYS Section

In the [KEYS] section, each keysym statement associates a set of one to four keysyms with a physical key.

Synopsis of a statement is:

KEYnn = keysym1 [, keysym2 [, keysym3 [, keysym4]]]

'nn' is the identifying number of a PC's key. Every PC's key has an entry in the section. The entry name is the text KEY followed by the decimal ScanCode number (key_number) and followed by the letter 'E' if the key has the extended flag set.

keysym1 is the keysym associated with the key in a non-shifted state (Normal). This is the only parameter that must be entered.

keysym2 is the keysym associated with the key when the key is Shifted.

keysym3 is the keysym associated with the key when a Mode-Shift key is pressed (Alt-Gr).

keysym4 is the keysym associated with the Shift + Mode-Shift sequence (Shift + Alt-Gr).

A Mode-Shift is a physical key which has a keysym value of 0xFF7E, (predefined as the ModeSwitch symbol), and which is assigned to one of the modifiers MOD1 to MOD5.

A full keysym specification consists of four numbers, each of which is in the range of 0 through 255 decimal (or 0x00 through 0xFF hex). The standard predefined X keysyms use only the third and fourth numbers. The first two numbers are assumed to be zero.

WinaXe Plus accepts keysyms in the following three formats:

1. In the dotted notation, where up to four numeric components are separated by periods '.'. Each numeric component represents one of the four numbers that defines a keysym. If a component is omitted, it is assumed to be zero in the left-most position. If two components are omitted, the two left-most components are assumed to be zero, etc. For example, if you enter the numbers
   

   32.255

   two of the four possible components are omitted. The keysym will be interpreted as

   0.0.32.255

   In the dotted notation, the two lines below both represent the same keysym:

   255.0xFE

   0.0.255.0xFE

2. A single numeric value containing up to four bytes specifications. Unspecified numbers are assumed to be zeroes in the left-most position. For example:
   

   0xFF20

   represents the values 0xFF and 0x20. The keysym is interpreted as follows:

   0.0.0xFF.0x20

   Predefined symbols can be used instead of the keysym formats described above. The following three symbols are predefined:

   ModeSwitch0xFF7E

   VoidSymbol0xFFFFFF

   NoSymbol0

   You can get a full list of X-keys via the xmodmap utility of UNIX by using the -pm and/or -pk options.

   The values of keysyms for keys may be obtained via the /usr/openwin/demo/xev X-Window's UNIX utility.

3. A keysym value can be of a composer type, i.e. the COMPxx entry exists in the [COMPOSERS_XKK] section with the keysym value 'xx'. See the [COMPOSER_XKK] section below for details of how composers work.

Examples:

[KEYS]
KEY30 = 97, 65; LATIN LETTER a / A
; KEY30 = 0x61, 0x41; (XK_a, XK_A); just the same as the previous line
KEY80E= 255.84, 255.84; cursor DOWN / cursor DOWN
; KEY80E=0xff54, 0xff54; (XK_Down, XK_Down); just the same

Examples of re-mapping

Suppose that you selected to use the us.kmf file (with XSettings) and you want to change the keyboard mapping for Up(8) and Down(2) keys of the additional keyboard and for the F1 key. You can find the following lines in the us.kmf file for them:

KEY59 = 0xffbe, 0xffbe ; (XK_F1,XK_F1)
..........
KEY72E = 0xff52, 0xff52 ; (XK_Up,XK_Up)
KEY80E = 0xff54, 0xff54 ; (XK_Down,XK_Down)

By using the xev or xmodmap -pk commands on the SUN host, you can get keysyms for all keys. For example, you choose:

Help=0xff6a;
Paste=0xffcf;
Copy=0xffcd;

If you modify the lines of the us.kmf file as follows:

KEY59 = 0xff6a, 0xff6a ; (Help,Help)
..........
KEY72E = 0xffcf, 0xffcf ; (Paste,Paste)
KEY80E = 0xffcd, 0xffcd ; (Copy,Copy)

you will emulate the "Help" (F1), "Copy" ("Down") and "Paste" ("Up") functions of the SUN keyboard.

Another example of keyboard mapping

Suppose that you use the us.kmf file and you want some keys of your keyboard to map to the SUN one. You can find the following lines in the us.kmf file:

KEY59 = 0xffbe, 0xffbe ; (XK_F1,XK_F1)
KEY60 = 0xffbf, 0xffbf ; (XK_F2,XK_F2)
KEY61 = 0xffc0, 0xffc0 ; (XK_F3,XK_F3)
KEY62 = 0xffc1, 0xffc1 ; (XK_F4,XK_F4)
KEY63 = 0xffc2, 0xffc2 ; (XK_F5,XK_F5)
KEY64 = 0xffc3, 0xffc3 ; (XK_F6,XK_F6)
KEY65 = 0xffc4, 0xffc4 ; (XK_F7,XK_F7)
KEY66 = 0xffc5, 0xffc5 ; (XK_F8,XK_F8)
KEY67 = 0xffc6, 0xffc6 ; (XK_F9,XK_F9)
KEY68 = 0xffc7, 0xffc7 ; (XK_F10,XK_F10)

If you change them to:

KEY59 = 0xffc8, 0xffc8, 0xffbe ; (XK_F11,XK_F11,XK_F1)
KEY60 = 0xffc9, 0xffc9, 0xffbf ; (XK_F12,XK_F12,XK_F2)
KEY61 = 0xffca, 0xffca, 0xffc0 ; (XK_F13,XK_F13,XK_F3)
KEY62 = 0xffcb, 0xffcb, 0xffc1 ; (XK_F14,XK_F14,XK_F4)
KEY63 = 0xffcc, 0xffcc, 0xffc2 ; (XK_F15,XK_F15,XK_F5)
KEY64 = 0xffcd, 0xffcd, 0xffc3 ; (XK_F16,XK_F16,XK_F6)
KEY65 = 0xffce, 0xffce, 0xffc4 ; (XK_F17,XK_F17,XK_F7)
KEY66 = 0xffcf, 0xffcf, 0xffc5 ; (XK_F18,XK_F18,XK_F8)
KEY67 = 0xffd0, 0xffd0, 0xffc6 ; (XK_F19,XK_F19,XK_F9)
KEY68 = 0xffd1, 0xffd1, 0xffc7 ; (XK_F20,XK_F20,XK_F10)

then the following keys of your keyboard will map to keys of the SUN keyboard:

F1 => F11/Stop
F2 => F12/Again
F3 => F13/Props
F4 => F14/Undo
F5 => F15/Font
F6 => F16/Copy
F7 => F17/Open
F8 => F18/Paste
F9 => F19/Find
F10 => F20/Cut

To get codes of F1 - F10 keys, you should press them together with the Alt-Gr key.

The COMPOSERS_XKK Section

In many European languages (especially in France, Belgium and Holland), users need to enter some special characters by combining a Diacritic (or composer) character and a normal letter. For example, the user enters first the '^' sign and then the 'a' character, then this should result in the 'b' keysym.

The [KEYS] section does not determine composer characters. The Composers are only defined in the [COMPOSERS_XKK] section.

In the [COMPOSERS_XKK] section, each composer statement associates a set of key_ number map pairings with a keysym value.

Synopsis of the composer statement is:

COMPxx = key_number > key_number[S] [, key_number > key_number[S] ... ]

In the composer entry, COMP is the entry name and 'xx' is a decimal keysym value for a composer key (in the range of character codes). The '>' sign defines single code mapping (from the left to the right), while a comma separates possible map pairings. The 'S' character, if exists, allows both cases for a key_number mapping pair, otherwise lower case only.

If for a keysym value 'xx' of a key (say, KEYcc), a composer entry COMPxx exists in the [COMPOSERS_XKK] section (i.e. XServer can find it there), then the 'cc' value will not be sent to the X Client (otherwise, it will).

In the composer case, XServer will save the keysym value 'xx' until the user presses the next key. If the next key (say, KEYyy) is in the COMPxx entry (like 'yy > zz' in a pair), then XServer will send the value 'zz' from the pair to the X Client. If 'yy' is not found in the COMPxx entry, then XServer will send the composer's key_number 'cc' and the second key_number 'yy'.

Note that the values 'yy' and 'zz' are in the range of character codes.

Note that if Composer is pressed twice, then XServer will send the single value 'cc' to the X Client.

Example:

[KEYS]
KEY18 = 0x65, 0x45; (XK_e, XK_E)
KEY22 = 0x75, 0x55; (XK_u, XK_U)
KEY23 = 0x69, 0x49; (XK_i, XK_I)
KEY24 = 0x6f, 0x4f; (XK_o, XK_O)
KEY30 = 0x61, 0x41; (XK_a, XK_A)
KEY41 = 94, 176; Circumflex Accent (^) / DEGREE SIGN, RING ABOVE
; KEY41 = 0x5e, 0xb0; (XK_asciicircum, XK_degree)
KEY162 = 0xe2, 0xc2; (XK_acircumflex, XK_Acircumflex)
KEY170 = 0xea, 0xca; (XK_ecircumflex, XK_Ecircumflex)
KEY174 = 0xee, 0xce; (XK_icircumflex, XK_Icircumflex)
KEY180 = 0xf4, 0xd4; (XK_ocircumflex, XK_Ocircumflex)
KEY187 = 0xfb, 0xdb; (XK_ucircumflex, XK_Ucircumflex)

[COMPOSERS_XKK]
; Definition of Circumflex Accent as a composer
COMP94=30>162S,18>170S,23>174S,24>180S,22>187S

In this example, if the user presses (normally) the key 41 which is the circumflex accent (on German keyboard), XServer will check if the keysym value 94 is found in the [COMPOSERS_XKK] section (the COMP94 entry), and if yes, then XServer will wait until the user enters the next character. If the next character is in the COMP94 entry (in our case 30), then XServer will send 162 to the X Client (both cases are allowed). If the second key_number is not found in the COMP94 entry, then XServer will send the composer's key_number (in our case 41) and the second key_number.

Two examples of the Scroll_Lock key implementation

The "Scroll_Lock" key is used to minimize the XServer window running in the FullScreen mode (if the Local ScrollLock key check box on the XSettings window is on). But some of keyboards do not have certain keys (e.g., Scroll_Lock). By the example of two files, us_ps.kmf and us_ps2.kmf, two possible solutions are considered below to implement the "Scroll_Lock" key code generation.

Note that both the files were produced from our standard us.kmf file. You can compare them to view the changes made. Of course, these are only EXAMPLES. The similar changes (of KEY60) may be made with ANY existing keyboard key.

• The us_ps.kmf file defines the "Escape" key as the COMPOSER key. So, the "Esc"+"i" key sequence will generate the Scroll_Lock key code. In this case, to generate the "simple Escape" key code, you must press the "Esc" key twice.
  
  
• The us_ps2.kmf file gives another solution - the "Shift"+"F2" key sequence will generate the Scroll_Lock key code.

Available Keyboard Mapping Files

Keyboard Filename	Keyboard
belgian.kmf	Belgian Keyboard (for 102 Keyboard)
croatian.kmf	Croatian Keyboard (for 102 Keyboard)
danish.kmf	Danish Keyboard (for 102 Keyboard)
decemfr.kmf	DEC style Keyboard Mapping for a French Keyboard
decemfrc.kmf	DEC style Keyboard Mapping for a French Canadian Keyboard
decemgr.kmf	DEC style Keyboard Mapping for a German Keyboard
decemuk.kmf	DEC style Keyboard Mapping for a U.K. 102 English Keyboard
decemus.kmf	DEC style Keyboard Mapping for a U.S. Keyboard
dutch.kmf	Dutch Keyboard (for 102 Keyboard)
dvorak.kmf	Dvorak Keyboard (for 102 Keyboard)
finnish.kmf	Finnish Keyboard (for 102 Keyboard)
frencan.kmf	French Canadian Keyboard
french.kmf	French Keyboard
german.kmf	German Keyboard
hungarn.kmf	Hungarian Keyboard
italian.kmf	Italian Keyboard
jpn106.kmf	Japanese 106 Keyboard
latinam.kmf	Latin American Keyboard
msus.kmf	Microsoft U.S. English Keyboard
norwegia.kmf	Norwegian Keyboard
polish.kmf	Polish Keyboard (for 102 Keyboard)
portugue.kmf	Portuguese Keyboard
portbraz.kmf	Portuguese (Brazilian) Keyboard
rus.kmf	Russian Keyboard (for 102 Keyboard)
rusalt.kmf	Russian Alternative Keyboard (for 102 Keyboard)
slovenia.kmf	Slovenian Keyboard (for 102 Keyboard)
spanish.kmf	Spanish Keyboard
swedish.kmf	Swedish Keyboard
swissfre.kmf	Swiss French Keyboard
swissger.kmf	Swiss German Keyboard
uk101.kmf	U.K. 101 English Keyboard
uk102.kmf	U.K. 102 English Keyboard
uk102m.kmf	U.K. 102 English Keyboard (for SWISSGER 102 Keyboard)
us.kmf	U.S. English Keyboard
userkbd.kmf	User-defined keyboard mapping