========================
"DEFKEY" by Einar Saukas
========================

DEFKEY is a generic library for reading redefinable keyboard controls.

It recognizes multiple keys pressed simultaneously, and supports redefining at
most 8 keys from the keyboard. Control keys are Q-A-O-P-M-N-1-Z by default. It
can be used in Boriel's ZX Basic or directly in Assembly.


========================
USAGE: Boriel's ZX Basic
========================

Using DEFKEY from Boriel's ZX Basic is very easy. At the beginning of your
program, you must include the library, as follows:

    #include "defkey.bas"

Inside your program, declare a variable to store current keyboard controls:

    DIM k AS UBYTE

Whenever you want to read current input from keyboard, use this function:

    LET k = readkeys()

Afterwards, whenever you want to verify if a certain direction (or one of the
fire keys) was pressed, you just need to check corresponding bits in this
variable, like this:

    IF (k & DEFKEY8) THEN
       ...
    END IF
    IF (k & DEFKEY7) THEN
       ...
    END IF

That's all!!!

By default, DEFKEY will read 8 input keys each time. If you want to reconfigure
it to read only 6 keys from keyboard for instance, use this function:

    initkeys(6)

Afterwards, you can optionally call function defkey() 6 times, in order to
redefine each one of the 6 control keys. Each call will wait until a key is
pressed, then automatically configure this key and return the selected key
code (including value 14 for SYMBOL SHIFT, 227 for CAPS SHIFT):

    FOR i = 1 TO 6
        LET k=defkey()
        ...
        PRINT CHR$(k)
    NEXT i

When DEFKEY is configured to read 5 keys, it works exactly like function 
joyKeyboard() from library JOY, returning the same sequence of bits in the same
order. Therefore it can be used as a replacement for joyKeyboard(), to serve the
same purpose except with redefinable keys.


===============
USAGE: Assembly
===============

Using DEFKEY directly from Assembly is very easy. Somewhere in your program, you
must include the library, as follows:

    include "defkey.asm"

Whenever you want to read current input from keyboard, use this routine:

    call readkeys

Afterwards, each bit of register A will be set if the corresponding key was
pressed. You can use it directly like this:

    call readkeys
    ld b,a
    and DEFKEY8
    call c, ...
    ld a,b
    and DEFKEY7
    call c, ...

Or, even better:

    call readkeys
    rrca
    call c, ... ; DEFKEY8
    rrca
    call c, ... ; DEFKEY7

That's all!!!

By default, DEFKEY will read 8 input keys each time. If you want to reconfigure
it to read only 6 keys from keyboard for instance, use this routine:

    ld a,6
    call initkeys

Afterwards, you can optionally call routine defkey 6 times, in order to redefine
each one of the 6 control keys. Each call will wait until a key is pressed, then
automatically configure this key and return the selected key code (including
value $0E for Symbol Shift, $E3 for Caps Shift):

    ld b,6
loop:
    exx
    call defkey
    rst $10
    exx
    djnz loop

When DEFKEY is configured to read 5 keys, it works exactly like routine 
joyKeyboard from library JOY, returning the same sequence of bits in the same
order. Therefore it can be used as a replacement for joyKeyboard, to serve the
same purpose except with redefinable keys.


=======
LICENSE
=======

You can freely use DEFKEY in your own programs, or implement new routines based
on it. The only condition is that, in either case, you must credit DEFKEY in
your documentation!


=======
CREDITS
=======

Created by Einar Saukas.