JInput approach

http://java.net/projects/jinput/sources/svn/content/trunk/coreAPI/src/java/net/java/games/input/Component.java?rev=247

public static final Key W           = new Key("W"); // MS 0x11 UNIX 0x077 UPPER 0x057

http://java.net/projects/jinput/sources/svn/content/trunk/plugins/linux/src/java/net/java/games/input/NativeDefinitions.java?rev=247

public static final int KEY_W = 17;

http://java.net/projects/jinput/sources/svn/content/trunk/plugins/windows/src/java/net/java/games/input/DIIdentifierMap.java?rev=247

As we discussed in the forum, I like to discuss terminology first, e.g.:
  <http://berrange.com/posts/2010/07/04/more-than-you-or-i-ever-wanted-to-know-about-virtual-keyboard-handling/>

Note: This text is X11 focused

Extracting the following from the above:
  scanCode - keymap independent code per key, same across same keyboard type
  keyCode   - keymap independent code per key, same across all keyboards - OS defined value
  keySym     - keymap *dependent* code per key, same across all keyboards - [same across OS ?]

- scanCode and keyCode are always reversible
- keySym and keyCode are reversible _if_ the keymap is known.

+++

Compared w/ NEWT's current state, and maybe even glancing at at AWT,
NEWT and AWT 'keyCode' matches the above 'keySym'
and hence depends on the keymap.

So from here on, let's name the current NEWT keyCode: keySym.

+++

If we desire to match the keymap independent keyCode definition,
we have to validate:
  A - how is this supported on the various platforms (X11, Windows, OSX, ..)
  B - how can we map keySym -> keyCode for AWT translated events
 
+++

Further more (if we acknowledge to impl. the orig keyCode definition), 
shall we replace and hence change the current keyCode semantics
- or - shall we introduce a new value, e.g. scanCode or iKeyCode (i == independent) ?

It is also unsure how keyCode - keySym events are mapped in case of 
key combinations like 'shift-ctrl-A'. As it is, I don't see a problem since we 
deliver an 'upper case A' semantic w/ keySym.

Question: Would a replacement of keySym/keyCode break applications ?
This would be true if users would already expect the symbolic key, 
e.g. a Cyrillic .. etc number.

Further more, the keySym delivered at up and down is the only available information
due to limitations of the Windows platform, only pressed deliveres the keyChar.

One of good solutions is to get all keymaps (at init stage) and search for keySym less than 255 for each keyCode. Then use result as keymap for keyCode->keySym translation for AWT events. Reverse translation is possible using c++.

> Question: Would a replacement of keySym/keyCode break applications ?
It will repair some of applications. keyCode is a code for key since first keyboard :) getKeyCode() is expected to get keyCode, getChar()/getCharCode() - to get character.

> It is also unsure how keyCode - keySym events are mapped in case of 
key combinations like 'shift-ctrl-A'. As it is, I don't see a problem since we 
deliver an 'upper case A' semantic w/ keySym.
upper/lower doesn't matter since we must choose ONE NUMBER for both : it's some magic number, not a character. Shift and Ctrl are modifier keys, keySym will be given for A.

>shall we replace and hence change the current keyCode semantics
Yes, we should repair/replace current incorrect behavior for linux platform.

>shall we introduce a new value
We CAN introduce 
getScanCode() - for keyboard scan codes
getRawCode() - for OS keyCodes
getKeySym() - for linux keySyms
but that's not required.

>Windows platform
Windows platform looks OK

(Newt-AWT-Window KeyEvent[EVENT_KEY_TYPED, code 87(0x57), char 'w' (0x77), isActionKey false, InputEvent[modifiers: 0x0, NEWTEvent[sys:false, source:jogamp.newt.driver.windows.WindowsWindow, when:1353039647580 d 1ms]]]

Newt-Standalone KeyEvent[EVENT_KEY_TYPED, code 87(0x57), char 'w' (0x77), isActionKey false, InputEvent[modifiers: 0x0, NEWTEvent[sys:false, source:jogamp.newt.driver.windows.WindowsWindow, when:1353039646094 d 0ms]]]

But when typing in a text field the actual key is 'z')

Another solution is to use first keySym (almost always latin).

Another is to use fixed keymap. (jinput approach)

Confirmed on windows, both for translated and newt events.

newt is using character instead of scanCode:
static int WmKeyDown(JNIEnv *env, jobject window, UINT wkey, WORD repCnt, BYTE scanCode, BYTE flags, BOOL system) {
...
    jkey = WindowsKeyToJavaKey(wkey);

(In reply to comment #5)
> One of good solutions is to get all keymaps (at init stage) and search for
> keySym less than 255 for each keyCode. Then use result as keymap for
> keyCode->keySym translation for AWT events. Reverse translation is possible
> using c++.

Well, we have access to the OS keyCode AFAIK.

> 
> > Question: Would a replacement of keySym/keyCode break applications ?
> It will repair some of applications. keyCode is a code for key since first
> keyboard :) getKeyCode() is expected to get keyCode, getChar()/getCharCode() -
> to get character.

I can live w/ that, and you want OS keyCode - this was more a question for other users -> open question.

> 
> > It is also unsure how keyCode - keySym events are mapped in case of 
> key combinations like 'shift-ctrl-A'. As it is, I don't see a problem since we 
> deliver an 'upper case A' semantic w/ keySym.
> upper/lower doesn't matter since we must choose ONE NUMBER for both : it's some
> magic number, not a character. Shift and Ctrl are modifier keys, keySym will be
> given for A.
Ok.

> 
> >shall we replace and hence change the current keyCode semantics
> Yes, we should repair/replace current incorrect behavior for linux platform.
> 
> >shall we introduce a new value
> We CAN introduce 
> getScanCode() - for keyboard scan codes
> getRawCode() - for OS keyCodes
> getKeySym() - for linux keySyms
> but that's not required.

Well, it seems we change NEWT-keyCode to be the real keyCode as describe above - good.

> 
> >Windows platform
> Windows platform looks OK
> 
> (Newt-AWT-Window KeyEvent[EVENT_KEY_TYPED, code 87(0x57), char 'w' (0x77),
> isActionKey false, InputEvent[modifiers: 0x0, NEWTEvent[sys:false,
> source:jogamp.newt.driver.windows.WindowsWindow, when:1353039647580 d 1ms]]]
> 
> Newt-Standalone KeyEvent[EVENT_KEY_TYPED, code 87(0x57), char 'w' (0x77),
> isActionKey false, InputEvent[modifiers: 0x0, NEWTEvent[sys:false,
> source:jogamp.newt.driver.windows.WindowsWindow, when:1353039646094 d 0ms]]]
> 
> But when typing in a text field the actual key is 'z')

Oh - great news. So you are saying that on Windows, NEWT keyCode
is already keymap independent ?
Then thats great, and removes many above questions!

Newt-Standalone

EN -> Newt-Standalone KeyEvent[EVENT_KEY_TYPED, code 87(0x57), char 'w' (0x77), isActionKey false, InputEvent[modifiers: 0x0, NEWTEvent[sys:false, source:jogamp.newt.driver.windows.WindowsWindow, when:1353102465898 d 0ms]]]

FR -> Newt-Standalone KeyEvent[EVENT_KEY_TYPED, code 90(0x5a), char 'z' (0x7a), isActionKey false, InputEvent[modifiers: 0x0, NEWTEvent[sys:false, source:jogamp.newt.driver.windows.WindowsWindow, when:1353102484011 d 0ms]]]

Newt-AWT-Window

EN -> Newt-AWT-Window KeyEvent[EVENT_KEY_TYPED, code 87(0x57), char 'w' (0x77), isActionKey false, InputEvent[modifiers: 0x0, NEWTEvent[sys:false, source:jogamp.newt.driver.windows.WindowsWindow, when:1353102690781 d 0ms]]]

FR -> Newt-AWT-Window KeyEvent[EVENT_KEY_TYPED, code 90(0x5a), char 'z' (0x7a), isActionKey false, InputEvent[modifiers: 0x0, NEWTEvent[sys:false, source:jogamp.newt.driver.windows.WindowsWindow, when:1353102707692 d 0ms]]]

Canvas-Window

Canvas-Window java.awt.event.KeyEvent[KEY_PRESSED,keyCode=87,keyText=W,keyChar='w',keyLocation=KEY_LOCATION_STANDARD,rawCode=87,primaryLevelUnicode=119,scancode=17] on canvas0

Canvas-Window java.awt.event.KeyEvent[KEY_PRESSED,keyCode=90,keyText=Z,keyChar='z',keyLocation=KEY_LOCATION_STANDARD,rawCode=90,primaryLevelUnicode=122,scancode=17] on canvas0

TEST:
Pressing "W" key ("Z" in FR layout) on different platforms with different jre

java-6-sun-1.6.0 / LINUX
java.awt.event.KeyEvent[KEY_PRESSED,keyCode=87,keyText=W,keyChar='z',keyLocation=KEY_LOCATION_STANDARD,rawCode=25,primaryLevelUnicode=119,scancode=0] on frame0
java.awt.event.KeyEvent[KEY_TYPED,keyCode=0,keyText=Unknown keyCode: 0x0,keyChar='z',keyLocation=KEY_LOCATION_UNKNOWN,rawCode=0,primaryLevelUnicode=119,scancode=0] on frame0
java.awt.event.KeyEvent[KEY_RELEASED,keyCode=87,keyText=W,keyChar='w',keyLocation=KEY_LOCATION_STANDARD,rawCode=25,primaryLevelUnicode=119,scancode=0] on frame0

java-6-openjdk / LINUX
java.awt.event.KeyEvent[KEY_PRESSED,keyCode=87,keyText=W,keyChar='w',keyLocation=KEY_LOCATION_STANDARD] on frame0
java.awt.event.KeyEvent[KEY_TYPED,keyCode=0,keyText=Unknown keyCode: 0x0,keyChar='w',keyLocation=KEY_LOCATION_UNKNOWN] on frame0
java.awt.event.KeyEvent[KEY_RELEASED,keyCode=87,keyText=W,keyChar='w',keyLocation=KEY_LOCATION_STANDARD] on frame0

java-7-openjdk-i386 / LINUX
java.awt.event.KeyEvent[KEY_PRESSED,keyCode=87,keyText=W,keyChar='z',extModifiers=Button7,keyLocation=KEY_LOCATION_STANDARD,rawCode=25,primaryLevelUnicode=122,scancode=0,extendedKeyCode=0x5a] on frame0
java.awt.event.KeyEvent[KEY_TYPED,keyCode=0,keyText=Unknown keyCode: 0x0,keyChar='z',extModifiers=Button7,keyLocation=KEY_LOCATION_UNKNOWN,rawCode=0,primaryLevelUnicode=122,scancode=0,extendedKeyCode=0x0] on frame0
java.awt.event.KeyEvent[KEY_RELEASED,keyCode=87,keyText=W,keyChar='z',extModifiers=Button7,keyLocation=KEY_LOCATION_STANDARD,rawCode=25,primaryLevelUnicode=122,scancode=0,extendedKeyCode=0x5a] on frame0

JRE 1.7 / WINDOWS
JFrame-Window java.awt.event.KeyEvent[KEY_PRESSED,keyCode=90,keyText=Z,keyChar='z',keyLocation=KEY_LOCATION_STANDARD,rawCode=90,primaryLevelUnicode=122,scancode=17,extendedKeyCode=0x5a] on frame0 Ex: 90
JFrame-Window java.awt.event.KeyEvent[KEY_TYPED,keyCode=0,keyText=Unknown keyCode: 0x0,keyChar='z',keyLocation=KEY_LOCATION_UNKNOWN,rawCode=0,primaryLevelUnicode=0,scancode=0,extendedKeyCode=0x0] on frame0
JFrame-Window java.awt.event.KeyEvent[KEY_RELEASED,keyCode=90,keyText=Z,keyChar='z',keyLocation=KEY_LOCATION_STANDARD,rawCode=90,primaryLevelUnicode=122,scancode=17,extendedKeyCode=0x5a] on frame0

JDK 1.6 / WINDOWS
JFrame-Window java.awt.event.KeyEvent[KEY_PRESSED,keyCode=90,keyText=Z,keyChar='z',keyLocation=KEY_LOCATION_STANDARD,rawCode=90,primaryLevelUnicode=122,scancode=17] on frame0
JFrame-Window java.awt.event.KeyEvent[KEY_TYPED,keyCode=0,keyText=Unknown keyCode: 0x0,keyChar='z',keyLocation=KEY_LOCATION_UNKNOWN,rawCode=0,primaryLevelUnicode=0,scancode=0] on frame0
JFrame-Window java.awt.event.KeyEvent[KEY_RELEASED,keyCode=90,keyText=Z,keyChar='z',keyLocation=KEY_LOCATION_STANDARD,rawCode=90,primaryLevelUnicode=122,scancode=17] on frame0

http://jogamp.org/git/?p=jogl.git;a=commit;h=85338858f5c58694fa88e77df1386d0556887944

TODO:
  X11 keyCode: i.e. keySym for US Keyboard
  OSX  keyCode: i.e. keySym for US Keyboard

Done: X11 and OSX .. for each a 'best practice' approach is being used.

OSX has no layout dependent keyCode to generate keySym, 
hence we create our own mapping of 1st 128 chars ..

Refine isPrintable()

Refined keySym definition, hinting to unshifted UTF16 keyCode value
for printable chars.

Use UTF-16 UniCode for key-code and key-symbol exposing well defined key encoding and simplify usage.

This concludes keyCode/keySym handling, i.e. allows a more simple implementation
for platform drivers.