# ```char_in```

> Version: 1.0.20096.1 \
> Created On: Sun 05 Apr 2020 12:42:26 AM CEST \
> Last modified: Sun 05 Apr 2020 01:24:29 AM CEST \
> Created by: Jali <jali@orca-central.de> \
> Last modified by: Jali <jali@orca-central.de>

## About 

The ```char_in``` function is one of the built in functions in ROM. It checks, if a key is 
currently pressed, and returns the key code in Register A.

## Parameters
The ```char_in``` function is called through addresses 0xBE53 or 0x8881 and takes no
input parameters.

## Return values
It returns the key-code of the pressed key in Register A. If no keypress was detected, A is 0.
To indicate, that a key was pressed the carry-flag is also set. When no keypress was detected,
the carry flag is cleared. This allows for easy checking if a key is pressed.
If more than one key was pressed at a time, A will contain 0x52, or -if SHIFT was addionally 
pressed- 0xD2.

## Notes
Every key has a unique keycode, that identifies the key that was pressed. 
The only key without a keycode, is the shift key. If the shift-key is pressed and held with any
other key, the most significant bit is set in A, adding 0x80 to each keycode. The only key
unaffected by this, is the ON/BREAK key, which always has a keycode of 51.

|  | 0    | 1    | 2    | 3    | 4    | 5    | 6    | 7    | 8    | 9    | A    | B    | C    | D    | E    | F    |
|--| ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
|00| --   | OFF  | Q    | W    | E    | R    | T    | Y    | U    | A    | S    | D    | F    | G    | H    | J    |
|10| K    | Z    | X    | C    | V    | B    | N    | M    | ,    | CAL  | BAS  | CAPS | ANS  | TAB  | SPAC | do   |
|20| up   | left | righ | CONS | 0    | .    | +/-  | +    | RET  | L    | ;    | DEL  | 1    | 2    | 3    | -    |
|30| M+   | I    | O    | INS  | 4    | 5    | 6    | *    | RM   | P    | BS   | n!   | 7    | 8    | 9    | /    |
|40| )    | hyp  | DEG  | y^x  | Sqrt | x^2  | (    | 1/x  | MDF  | 2nd  | sin  | cos  | ln   | log  | tan  | FSE  |
|50| CCE  | ON   |      |      |      |      |      |      |      |      |      |      |      |      |      |      |

## Example

The folowing example is a simple polling routine. It runs in an endless loop, and
displays the key code, of the last key pressed, as a hex-value. Pressing ON/BREAK
will end the program gracefully.

```ASM
10;;Queries the keyboard for input and prints the resulting keycode
20         ORG     100H        ;Tell the assembler to start at addr 0x100
30START:   LD      HL,GREET    ;Load the start addr. of the banner text
40         LD      B,15H       ;The length of the string
50         LD      DE,0H       ;Start output in the top left corner
60         CALL    84CDH       ;Call str_out
70LOOP:    CALL    8881H       ;Call the char_in
80         JR      NC,LOOP     ;If no key was pressed, jump back to scan
90         CP      51H         ;Checks if the pressed key was "ON/Break"
100        RET     Z           ;If the key was "ON" end the program.          
110        LD      HL,BUF      ;Load the buffer addess
120        CALL    BTOHEX      ;Convert the byte in A into a HEX-string and store it at BUF
130        LD      B,2         ;Set the length of BUF
140        LD      DE,15H      ;Position cursor in row 0, col 22
150        CALL    84CDH       ;Print the Keycode
160        JR      LOOP        ;Retrun to the loop
170        RET                 ;End the program
180;;Convert the contents of A into a hex-string and stores the result in the buffer pointed in HL
190BTOHEX: PUSH    AF          ;Store A onto the stack for later use
200        LD      B,4         ;Init a loop for shifting the register
210LP1:    SRL     A           ;Shift the MSN down to the least significant Nibble
220        DJNZ    LP1         ;Shift again, until all 4 bits where shifted.
230        CALL    HEXDGT      ;Converts the LSN to hex
240        INC     HL          ;Point HL to the next byte in buffer
250        POP     AF          ;Retrieve the original A
260        AND     0FH         ;Cut the first digit of the hex no.
270        CALL    HEXDGT      ;Call HEXDIGIT again for the second digit.
280        LD      HL,BUF      ;Restore the buffer address
290        RET
300;;Converts the least significant nibble in A into a ASCII hex-digit and stores the result
310HEXDGT: CP      0AH         ;Check if the number is smaller than 10
320        JR      C,SKIP      ;Skip the next instruction, if it is
330        ADD     A,07H       ;If the value is >10, we need to skip the chars between '9' and 'A'
340SKIP:   ADD     A,30H       ;Converts the number into its ASCII digit
350        LD      (HL),A      ;Store the digit in the correct location.
360        RET
370GREET:  DB      'Test keyboard input: '
380BUF:    DS      2           ;Define a 2 byte buffer to store the keycode in ASCII 
390        END                 ;Mark the end of code for the assembler
```
