home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / keyboard / keylib / key.doc next >
Encoding:
Text File  |  1994-05-04  |  8.7 KB  |  275 lines
  1. /****************************************************************************\
  2.  
  3.                         Selective Keyboard Handler
  4.  
  5.                   Copyright (c) 1994  Douglas Peterson
  6.  
  7. \****************************************************************************/
  8.  
  9.  
  10.    This is a set of library routines for getting keystrokes from the
  11. user.  It is written in Assembly language for use with C/C++.  It doesn't
  12. make use of any C runtime library routines and SHOULD be compatible with
  13. any ANSI C compiler.
  14.  
  15.    I've seen quite a few low level keyboard handlers in my time, but have
  16. never been fully satisfied with them.  I wanted a handler that functioned
  17. similar to BIOS, but 1) Didn't use a buffer (kept only the last pressed key),
  18. 2) Blocked out BIOS interrupts like CTRL-C, CTRL-ALT-DELETE, PRINT SCREEN,
  19. etc.., and 3) Keys weren't limited to those "scan-codes" accepted by BIOS
  20. like CTRL-ALT-SHIFT-ENTER (You really can test for this with this handler!).
  21.  
  22.    So here it is..
  23.  
  24.  
  25.    This library is hereby released into the public domain and is completely
  26. free of charges.  I cannot and will not be held liable for any problems that
  27. might occur with the coincidental use of this code.  Use at your own risk!
  28.  
  29.  
  30. NOTICE:  This is a low level keyboard handler.  It takes over interrupt
  31. vector 09h and only releases control back to the original owner when
  32. key_init(RESTORE) is called.  Make sure you do this BEFORE your program
  33. terminates and if you spawn a child process.
  34.  
  35.  
  36. /****************************************************************************\
  37.  
  38.       Revision List
  39.  
  40. \****************************************************************************/
  41.  
  42.       Version 1.00 - First release.
  43.               1.01 - Added StateTable so that the handler can mimic
  44.                       the usual sort of low level handler.
  45.                      Function key_test() altered and it's original
  46.                       function is mimicked by key_ready().
  47.  
  48.  
  49.  
  50. /****************************************************************************\
  51.  
  52.  
  53. \****************************************************************************/
  54.  
  55.    All of the low level key handlers I've seen just let you test to see
  56. if a particular key is currently pressed or released.  This one is
  57. different.  It has only a 1 word buffer that stores a special scan code
  58. representing the last combination of key presses.  It can be cleared
  59. manually and is cleared after fetching a key with key_wait() or key_check().
  60.  
  61.    As of version 1.01, you can test key presses and releases with the
  62. key_test() function.  key_test()'s original usage has been replaced by
  63. key_ready().
  64.  
  65.  
  66.    The public symbol for the buffer is KeyBuf (with an underscore), but
  67. since it is altered by the ISR, direct manipulation is not recommended.
  68. It is possible that it's value could change while you are messing with it.
  69.  
  70. For example:
  71.  
  72.    if (KeyBuf==CR) {
  73.             <------------- The ISR could change KeyBuf right here
  74.       key=KeyBuf;
  75.       ...
  76.    }
  77.  
  78.  
  79.    The structure of the buffer is:
  80.  
  81.   151413121110 9 8 7 6 5 4 3 2 1 0  <- Bit position
  82.    0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
  83.              | | | |_____________|
  84.              | | |        |________ Scan code of key
  85.              | | |_________________ SHIFT flag
  86.              | |___________________ ALT flag
  87.              |_____________________ CTRL flag
  88.  
  89.    Bits 11-15 are unused.
  90.  
  91.    There are macros defined for every possible key.  Feel free to alter
  92. them at will as some might consider the '-' character a "DASH" and some
  93. might better like "MINUS".  There are a few special definitions, they
  94. are:
  95.  
  96.    KP_ASTERISK    - Key pad asterisk (*)
  97.    KP_DASH        - Key pad dash/minus (-)
  98.    KP_PLUS        - Key pad plus (+)
  99.    KP_5           - Key pad five key (5)
  100.  
  101.    You can build on a definition in your code like:
  102.  
  103. Key Combination      C Code Example
  104. ------------------   ----------------------------------------------------
  105. CTRL-ALT-4           if (key==CTRL+ALT+_4)
  106.  
  107. SHIFT-F              case SHIFT+_F:
  108.  
  109. SHIFT-CTRL-ALT-ESC   while (key_wait()!=SHIFT+CTRL+ALT+ESC) ;
  110.  
  111. ALT-F1               case ALT+F1:
  112.  
  113. ENTER or
  114. SHIFT-ENTER or
  115. CTRL-ENTER or
  116. ALT-ENTER            if ((char)key==CR)
  117.  
  118. Q or
  119. SHIFT-Q              if ((key&0x06FF)==_Q)  NOTE: we are masking out the shift flag bit
  120.  
  121.    This can be especially usefull in case statements because you can test
  122. for the 'I' key by switching only the first 8 bits (switch ((char)key) {)
  123. and you don't have to convert to upper case or check the ALT key.
  124.  
  125.  
  126.    Lighted keys (CAPSLOCK,SCROLLLOCK,and NUMLOCK) return scan codes just
  127. like any other key, but the lights are unaffected and meaningless.
  128.  
  129.    Interrupt accessing keys like Print Screen, and Pause appear to return
  130. different codes depending on BIOS/keyboard.  They will return them like
  131. any other key, but I'm not sure that they are accurate.
  132.  
  133.  
  134.    One very odd thing I have found so far (at least on my keyboard) is that
  135. SHIFT-INS (or HOME,END,DEL,PGUP,PGDN) on the gray keys gets returned without
  136. the SHIFT flag set.  On the number pad this is not the case (7,9,1,3,0,. are
  137. considered as HOME,PGUP,END,PGDN,INS,DEL respectively).  I cannot find any
  138. explination for this at all.
  139.  
  140.  
  141. /****************************************************************************\
  142.  
  143.    KeyASCIITable[]
  144.  
  145. \****************************************************************************/
  146.  
  147.    char KeyASCIITable[128] is a character buffer that can be used to index
  148. a scan code with an ASCII character.  For instance the _A key (code 30)
  149. would be returned (KeyASCIITable[30]) as 'A'.
  150.  
  151.    This table is limited to only the basic keys as there is no ASCII
  152. character for the F1 key.  Most will return 0.  Referencing this table
  153. will cost you 128 bytes in your code and because it's fairly useless,
  154. don't use it unless you need to.
  155.  
  156.  
  157.  
  158. /****************************************************************************\
  159.  
  160.    VERSION INFO
  161.  
  162. \****************************************************************************/
  163.  
  164.    If you have a librarian like TLIB (Borland) or LIB (Microsoft) you can
  165. determine the version of this library by generating a .LST (list) file
  166. and looking at the module VERSION.  VERSION has just one public symbol
  167. which will be called _Version_X_xx, where X is the major and xx is the
  168. minor version numbers.
  169.  
  170.  
  171.  
  172. /****************************************************************************\
  173.  
  174.    FUNCTION DESCRIPTIONS
  175.  
  176. \****************************************************************************/
  177.  
  178. ----------------------------------------
  179. void key_init(int state)
  180. ----------------------------------------
  181.  
  182.       This function invokes and removes the handler.  You can initialize
  183.    and remove it as many times as you like.  If it is already installed,
  184.    calling key_init() with 1 will have no effect and vice-versa.
  185.  
  186.       Remember to remove the handler before your program exits!!
  187.  
  188.    PARAMETERS:
  189.  
  190.       state - 0 (RESTORE) to remove the handler
  191.               1 (INIT or any non-zero number) to install the handler
  192.  
  193.  
  194. ----------------------------------------
  195. void key_clear(void)
  196. ----------------------------------------
  197.  
  198.       This macro simply sets the buffer to zero.
  199.  
  200.  
  201. ----------------------------------------
  202. int key_check(void)
  203. ----------------------------------------
  204.  
  205.       This function checks the buffer for a waiting key.  It will 'fetch'
  206.    the key if one exists.
  207.  
  208.    RETURNS:
  209.  
  210.       0 - If no key available -or-
  211.       Scan-code/Flag of key waiting
  212.  
  213.  
  214. ----------------------------------------
  215. int key_ready(void)
  216. ----------------------------------------
  217.  
  218.       This function tests the buffer for a waiting key.  It does NOT
  219.    'fetch' the character.
  220.  
  221.    RETURNS:
  222.  
  223.       0 - If no key available -or-
  224.       1 - If key IS available
  225.  
  226.  
  227. ----------------------------------------
  228. int key_test(int keycode)
  229. ----------------------------------------
  230.  
  231.       This function allows you to test the press and release status of
  232.    the keys just like the usual brand of key handler.
  233.  
  234.    PARAMETERS:
  235.  
  236.       keycode - Key Scan Code to test
  237.  
  238.    RETURNS:
  239.  
  240.       0 - If key is currently released
  241.       1 - If key is currently pressed
  242.  
  243.  
  244. ----------------------------------------
  245. int key_wait(void)
  246. ----------------------------------------
  247.  
  248.       This function clears the buffer and waits until a key is pressed
  249.    before returning.
  250.  
  251.    RETURNS:
  252.  
  253.       Scan-code/Flag of key pressed
  254.  
  255.  
  256.  
  257. /****************************************************************************\
  258.  
  259. \****************************************************************************/
  260.  
  261.    If you have any questions or comments I can be reached:
  262.  
  263. Douglas Peterson
  264.  
  265. CompuServe  73014,3320
  266.  
  267.    -or-
  268.  
  269. Dust Devil BBS  (702) 796-7134
  270.  
  271.    -or-
  272.  
  273. P.O. Box 26331
  274. San Diego, CA  92196
  275.