
WinCenter keyboard mapping overview
===================================

WinCenter keyboard support is handled at a very low level.  There is no
fancy emulation or translations being performed.  It simply maps an X
keysym into a PC scancode, sending both up and down events.  No attempt
is made to handle state of modifiers -- shift, Alt, dead keys, etc. --
all this work is done by NT and the applications.  This means you can
only have a one-to-one mapping of keys.  There is no way to create a
map where a single keypress sends a sequence to NT.

WinCenter keymap file usage

The keyboard layouts should be set to US for normal operations.  WinCenter
will (quietly) override this.  *Do not* set the keyboard explicitly
via the Control Panel->International app.

*However*, any International keyboard layouts must be loaded into the
system from the WinFrame CD.  If they are missing, then things will
quietly fail.  The easiest way to install them is by playing with the
International app from the console.

WinCenter finds its keymap file by the following system:

1- if the X resource WinCenter*keymapFile exists, it will use that value as
    the path to a keymap file.  this allows a user to specify a custom keymap.

    eg

    WinCenter*keymapFile: c:\users\lemke\mymap.kbd

2 - it next looks on the root window for the _NCD_KEYBOARD_TYPE
    property, which is set by NCDware v3.0 and later and specifies the
    keyboard the user has configured into the NCD.  it takes this value
    and uses the NCDKbd.txt file to find the appropriate map.  You can
    add any new mappings to the NCDKbd.txt file.

3 - if no keymap file is known, it falls back to a US layout.

For a user to make a new keymap file, they must either use the
resource, or overwrite an existing file.  the keymap files are placed
in %systemroot%\system32\WinCen.

WinCenter will tell NT keymap file being used, and automatically swap
you to that mode.  Note that you will *not* see this reflected in the
International section of the control panel.

Keymap file contents

The keymap file has several components.  It uses '#' as a comment
character, has several key variables, followed by a large array which
maps a set of X keysyms to PC scancodes.

The only variable which should need to change is the KeyboardLayout,
which describes the language to be used.  This should correspond
with an NT Keyboard Layout as set from Program Manager->Main->Control
Panel->International.  Attached is the full list of symbolic names for
international keyboards supported by WinCenter.

Creating a new international keymap file:

We've used the following tools:

- 'spy', an NT development tool that shows events, including PC
    scancodes.

- xev, which will spit out the X keysym name

Instructions for downloading files:
        ftp ftp.ncd.com
        Name: anonymous
        Password: (your email address)
        bin
        cd /pub/ncd/Archive/WinCenter/Keyboards
        get XEV.ZIP

- Appendix E of the X Window System reference manual, which
    contains the keysym names as well as the actual symbols

- any official keyboard documentation.  Cherry ships a keyboard
    info data sheet that specifies most of the data required.

Cookbook method:

The following should get you a new keymap file if you're using
an NCD PC-compatible international keyboard.

The simplest thing to do is start with a keymap file which matches the
new keyboard as closely as possible and modify it as needed.  You can
usually avoid some of the stranger problems (keypads, escapes) by using
this method.

Plug the keyboard to be mapped into the NT console.  Change the Keyboard
Layout to match the keyboard, and verify that its working properly
(the Keyboard Layout can be changed dynamically, with no reboot required.)

Start up Spy.  Under Options->Messages, clear all Messages, and turn
on only WM_KEYDOWN.  Start up Notepad.  Have Spy start snarfing messages
(the Start! button in the menubar).  Start typing at the notepad.

For each WM_KEYDOWN event, Spy should spit out a line of info.  It will be
an 8-digit hex number, the event name (WM_KEYDOWN), and two more 8-digit
hex numbers.  The PC scancode is the first 4 digits of the last (third)
set of 8 digit hex numbers.  This scancode goes in the first column of
the WinCenter keymap file.

After the scancode, the keymap file will contain a comma-separated list
(terminated by a semi-colon), of all the X keysyms that are enscribed
on the key.

example:
for a US keyboard, the key with '3' and '#' on it gives the scancode
'0004'.  the us.kbd keymap file uses the line
    0x04,           _3,                 numbersign;
to show this relationship.

Produce the scancode/symname mappings for all the keys on the keyboard.
For the majority, you will see a scancode with the first 2 digits
always 0.  For some special keys, the keypad keys and the keys between
the keypad and the main row, an extra value will be seen, which is an
escape to differentiate the key from another with the same label.

e.g, the US keyboard has two Left keys, one on the keypad, and the other
grouped with the arrow keys.  the keypad Left (KP_Left in X naming),
has scancode 004B.  the arrow Left (X name Left) has scancode 014B,
the same value with an escape.

in the us.kbd keymap file are two lines:

    0x4b,           KP_Left,            KP_4;
    0x4b|E0,        Left;

The escape to the arrow Left is specified with the '|E0'.

Any key that spits out something in the first two digits probably wants
the E0 escape added to its name.  There is one exception, the Break key,
which uses E1.

All of the escape stuff is a bit magical at this point, so you'll
probably have to experiment.  We have at least one known glitch with
the BelgianFrench keyboard and its ModeSwitch key.

Determine the official name of the keyboard being used.  Plug it into
the NCD, boot, and run 'xprop -root'.  There should be an entry for
"_NCD_KEYBOARD_TYPE(STRING)".  The value inside the quotes is what should
be placed in the left-hand side of your new entry in the NCDKbd.txt file.


Testing & Trouble Shooting:


Its easiest to test by using the resource method of specifying the keymap
file, starting up WinCenter, and just typing at the login box -- it'll
echo most keys.  You just need to restart WinCenter to see a new change.

If things act wrong, verify that the keymap file was read.  WinCenter
places a message about the keymap file used in the EventViewer, just
before the 'Starting up...' message.

Use xev to verify that the X server is spitting out the X keysym you
wanted.

On NCDs, having 'Local Dead Key Support' turned on (Setup->Input Devices)
may cause problems.


Customization:

Note:  the following is still all theory -- i haven't tested it.

For non-PC compatible keyboards, things are more complex, since you
can't see the scancodes.  However, you should be able to start with
the closest match, and add the extra keysyms so that they spit out the
appropriate scancodes.

In this way, you could take a Sun keyboard, and map keys with no PC
equivalent to do PCish things.

You should be able to take a DEC keyboard, and make the Delete key spit
out Backspace.

--------------

Symbolic names for WinCenter keyboards layouts:

    Belgian_Dutch
    Belgian_French
    Brazilian_ABNT
    British
    Bulgarian
    Canadian_English_Multilingual
    Canadian_French
    Canadian_French_Multilingual
    Croatian
    Czech
    Danish
    Dutch
    Finnish
    French
    German
    Greek
    Hungarian
    Icelandic
    Italian
    Italian_142
    Latin_American
    Norwegian
    Polish_Programmers
    Portuguese
    Romanian
    Russian
    Slovak
    Slovenian
    Spanish
    Spanish_variation
    Swedish
    Swiss_French
    Swiss_German
    Turkish_F
    Turkish_Q
    US
    US_Dvorak
    US_International



============



A keymap file for the NCD DEC style keyboard is included
in this directory: dec108.kbd
