CHAPTER 5
THE KEYBOARD HANDLER (K:)

     The keyboard is a read only device and therefore the keyboard handler
     has no output functions.
     
     The keyboard handler reads the keys as ATASCII codes.  Each key is
     represented by one byte of data.  Therefore, each time a key is
     pressed the data is treated as a byte of data just as data from any
     other device is.  The only difference is that the computer must wait
     for the operator to press the keys as it reads the data.
     
     Whenever a key is pressed an IRQ interrupt is generated by the
     keyboard reading hardware.  The internal code (not ATASCII) for the
     key just pressed is then stored in CH [$02FC (764)].  The code is then
     compared with the prior key code in CH1 [$02F2 (754)].  If the code in
     CH1 is different from the code in CH, the key is accepted.  The code
     is then converted to ATASCII, and placed in the database variable
     ATACHR [$02FB (763)].  On XL and XE models, KEYDEF [$0079,2 (121)]
     points to the key-code-to-ATASCII conversion table.  (This address is
     used by the the screen handler in 400/800 models).
     
     If the code in CH1 is the same as the code in CH, the new key code
     will not be accepted unless the key debounce timer, KEYDEL [$02F1
     (753)] is 0.
     
     When CIO is told to do an input operation from the keyboard, CH is
     checked to see if a key has been pressed.  If CIO finds $FF (255) in
     CH, it waits until a key is pressed.  If CH is not $FF, a key has been
     pressed and the ATASCII code for that key is taken from ATACHR.  CH is
     then set to $FF.
     
     The data in CH is in the following format.
     
                               Key code format:
     
     
               7 6 5 4 3 2 1 0
              -----------------
              |C|S| key code  |
              -----------------
     
      C   1 = [CTRL] key is pressed
      S   1 = [SHIFT] key is pressed
     
     Anytime a key is pressed, CH is loaded with the key code.  CH will
     hold the code until the computer is commanded to read the keyboard. 
     Sometimes the computer will read a key which was pressed long ago.  If
     you want to prevent this, load CH with $FF before reading the
     keyboard.  (In BASIC use POKE 764,255.)  This will clear out any old
     key pressings.
     
     
                             Special function keys
     
     
          [CTRL][1]      screen output start/stop
          [CTRL][2]      BELL
          [CTRL][3]      Generates End-Of-File status
          [/|\]
          or
          [/]            inverse video toggle
          [CAPS LOWER]   sets lower case
          [CTRL][CAPS]   sets CTRL lock
          [SHIFT][CAPS]  sets caps lock
     
     KEYBOARD REPEAT DELAY AND RATE CONTROL
     
     On the XL and XE, KRPDEL [$02D9 (729)] determines the delay before the
     key repeat begins.  The value of this byte is the number of vertical
     blanks (1/60th second each) to delay.  KEYREP [$02DA (730)] determines
     the repeat rate in vertical blanks.
     
     KEYBOARD CLICK
     
     The keyboard click of the XL/XE is heard through the TV speaker.  The
     click may be turned off by putting $FF in NOCLIK [$02DB (731)].
     
     NON-HANDLER, NON-CIO KEYS
     
     The [OPTION], [SELECT] and [START] keys are read from the console
     switch register, CONSOL [$D01F (53279)].
     
                          The console switch register
     
                7  6  5  4  3  2  1  0
               -------------------------
      CONSOL   |0 |0 |0 |0 |SP|OP|SE|ST|
               -------------------------
                            8  4  2  1
     
     
         ST  0 = [START]
         SE  0 = [SELECT]
         OP  0 = [OPTION]
         SP  Console speaker.  set to 1 during vertical blank.
               toggleing this bit operates the speaker (which
               is heard through the TV on XL/XE models).
               This bit always reads 0
     
     The [HELP] key on XL and XE models is read from HELPFG, [$02DC (732)].
     This address is latched and must be reset to zero after being read.
     

                            The [HELP] key register
     
                 7 6 5 4 3 2 1 0
                -----------------
      HELPFG    |C S 0 H 0 0 0 H|
                -----------------
                 1 6 3 1 8 4 2 1
                 2 4 2 6
                 8 
     
     
          H  1 = [HELP] (bits 0 and 4)
          S  1 = [SHIFT]
          C  1 = [CONTROL]
     
     
     
                   Useful database variables and OS equates
     
     
     KEYDEF $0079,2     (121): key code coversion table vector (XL/XE)
     KRPDEL $02D9       (729): delay before key repeat (XL/XE)
     KEYREP $02DA       (730): key repeat rate (XL/XE)
     NOCLIK $02DB       (731): $FF turns off key click (XL/XE)
     HELPFG $02DC       (732): [HELP] key (XL/XE)
     ATACHR $02FB       (763): ATASCII Code for last key
     CH     $02FC       (764): keycode, $FF if no key has been pressed
     BRKKEY $0011        (17): break key flag, 0 = break key pressed
     SRTIMR $022B       (555): Key delay and repeat timer
     SHFLOK $02BE       (702): SHIFT/CTRL lock flag
     $00       = lower case
     $40 (64)  = upper case lock
     $80 (128) = CTRL lock
     INVFLG $02B6     (694): inverse video flag, non-zero = inverse
     CONSOL $D01F     (53279): start, select and option keys
     IRQEN  $D20E     (53774): IRQ interrupt enable
     bit 7 enables [BREAK]
     bit 6 enables other keys
     
     
                               shadow registers
     
     
     POKMSK $0010        (16): IRQEN shadow