nanogui: Thread: Input event insertion from user apps

Hello all,

   In the (seemingly) neverending effort to improve nano-X and
the engine/drivers, we (Screen Media) have now identified what
is probably an improvement of the flexibility of input
handeling in nano-X and better features/specs for the API.
The essense of this patch is important to us, at least.

Here goes:

   We need a separate process to handle input from mouse and
keyboard.  There are several reasons; the on-screen keyboard
will deliver keyboard input outside of the linux console or
X11 system, so we need a way to feed this information directly
to nano-X.
   When implementing this code, we realised that our rapidly
changing touch driver could also be moved to the input driver
and thus make it less of a hassle to integrate it with new
versions of nano-X (the driver is very hardware centric, and
based on strange hardware and probably has no place in
mainstream Nano-X).
   When patching this part of Nano-X, we also took the liberty
to change the KEYSTROKE event structure to handle extended
character sets better, e.g. unicode.  A great deal of thought
went into trying to make it as backward compatible as possible
(but not binary compatible), full featured in terms of Unicode
support and easy to use.  I will appreciate any comments on
the proposal.  I will describe the patch in the following.

The following variables are now defined in the GR_EVENT_KEYSTROKE
event structure (others with same semantic as before not listed):

  GR_UNICODE uch;         /* 32-bit Unicode keystroke */
  unsigned int special;   /* Special keys */
  GR_CHAR ch;             /* 8-bit keystroke */
  unsigned char content;  /* What variables are valid */

OK, this seems complicated but will actually help application
developers a lot.  This is how it works:

When a keystroke event is delivered, it may contain different
kinds of information, depending on what key in what situation
was pressed.  The 'content' variable is a bit-field indicating
which of the other variables are valid, and what they contain.
The content variable indicates if the event contains:

   GR_KEYSTROKE_CONTENT_8BIT_PROPER
   GR_KEYSTROKE_CONTENT_8BIT_CTRLSEQ
   GR_KEYSTROKE_CONTENT_UNICODE_PROPER
   GR_KEYSTROKE_CONTENT_UNICODE_CTRLSEQ
   GR_KEYSTROKE_CONTENT_SPECIAL

Each of the variables 'ch' (8BIT) and 'uch' (UNICODE, 32-bit)
are either 'proper' in the sense that it is a real character,
or recognized as a control or escape sequence.  If they are
recognized as control sequences by nano-X or whoever delivered
the events to nano-X, the 'special' variable may hold a value
identifying a common key or switch or whatever that is
identified as "special" (like function keys, arrows etc.)

The reason for distinguishing between control and proper
characters would be for the benefit of applications:  Some
applications like terminal emulators may want to get the
data from the keyboard "as is", e.g. does not care if they
are proper or control sequences, while other applications
may want nano-X to decode function keys for them, while yet
others may only be interested in proper 8-bit keys.

The only backward compatibility problem that I have identified
arises when a key is pressed that has a unicode value, but no
8-bit value:  The content variable should indicate that there is
no valid 8-bit character, but an application that does not test
the content variable will read a '?' character (or other) to
indicate a "strange" character.

This is how we would like to handle the problem of unicode
input support, and I think it is a clean way to do it.  The
reason why we have not used "very high" unicode values for
the function keys and arrow keys etc. and instead uses the
'special' variable is so that we can produce an event that
says:

      1) Special key "NUMERIC-KEYBOARD-4" pressed
      2) ASCII key "4" pressed
      4) Unicode key "4" pressed

And programs that don't need the detailed information can make
use of the less detailed information automatically, e.g. test
for special keys first; none that we care about, ok then check
unicode or ascii depending on needs.

The backspace is a good example of this, its special code
will (should) uniquely identify it as "Backspace", while the
8-bit (proper) character could be ^H.

The API changes to get this implemented is the introduction
of two new functions, both using a single protocol structure
that ships the data of the event to the Nano-X server.  The
prototypes are:

void GrInjectPointerEvent(MWCOORD x, MWCOORD y,
                          int button, int visible);
void GrInjectKeyboardEvent(GR_UNICODE uch, GR_CHAR ch, int modif,
                           int special, unsigned char content);

The "visible" flag to GrInjectPointerEvent indicates if the pointer
should be visible or not; make it visible when pointer is mouse,
don't show it for touch screens.  This will be detected and
handeled on the fly in our "input server" that will also take
input from a mouse (and a standard keyboard) in addition to
touch panel and on-screen keyboard for characters.

I'm not sure if I have implemented the "visible" functionality
correctly, though; it works for me with the NULL-kbd driver, but
it seems to use a reference count system that I don't understand.
Is this for applications to decide visibility?

Also, the linux console escape sequences are not decoded like I
describe in this mail, as I want to hear your opinions first.
I have a fully working standalone program that implements the
escape sequence detection for all keys on my Linux system that
I can port as a followup to this first effort to redefine the
API if I get the GA.

This got long again, I hope some of you followed me through it
and would care to comment if I have missed anything.  The patch
is attached, it is against 0.88pre6b - I have not looked at
pre7 yet - let me know if it doesn't patch cleanly and I'll
fix it.

At the end of this mail I inlclude a relevant section from
the nano-X.h file.

NOTE: One thing to keep in mind is the modifiers and the
KEY_UP event which seems to me is not used now for the
tty driver.

Best Regards,
Morten Rolland, Screen Media

PS: I put in some comments in srvnet.c so that all the function
pointers have a comment with its protocol number - usefull when
debugging incompatible nano-X servers and clients...:-/

PPS: The nano-X binary and shared library should have some sort
identification string that is recognised by 'ident' and produce
the proper nano-X version.

PPPS: When a client first connects to the nano-X server, the
client should tell the server what version it is, and the
server should make a quick compare or table lookup and report
if the two versions are compatible, so the client can give
errors or warnings as appropriate.  I have had a little too
many versions lying around, each one designed for a different
purpose.... Not the average situation I guess but nice all the
same.  Anyway, this is for later.

--------

/* Event for a keystroke typed for the window with has focus. */
typedef struct {
  GR_EVENT_TYPE type;		/* event type */
  GR_WINDOW_ID wid;		/* window id event delived to */
  GR_WINDOW_ID subwid;		/* sub-window id (pointer was in) */
  GR_COORD rootx;		/* root window x coordinate */
  GR_COORD rooty;		/* root window y coordinate */
  GR_COORD x;			/* window x coordinate of mouse */
  GR_COORD y;			/* window y coordinate of mouse */
  int buttons;			/* current state of buttons */
  int modifiers;		/* modifiers (SHIFT, CTRL, etc) */
  GR_UNICODE uch;		/* 32-bit Unicode keystroke */
  unsigned int special;		/* Special keys */
  GR_CHAR ch;			/* 8-bit keystroke */
  unsigned char content;	/* What variables are valid */
} GR_EVENT_KEYSTROKE;

/* These are the bits of the GR_EVENT_KEYSTROKE variable 'content' */

#define GR_KEYSTROKE_CONTENT_8BIT_PROPER	0x01
#define GR_KEYSTROKE_CONTENT_8BIT_CTRLSEQ	0x02
#define GR_KEYSTROKE_CONTENT_UNICODE_PROPER	0x04
#define GR_KEYSTROKE_CONTENT_UNICODE_CTRLSEQ	0x08
#define GR_KEYSTROKE_CONTENT_SPECIAL		0x10

/*
 * The idea is to mark every keystroke event with what kind of
 * information is available in the event.  For instance, when the
 * user presses a function key, like F10 and then 'A' on the Linux
 * console, the following sequence of events should be generated:
 *
 *                          Time ====>
 *
 * ch                       ESC    [      2      1      ~      A
 * uch                      27     91     50     49     126    65
 * special                  0      0      0      0      10     0
 * content/8BIT_PROPER      0      0      0      0      0      1
 * content/8BIT_CTRLSEQ     1      1      1      1      1      0
 * content/UNICODE_PROPER   0      0      0      0      0      1
 * content/UNICODE_CTRLSEQ  1      1      1      1      1      0
 * content/SPECIAL          0      0      0      0      1      0
 *
 * special=0: GR_SPECIAL_KEY_NOSPECIAL
 * special=10: GR_SPECIAL_KEY_F10
 *
 * As can be seen here, an application that does not test the 'content'
 * variable will receive a stream of characters on the 8-bit 'ch'
 * variable.  However, when a unicode character with no 8-bit equivalent
 * is typed, we will have ch='?' and content/8BIT_PROPER = 0.
 *
 * E.g. an application that does not test the content variable may
 * produce spurious '?' for unicode characters and escape sequences
 * for function keys.
 *
 * The allready decoded and easily available information should
 * enchourage application programmers to put some simple logic into
 * programs to handle keyboard events properly (e.g. ignore a
 * key event if it is not 8-bit proper or is part of a control
 * sequence if only 8-bit characters are supported).
 */

/* These are the bits of the GR_EVENT_KEYSTROKE variable 'special' */
#define GR_SPECIAL_KEY_NOSPECIAL	0
#define GR_SPECIAL_KEY_F1		1
#define GR_SPECIAL_KEY_F2		2
#define GR_SPECIAL_KEY_F3		3
#define GR_SPECIAL_KEY_F4		4
#define GR_SPECIAL_KEY_F5		5
#define GR_SPECIAL_KEY_F6		6
#define GR_SPECIAL_KEY_F7		7
#define GR_SPECIAL_KEY_F8		8
#define GR_SPECIAL_KEY_F9		9
#define GR_SPECIAL_KEY_F10		10
#define GR_SPECIAL_KEY_F11		11
#define GR_SPECIAL_KEY_F12		12

#define GR_SPECIAL_KEY_NUM0		48
#define GR_SPECIAL_KEY_NUM1		49
#define GR_SPECIAL_KEY_NUM2		50
#define GR_SPECIAL_KEY_NUM3		51
#define GR_SPECIAL_KEY_NUM4		52
#define GR_SPECIAL_KEY_NUM5		53
#define GR_SPECIAL_KEY_NUM6		54
#define GR_SPECIAL_KEY_NUM7		55
#define GR_SPECIAL_KEY_NUM8		56
#define GR_SPECIAL_KEY_NUM9		57

#define GR_SPECIAL_KEY_NUM_PERIOD	64
#define GR_SPECIAL_KEY_NUM_ENTER	65
#define GR_SPECIAL_KEY_NUM_PLUSS	66
#define GR_SPECIAL_KEY_NUM_MINUS	67
#define GR_SPECIAL_KEY_NUM_STAR		68
#define GR_SPECIAL_KEY_NUM_SLASH	69

#define GR_SPECIAL_KEY_ESC		96
#define GR_SPECIAL_KEY_TAB		97
#define GR_SPECIAL_KEY_INSERT		98
#define GR_SPECIAL_KEY_DELETE		99
#define GR_SPECIAL_KEY_BACKSPACE	100
#define GR_SPECIAL_KEY_PAGEUP		101
#define GR_SPECIAL_KEY_PAGEDOWN		102
#define GR_SPECIAL_KEY_HOME		103
#define GR_SPECIAL_KEY_END		104
#define GR_SPECIAL_KEY_ARROW_LEFT	105
#define GR_SPECIAL_KEY_ARROW_RIGHT	106
#define GR_SPECIAL_KEY_ARROW_UP		107
#define GR_SPECIAL_KEY_ARROW_DOWN	108

: The essense of this patch is important to us, at least.

I like the idea of the patch.  I have a few issues, although
I haven't looked much at the implementation yet.

: The following variables are now defined in the GR_EVENT_KEYSTROKE
: event structure (others with same semantic as before not listed):
:
:   GR_UNICODE uch;         /* 32-bit Unicode keystroke */
:   unsigned int special;   /* Special keys */
:   GR_CHAR ch;             /* 8-bit keystroke */
:   unsigned char content;  /* What variables are valid */

Having both uch and ch probably is a good idea,
basically it allows both multiple encodings to be
returned, as you mention, letting the applications
program worry about whether it wants unicode
or not.

I'm a little worried about the "special" element though -
I think encoding function keys into a 16-bit keystroke
(using 0-255 as the local code page value and values
above 255 as our special function keys etc) would be
better, and then using the "special" value renamed as
"scancode" which returned system-dependent information
would be better.


:
:    GR_KEYSTROKE_CONTENT_8BIT_PROPER
:    GR_KEYSTROKE_CONTENT_8BIT_CTRLSEQ
:    GR_KEYSTROKE_CONTENT_UNICODE_PROPER
:    GR_KEYSTROKE_CONTENT_UNICODE_CTRLSEQ
:    GR_KEYSTROKE_CONTENT_SPECIAL

I'm not sure I like the difference between xxx_PROPER
and xxx_CTRLSEQ.  The underlying lower layer should
decode function key sequences and either deliver them
as a single "function key" or, if timeout or invalid sequence,
just spit them thru as normal  PROPER characters.  This
lets the lower layer completely control the decoding
of "sequences" into function keys, according to local
machine characteristics, like X Windows or console
/etc/termcap, for example.


: The reason for distinguishing between control and proper
: characters would be for the benefit of applications:  Some
: applications like terminal emulators may want to get the
: data from the keyboard "as is", e.g. does not care if they
: are proper or control sequences, while other applications
: may want nano-X to decode function keys for them, while yet
: others may only be interested in proper 8-bit keys.

I'd rather see a cooked/raw mode entry point for this sort of
thing, and I'm not sure even that makes sense.

: void GrInjectPointerEvent(MWCOORD x, MWCOORD y,
:                           int button, int visible);
: void GrInjectKeyboardEvent(GR_UNICODE uch, GR_CHAR ch, int modif,
:                            int special, unsigned char content);
:
: The "visible" flag to GrInjectPointerEvent indicates if the pointer
: should be visible or not; make it visible when pointer is mouse,
: don't show it for touch screens.

Remove the visible parameter.  We don't want to turn the
cursor on and off on a per-character basis, that's a completely
different API function: GrShowCursor(), GrHideCursor().

Also, the GrInjectKeyboardEvent may have to change slightly
based on the final API, but I like the idea. (Basically it should
handle the same parameters as the low-level kbd driver passes
up to the engine layer.)


:
: I'm not sure if I have implemented the "visible" functionality
: correctly, though; it works for me with the NULL-kbd driver, but
: it seems to use a reference count system that I don't understand.
: Is this for applications to decide visibility?

Yes, the reference count stuff is badly written right now, I think
I've fixed it for Microwindows.  But basically, you shouldn't
have to know the count, you just call the Hide/Show functions,
and the system does the right thing.


:
: Also, the linux console escape sequences are not decoded like I
: describe in this mail, as I want to hear your opinions first.
: I have a fully working standalone program that implements the
: escape sequence detection for all keys on my Linux system that
: I can port as a followup to this first effort to redefine the
: API if I get the GA.

I'd like to see this code stuck in the drivers/kbd_tty.c for instance,
and a separate implementation in drivers/kbd_x11.c


: NOTE: One thing to keep in mind is the modifiers and the
: KEY_UP event which seems to me is not used now for the
: tty driver.

It is important that we have knowledge of separate key
down and key ups, and also handle the pressing of shift,
alt, and ctrl keys during normal operation, even of the Linux
console.

: PPS: The nano-X binary and shared library should have some sort
: identification string that is recognised by 'ident' and produce
: the proper nano-X version.

You should add them.  Add ident to srvmain.c, I think.



:
: PPPS: When a client first connects to the nano-X server, the
: client should tell the server what version it is, and the
: server should make a quick compare or table lookup and report
: if the two versions are compatible, so the client can give
: errors or warnings as appropriate.  I have had a little too
: many versions lying around, each one designed for a different
: purpose.... Not the average situation I guess but nice all the
: same.  Anyway, this is for later.

Yes, good idea.  Perhaps we should mod the protocol
now, before it's too late.

: #define GR_SPECIAL_KEY_F1 1
: #define GR_SPECIAL_KEY_F2 2
: #define GR_SPECIAL_KEY_F3 3
[snip]

We may want to renumber these things, and we may want
more function keys, and definitely need to handle the business
of whether a control, shift, or alt is pressed at the time that the
key is pressed.  This info can be passed back in content.
I don't think "content" is a good name, though, too confusing.
"flags" would be better.

Not that you care what Win32 does, I have nonetheless
pasted in the return values for keyup and keydown messages.
It would be nice to be somewhat close to this.  If we added
an additional nUnicodeValue, and stored the 8-bit value
as well as the "virtual" function key stuff in nVirtKey, and
stored all the content flags in lKeyData, we would basically
be there.

Win32:

WM_KEYDOWN

nVirtKey = (int) wParam;    // virtual-key code
lKeyData = lParam;          // key data


The WM_KEYDOWN message is posted to the window with the keyboard focus when a
nonsystem key is pressed. A nonsystem key is a key that is pressed when the ALT
key is not pressed.

Parameters

nVirtKey

Value of wParam. Specifies the virtual-key code of the nonsystem key.

lKeyData

Value of lParam. Specifies the repeat count, scan code, extended-key flag,
context code, previous key-state flag, and transition-state flag, as shown in
the following table:

Value Description
0-15 Specifies the repeat count. The value is the number of times the keystroke
is repeated as a result of the user holding down the key.
16-23 Specifies the scan code. The value depends on the original equipment
manufacturer (OEM).
24 Specifies whether the key is an extended key, such as the right-hand ALT and
CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if
it is an extended key; otherwise, it is 0.
25-28 Reserved; do not use.
29 Specifies the context code. The value is always 0 for a WM_KEYDOWN message.
30 Specifies the previous key state. The value is 1 if the key is down before
the message is sent, or it is 0 if the key is up.
31 Specifies the transition state. The value is always 0 for a WM_KEYDOWN
message.


Regards,

Greg

Greg Haerr wrote:

> I'm a little worried about the "special" element though -
> I think encoding function keys into a 16-bit keystroke
> (using 0-255 as the local code page value and values
> above 255 as our special function keys etc) would be
> better, and then using the "special" value renamed as
> "scancode" which returned system-dependent information
> would be better.

Returning a scan code is a good idea, but we would also need
a standard way to identify typical keys like arrows, "Home",
function keys etc. in a portable way, like you say.

Originally I thought about doing this by allocating our own
unicode values somewhere far out, but this would not
make it possible to return "for you simple apps, note that
'4' was pressed - and by the way, you sophisticated apps may
want to know that it was '4' on the *numpad*."

This would be possible with the special variable.  It could
be achieved with the scan code too - but with a portability
penalty.  This is not critical to us, but personally I think
the added complexity is small enough for the applications to
enforce it for greater flexibility.

> :    GR_KEYSTROKE_CONTENT_8BIT_PROPER
> :    GR_KEYSTROKE_CONTENT_8BIT_CTRLSEQ
> :    GR_KEYSTROKE_CONTENT_UNICODE_PROPER
> :    GR_KEYSTROKE_CONTENT_UNICODE_CTRLSEQ
> :    GR_KEYSTROKE_CONTENT_SPECIAL
> 
> I'm not sure I like the difference between xxx_PROPER
> and xxx_CTRLSEQ.  The underlying lower layer should
> decode function key sequences and either deliver them
> as a single "function key" or, if timeout or invalid sequence,
> just spit them thru as normal  PROPER characters.  This
> lets the lower layer completely control the decoding
> of "sequences" into function keys, according to local
> machine characteristics, like X Windows or console
> /etc/termcap, for example.

I agree completely - and I forgot it seems to explain the most
important reason for the existence of this idea:
Backward compatibility (deliver escape sequeces) combined with
a simpler and more portable way for applications to detect
function keys! (Our widget set decodes escape sequences now).

If you feel like the API should take care of this - and not
deliver (recognized) escape sequences, then this is fine by me.

> I'd rather see a cooked/raw mode entry point for this sort of
> thing, and I'm not sure even that makes sense.

Me neither for an API, but maybe someone somewhere has a keyboard
with very strange knobs on it that has conflicting escape
sequences with the keyboard that the keyboard driver thinks it is...
This is far fetched, but if the RAW mode needs to be implemented
for reasons like this, the raw mode can't be turned on globaly.
This is on problem solved with the event tagging I proposed.

We can let the RAW problem rest for now.

> : void GrInjectPointerEvent(MWCOORD x, MWCOORD y,
> :                           int button, int visible);
> : void GrInjectKeyboardEvent(GR_UNICODE uch, GR_CHAR ch, int modif,
> :                            int special, unsigned char content);
> :
> : The "visible" flag to GrInjectPointerEvent indicates if the pointer
> : should be visible or not; make it visible when pointer is mouse,
> : don't show it for touch screens.
> 
> Remove the visible parameter.  We don't want to turn the
> cursor on and off on a per-character basis,

Character?  You mean mouse move event?  The cursor will be either
on or off (for long periodes) depending on wether the input method
is touch or mouse.  You don't want a mouse pointer when using touch,
but it is needed for mouse input.  I may actually need this function
for, uhm, a hack too... But that is another story.

> that's a completely
> different API function: GrShowCursor(), GrHideCursor().

Yes, but they are not exported by the client API right now, and I
was affraid the GrShow/HideCursor functions would have slightly
different semantics, so the easiest solution seemed to be to define
it through the new functions.

The differing semantics is, I suspect, that GrHideCursor will not
always hide the cursor (because of the reference count thing).
The semantics that I need is for the external "mouse/touch-server"
to be able to command visibility 100% - depending on input
method alone, not depending on other applications.

The implementation calls the Hide/Show functions when the
"visibility" argument changes from the previous one (from inside
the nano-X server).

> Also, the GrInjectKeyboardEvent may have to change slightly
> based on the final API, but I like the idea. (Basically it should
> handle the same parameters as the low-level kbd driver passes
> up to the engine layer.)

Yes.  We will have to keep state of the mouse buttons *as delivered*
to the applications so that the "synthetic" keyboard event will
contain the correct information.

> Yes, the reference count stuff is badly written right now, I think
> I've fixed it for Microwindows.  But basically, you shouldn't
> have to know the count, you just call the Hide/Show functions,
> and the system does the right thing.

If this means that the GrHideCursor will *always* hide it - then I
will export the Show/Hide functions from client.c and use this
instead.  If Hide may not always hide the cursor we may have to
come up with (at least) an alternative API (which may be the
"visible" flag to InjectPointer), and then make it do the right
thing at a later stage (it seems to work for my setup witht the
NULL keyboard driver).

> : Also, the linux console escape sequences are not decoded like I
> : describe in this mail, as I want to hear your opinions first.
> : I have a fully working standalone program that implements the
> : escape sequence detection for all keys on my Linux system that
> : I can port as a followup to this first effort to redefine the
> : API if I get the GA.
> 
> I'd like to see this code stuck in the drivers/kbd_tty.c for instance,
> and a separate implementation in drivers/kbd_x11.c

Yes.  Language/codepage/unicode should probably be handled at this
level as well, with the help of higer-level helper functions, since
the hardware driver knows how to interpret the native driver and
translate into unicode, and then deliver unicode (and decoded function
keys etc.)

> It is important that we have knowledge of separate key
> down and key ups, and also handle the pressing of shift,
> alt, and ctrl keys during normal operation, even of the Linux
> console.

Yes, but this may be a bigger task, and can be solved later?  We will
not need this functionality, I think.  I can try to upgrade the tty
driver first, when the API is ready.

> : PPS: The nano-X binary and shared library should have some sort
> : identification string that is recognised by 'ident' and produce
> : the proper nano-X version.
> 
> You should add them.  Add ident to srvmain.c, I think.

I think it is easier for you to do it than me making a tiny patch:

* Create a file microwin/src/version.c that looks similar to:

   /* Microwindows project by ... etc. */
   const char *microwin_version = "$info: Microwin Version 0.88pre6b $";

And then include this file from e.g. 'srvmain.c' and others:

     nano-X server (nanox/srvmain.cas you suggested)
     nano-X client library (nanox/client.c)
     Microwin libraries

> : #define GR_SPECIAL_KEY_F1 1
> : #define GR_SPECIAL_KEY_F2 2
> : #define GR_SPECIAL_KEY_F3 3
> [snip]
> 
> We may want to renumber these things, and we may want
> more function keys, and definitely need to handle the business
> of whether a control, shift, or alt is pressed at the time that the
> key is pressed.  This info can be passed back in content.

The 'modifiers' was intended for this, wasn't it?  I don't mind
putting this info into 'content', though.

> I don't think "content" is a good name, though, too confusing.
> "flags" would be better.

Agreed,

> Not that you care what Win32 does,

Well.... - Since Microwindows is is guided by this in part,
it would be smart to try find a common ground that is both
simple to use from both camps and sufficiently feature rich
since some code will be used by both (Low level keyboard driver).

> I have nonetheless
> pasted in the return values for keyup and keydown messages.
> It would be nice to be somewhat close to this.  If we added
> an additional nUnicodeValue, and stored the 8-bit value
> as well as the "virtual" function key stuff in nVirtKey, and
> stored all the content flags in lKeyData, we would basically
> be there.
> 
> Win32:
> 
> WM_KEYDOWN
> 
> nVirtKey = (int) wParam;    // virtual-key code
> lKeyData = lParam;          // key data
> 
> The WM_KEYDOWN message is posted to the window with the keyboard focus when a
> nonsystem key is pressed. A nonsystem key is a key that is pressed when the ALT
> key is not pressed.
> 
> Parameters
> 
> nVirtKey
> 
> Value of wParam. Specifies the virtual-key code of the nonsystem key.
> 
> lKeyData
> 
> Value of lParam. Specifies the repeat count, scan code, extended-key flag,
> context code, previous key-state flag, and transition-state flag, as shown in
> the following table:
> 
> Value Description
> 0-15 Specifies the repeat count. The value is the number of times the keystroke
> is repeated as a result of the user holding down the key.
> 16-23 Specifies the scan code. The value depends on the original equipment
> manufacturer (OEM).
> 24 Specifies whether the key is an extended key, such as the right-hand ALT and
> CTRL keys that appear on an enhanced 101- or 102-key keyboard. The value is 1 if
> it is an extended key; otherwise, it is 0.
> 25-28 Reserved; do not use.
> 29 Specifies the context code. The value is always 0 for a WM_KEYDOWN message.
> 30 Specifies the previous key state. The value is 1 if the key is down before
> the message is sent, or it is 0 if the key is up.
> 31 Specifies the transition state. The value is always 0 for a WM_KEYDOWN
> message.

I'm not used to this API, so I think you should guide me when I
do something stupid - but from what I understand there should be some sort
of simple mapping.

OK, how do we proceed from here?

Regards,
Morten Rolland, Screen Media