Win\Keyboard - Windows Keyboard Library
                    =======================================
                       File: Win\Keyboard - Update: 0.11
                    Author: J.G.Harston - Date: 03-Dec-2005


When using BBC BASIC for Windows GET and INKEY return certain top-bit-set values
for function and editing keys. However, The values returned for the function keys
are different from many other platforms running BBC BASIC. Also, some of the
values returned for some editing keys return the same values as some of the
function keys and some combinations of Shift, Control and Alt do not effect the
value returned.

The Win\Keyboard library provides functions to replace GET and INKEY that return
regular unique top-bit-set values for function and editing keys, and also returns
distinct values for keys pressed with Shift, Control and Alt.

DEFFNkbd_INKEY(time%)
=====================
If time% is negative, returns the keypressed state, as with INKEY. If time% is
zero or positive, waits a maximum of time% centiseconds and returns -1 if no key
pressed or the ASCII value of the key pressed. If function and editing keys have
not been redefined with *KEY, then they return the value listed in the Top-Bit
keycode table.

DEFFNkbd_GET
============
FNkbd_GET waits forever until a key is pressed, and then returns its ASCII value
as with FNkbd_INKEY().

Keycode Top-Bit Table
=====================
Note that some versions of Windows don't recognise the Shift, Ctrl and Alt keys
properly, particularly with the editing keys.

+--+---+----+---+---+---+---+----+----+-----+----+-----+-----+----+----+----+----+
|  | 0 | 1  | 2 | 3 | 4 | 5 |  6 |  7 |  8  |  9 |  A  |  B  |  C |  D |  E |  F |
+--+---+----+---+---+---+---+----+----+-----+----+-----+-----+----+----+----+----+
|8x|   | F1 | F2| F3| F4| F5|  F6|  F7|  F8 |  F9| F10 | F11 | F12| F13| F14| F15|
+--+---+----+---+---+---+---+----+----+-----+----+-----+-----+----+----+----+----+
|9x|   |sF1 |sF2|sF3|sF4|sF5| sF6| sF7| sF8 | sF9|sF10 |sF11 |sF12|sF13|sF14|sF15|
+--+---+----+---+---+---+---+----+----+-----+----+-----+-----+----+----+----+----+
|Ax|   |cF1 |cF2|cF3|cF4|cF5| cF6| cF7| cF8 | cF9|cF10 |cF11 |cF12|cF13|cF14|cF15|
+--+---+----+---+---+---+---+----+----+-----+----+-----+-----+----+----+----+----+
|Bx|   |aF1 |aF2|aF3|aF4|aF5| aF6| aF7| aF8 | aF9|aF10 |aF11 |aF12|aF13|aF14|aF15|
+--+---+----+---+---+---+---+----+----+-----+----+-----+-----+----+----+----+----+
|Cx|   |    |   |   |   |   | Ins| Del| Home| End| PgDn| PgUp|  <-|  ->| Dn | Up |
+--+---+----+---+---+---+---+----+----+-----+----+-----+-----+----+----+----+----+
|Dx|   |    |   |   |   |   |sIns|sDel|sHome|sEnd|sPgDn|sPgUp| s<-| s->|sDn |sUp |
+--+---+----+---+---+---+---+----+----+-----+----+-----+-----+----+----+----+----+
|Ex|   |    |   |   |   |   |cIns|cDel|cHome|cEnd|cPgDn|cPgUp| c<-| c->|cDn |cUp |
+--+---+----+---+---+---+---+----+----+-----+----+-----+-----+----+----+----+----+
|Fx|   |    |   |   |   |   |aIns|aDel|aHome|aEnd|aPgDn|aPgUp| a<-| a->|aDn |aUp |
+--+---+----+---+---+---+---+----+----+-----+----+-----+-----+----+----+----+----+
It can be seen from this table that bit5 and bit4 hold the state of Shift, Control
and Alt.

Technical Notes
===============
The library functions read the key pressed and then immediately read the state of
the Shift, Control and Alt keys. As there is a small, but finite, time between
reading the keypress and reading the state of the modifier keys there is a small
chance that the modifier key will be ignored. This can happen if keys are entered
into the keyboard buffer faster than the program reads them, as only keypresses
are buffered, not the state of the modifier keys.

This possibility only arises with the editing keys where the same raw value is
returned by INKEY/GET regardless of the modifier pressed, and Ctrl+Home/End/
PgUp/PgDn which return the same raw values as F12-F15.

In practice it is unlikely to occur as the natural way to type, for example,
Shift-End, is to hold Shift down, press and release End, and then release Shift.

See also
========
Console library in http://mdfs.net/Apps/Emulators/Tube/cZ80Tube.

Version History
===============
0.10 Mar-2005 Initial version.
0.11 Dec-2005 Documentation completed.

Disclaimer
==========
The Win\Keyboard library is provided "as-is" and is Copyright (C) J.G.Harston. No
responsibility can or will be taken for any loss, damage, etc, whatsoever through
its use. The Win\Keyboard library may be freely redistributed and used in any BBC
BASIC for Windows program. Please acknowledge its use in any documentation.