feat: add Multikeys doc

docs/library/keys.bas.md

@@ -0,0 +1,94 @@
+# KEYS.BAS
+
+Library to check for keys being pressed. It provide functions which are
+much faster than [INKEY$](../inkey.md), take less memory and does not require
+the Sinclair ROM to be present.
+
+## Functions
+Functions provided in this library:
+
+* [GetKey](./keys/getkey.md)
+* [GetKeyScanCode](./keys/getkeyscancode.md)
+* [MultiKeys](./keys/multikeys.md)
+
+
+### Scan codes
+
+This library define some global constants named _Scan codes_ which are just
+UInteger constant.
+
+Each key has assigned a unique Scan code. The ZX Spectrum Keyboard is divided
+in 8 Rows half. Each Row half comprises 5 keys (from the left or right side of the speccy
+QWERTY keyboard).
+
+For example letters H, J, K L and ENTER belong to row half #2 (see below).
+
+It is possible, for some routines, to use more than one scan code simultaneously, with `bOR`
+operator.
+For example `KEYH bOR KEYL` means Key H and/or Key L.
+The only restriction is that both keys must be in the same Row Half.
+
+These are all the scan codes available and their values.
+```
+Scan Codes
+
+1st Keyboard ROW half
+const KEYB        AS UInteger = 07F10h
+const KEYN        AS UInteger = 07F08h
+const KEYM        AS UInteger = 07F04h
+const KEYSYMBOL   AS UInteger = 07F02h
+const KEYSPACE    AS UInteger = 07F01h
+
+2nd Keyboard ROW half
+const KEYH        AS UInteger = 0BF10h
+const KEYJ        AS UInteger = 0BF08h
+const KEYK        AS UInteger = 0BF04h
+const KEYL        AS UInteger = 0BF02h
+const KEYENTER    AS UInteger = 0BF01h
+
+REM 3rd Keyboard ROW half
+const KEYY        AS UInteger = 0DF10h
+const KEYU        AS UInteger = 0DF08h
+const KEYI        AS UInteger = 0DF04h
+const KEYO        AS UInteger = 0DF02h
+const KEYP        AS UInteger = 0DF01h
+
+REM 4th Keyboard ROW half
+const KEY6        AS UInteger = 0EF10h
+const KEY7        AS UInteger = 0EF08h
+const KEY8        AS UInteger = 0EF04h
+const KEY9        AS UInteger = 0EF02h
+const KEY0        AS UInteger = 0EF01h
+
+REM 5th Keyboard ROW half
+const KEY5        AS UInteger = 0F710h
+const KEY4        AS UInteger = 0F708h
+const KEY3        AS UInteger = 0F704h
+const KEY2        AS UInteger = 0F702h
+const KEY1        AS UInteger = 0F701h
+
+REM 6th Keyboard ROW half
+const KEYT        AS UInteger = 0FB10h
+const KEYR        AS UInteger = 0FB08h
+const KEYE        AS UInteger = 0FB04h
+const KEYW        AS UInteger = 0FB02h
+const KEYQ        AS UInteger = 0FB01h
+
+REM 7th Keyboard ROW half
+const KEYG        AS UInteger = 0FD10h
+const KEYF        AS UInteger = 0FD08h
+const KEYD        AS UInteger = 0FD04h
+const KEYS        AS UInteger = 0FD02h
+const KEYA        AS UInteger = 0FD01h
+
+REM 8th Keyboard ROW half
+const KEYV        AS UInteger = 0FE10h
+const KEYC        AS UInteger = 0FE08h
+const KEYX        AS UInteger = 0FE04h
+const KEYZ        AS UInteger = 0FE02h
+const KEYCAPS     AS UInteger = 0FE01h
+```
+
+## See Also
+
+ * [INKEY$](../inkey.md)

docs/library/keys/multikeys.md

@@ -0,0 +1,42 @@
+# MultiKeys
+
+Library: `#include <keys.bas>`
+
+Returns whether any of the given keys is being pressed.
+Unlike
+
+
+###Syntax
+`MultiKeys(KeyCode1 bOR KeyCode2 bOR ...)`
+
+Returns whether any of the given keys was pressed. If no key was pressed, returns 0.
+It's possible to check for more than one key pressed at once, and to decode
+which keys were pressed by examining the returned value.
+
+## Examples
+
+```basic
+#include <keys.bas>
+
+DO
+LOOP UNTIL MultiKeys(KEYH bOR KEYL)
+
+PAUSE 10  'Needed to allow the user to wait press 2 keys
+x = MultiKeys(KEYH bOR KEYL)
+IF x bAND KEYH PRINT "Key H was pressed"
+IF x bAND KEYL PRINT "Key L was pressed"
+
+```
+Will print whether the Key H o the Key L or both bas been pressed.
+
+Checking for 2 or more keys will work only if these keys are in the same
+"row half", that is: in the same row and in the same group of 5 keys of that
+row (the left one or the right one)
+
+### See also
+
+* [GetKey](getkey.md)
+* [GetKeyScanCode](.getkeyscancode.md)
+
+
+Back to parent page: [String library](../keys.bas.md)

src/arch/zx48k/library/keys.bas

@@ -1,6 +1,6 @@
 ' ----------------------------------------------------------------
 ' This file is released under the MIT License
-' 
+'
 ' Copyleft (k) 2008
 ' by Jose Rodriguez-Rosa (a.k.a. Boriel) <http://www.boriel.com>
 ' ----------------------------------------------------------------
@@ -15,7 +15,7 @@ REM Avoid recursive / multiple inclusion
 
 ' ----------------------------------------------------------------
 ' function GetKeys()
-' 
+'
 ' Returns:
 '     Waits for a Key press and returns ASCII Code
 ' ----------------------------------------------------------------
@@ -31,12 +31,21 @@ end function
 
 ' ----------------------------------------------------------------
 ' function MultiKeys(x as Ubyte)
-' 
+'
 ' Returns:
-'    Given the ScanCode, returns 0 if the given key(s) are not 
-'    pressed, not zero otherwise
+'    Given the ScanCode, returns 0 if none of the given key(s) are
+'    not pressed, not zero otherwise. Scancode is one of the UInteger
+'    constants defined below (KEYB, for B Key in the Keyboard, KEYSPACE
+'    for Space Bar, KEYCAPS for shift key, etc...)
+'
+'    It's possible to check for multiple keys at once using the bOR
+'    operator. eg. To check whether key H or L are being pressed (or both)
+'    use MultiKeys(KEYH | KEYL). The only restriction is that keys must
+'    be in the same row group defined below.
+'
+'    It's possible to decode which keys of a row are pressed by
+'    reading the bits of byte returned.
 '
-' Scancodes are like SC_ENTER, SC_SPACE
 ' ----------------------------------------------------------------
 function FASTCALL MultiKeys(scancode as UInteger) AS UByte
     asm
@@ -50,19 +59,22 @@ end function
 
 ' ----------------------------------------------------------------
 ' function GetKeyScanCode()
-' 
+'
 ' Returns:
-'    The pressed Key Scan Code or 0 if none
+'    The pressed Key Scan Codes or 0 if none
 '
-' Scancodes are like SC_ENTER, SC_SPACE
+' To check for more than one key pressed at once use the bOR
+' operand. i.e.
+'   IF GetKeyScanCode() = KEYL bOR KEYH THEN ...
+' will check if both keys H and L are being pressed simultaneously.
 ' ----------------------------------------------------------------
 function FASTCALL GetKeyScanCode AS UInteger
     asm
 		PROC
 		LOCAL END_KEY
 		LOCAL LOOP
-	
-		ld l, 1	
+
+		ld l, 1
 		ld a, l
 	LOOP:
 		cpl
@@ -71,7 +83,7 @@ function FASTCALL GetKeyScanCode AS UInteger
         cpl
 		and 1Fh
 		jr nz, END_KEY
-		
+
 		ld a, l
 		rla
 		ld l, a
@@ -144,4 +156,3 @@ const KEYZ        AS UInteger = 0FE02h
 const KEYCAPS     AS UInteger = 0FE01h
 
 #endif
-