home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / beehive / utilitys / chx8012b.arc / KEYBOARD.DOC < prev    next >
Text File  |  1990-07-21  |  10KB  |  193 lines
  1.                             KEYBOARD MAPPING
  2.                          CHECK REGISTER PROGRAM
  3.                           CP/M-80 Version 1.2
  4.                               August 1986
  5.                              by WoolleyWare
  6.  
  7.  
  8. Version 1.2 of the Check Register Program includes the ability to remap
  9. CONTROL keys and to define how "special" keys, such as function and/or
  10. arrow keys, should be interpreted by the program.  The use of these
  11. optional features is described in this document.
  12.  
  13. After installing the program using CHECKSIN, the CHECKS.SCR file
  14. contains screen control information, which is described in detail on
  15. pages 7 thru 9 of the Check Register Program document (v.1.0 dated June
  16. 1986 and found in the CHECKS.DOC file).  The 17th line of CHECKS.SCR
  17. defines Dloop and Inserton.  The Dloop parameter expresses CPU speed as
  18. a percentage of that for a Z80.  Inserton should be non-zero for the
  19. program to startup in insert mode when editing the Payee field.
  20.  
  21. Two additional parameters may follow Dloop and Inserton; they are
  22. _Leadin and keymap.  With these new parameters, the complete 17th line
  23. now appears as follows:
  24.  
  25.      Dloop  Inserton  _Leadin  keymap
  26.  
  27. Each parameter is defined by the presence of a decimal integer value,
  28. separated from other values by one or more spaces.  The last two
  29. parameters are optional.  If decimal values are missing for both _Leadin
  30. and keymap, they will each be set to zero.  If _Leadin is given but not
  31. keymap, then zero will be assumed for the latter.
  32.  
  33. If _Leadin is non-zero, then it will be taken to be the decimal ASCII
  34. value received as the first of a series of characters transmitted when a
  35. "special" key, such as a function key or an arrow key, is pressed.  Up
  36. to 10 special keys may be defined.  They will be described on the 18th
  37. line of CHECKS.SCR, which will be read into the _Funkey array.  Each
  38. special key may transmit up to three ASCII characters including the
  39. common first character _Leadin.  These special characters must be
  40. received by the program with less than about one-tenth second delay
  41. between each.  (Timing is controlled by Dloop.)  Once recognized, each
  42. special key will be translated as described by the 19th line of
  43. CHECKS.SCR, which will be read into the _Newkey array.  If the special
  44. characters are not recognized to be part of the _Funkey array or if they
  45. are received too slowly, then they will be used by the program without
  46. translation.
  47.  
  48. The _Funkey array may have up to 10 pairs of decimal ASCII values.  Each
  49. pair represents up to two ASCII characters to be received after _Leadin
  50. when the corresponding special key is pressed; if only one character
  51. will be transmitted by the special key, then the second value of the
  52. pair should be zero.  If less than 10 pairs are present on the 18th line
  53. of CHECKS.SCR, zero will be assigned to remaining values, indicating
  54. that they should be ignored by the program.  Each _Funkey pair has a
  55. matching _Newkey pair read from the 19th line; undefined _Newkey
  56. parameters will be set to zero.  Zero _Newkey values will be ignored by
  57. the program.  The process may be illustrated using the following
  58. examples.
  59.  
  60. Many Televideo (and similar) terminals have a row of function keys
  61. labeled F1, F2, F3, etc.  Each transmits a series of three ASCII
  62. characters beginning with SOH (which is CONTROL-A, or decimal ASCII 1)
  63. and ending with CR (which is CONTROL-M, or decimal ASCII 13).  The
  64. middle character is @ for F1, A for F2, B for F3, etc.  We will tell the
  65. program to translate these keys as indicated below:
  66.  
  67.      F1   F2   F3   F4   F5   F6   F7   F8
  68.      ^KA  ^KR  ^O   ^P   ^KO  ^KS  ^KD  ^KQ
  69.  
  70. where the carat symbol (^) indicates a CONTROL character.  Lines 17, 18,
  71. and 19 of the CHECKS.SCR file should be edited using a standard ASCII
  72. text editor such as ED or WordStar in the Non-document mode.  _Leadin
  73. will be set to decimal 1.  Notice that zero values will be assigned when
  74. no additional decimal integer values are present on a line, which
  75. permits text comments to be included without misinterpretation.  Lines
  76. 17, 18, and 19 should be entered as follows:
  77.  
  78.      100   1   1                        Dloop  Inserton  _Leadin
  79.       64  13  65  13  66  13  67  13  68  13  69  13  70  13  71  13
  80.       11  65  11  82  15   0  16   0  11  79  11  83  11  68  11  81
  81.  
  82. When the special key should be translated into a single character, the
  83. second value of the _Newkey pair must be set to zero, as illustrated.
  84.  
  85. For another example, the VT100 terminal includes arrow keys which
  86. generate ESCAPE, [, and a letter from A thru D.  These may be mapped as
  87. follows:
  88.  
  89.      Up        Down      Right     Left           Arrow key
  90.      ESC [ A   ESC [ B   ESC [ C   ESC [ D        Received characters
  91.      ^E        ^X        ^D        ^S             Translated characters
  92.  
  93. The mapping may be defined by the following for lines 17, 18, and 19 of
  94. CHECKS.SCR:
  95.  
  96.      100   1  27                        Dloop  Inserton  _Leadin
  97.       91  65  91  66  91  67  91  68    VT100 arrow keys
  98.        5   0  24   0   4   0  19   0    Program cursor controls
  99.  
  100. Notice that using the left arrow key will not transmit ^S (or XOFF) from
  101. the VT100 terminal to the computer, which might otherwise cause problems
  102. when XON-XOFF handshaking is used.  Instead, ESC [ D is received from
  103. the terminal then translated by the program into its move cursor left
  104. command, which is ^S.
  105.  
  106. Finally, VT52 arrow keys are similar, except the [ character is not
  107. present.  They may be mapped using:
  108.  
  109.      100   1  27                        Dloop  Inserton  _Leadin
  110.       65   0  66   0  67   0  68   0    VT52 arrow keys
  111.        5   0  24   0   4   0  19   0    Program cursor controls
  112.  
  113. So much for _Leadin and "special" keys.
  114.  
  115. The fourth decimal integer value on line 17, if present, defines the
  116. parameter keymap.  A non-zero value indicates that a map (or table) will
  117. be provided to redefine up to 32 CONTROL characters.  This map will
  118. consist of two lines in the CHECKS.SCR file, which will be read into the
  119. _Keymap array.  The first line maps the first 16 CONTROL characters
  120. (decimal ASCII 0 thru 15), and the second line maps the second 16
  121. (decimal ASCII 16 thru 31).  If _Leadin is zero, then the values for
  122. _Keymap must be provided on lines 18 and 19 of CHECKS.SCR; otherwise,
  123. _Keymap will be read from lines 20 and 21.
  124.  
  125. Each entry of _Keymap defines how the corresponding CONTROL character
  126. received from the keyboard should be translated before passing it to the
  127. program.  The first 16 entries correspond to ^@ (which is ASCII NUL),
  128. ^A, ^B, etc., thru ^O; the second 16 correspond to ^P thru ^Z, ^[, ^\,
  129. ^], ^^, and finally ^_.  For example, if the first three entries in
  130. _Keymap were 65, 66, and 67, then whenever ^@ was pressed, the program
  131. would convert that into an A, ^A would become B, and ^B would result in
  132. C.  Each zero value in the _Keymap array indicates that the
  133. corresponding CONTROL character should be translated into itself.
  134. Therefore, if the second three entries in _Keymap were each zero, ^C
  135. would be received as ^C, ^D as ^D, and ^E as ^E.  Notice that, except
  136. for ^@, a CONTROL character may not be mapped into ASCII NUL.  (NUL is
  137. often transmitted when the BREAK key is pressed.)
  138.  
  139. To illustrate, the Televideo 925/950 (and similar) terminals have arrow
  140. keys which transmit the following:
  141.  
  142.      Up        Down      Right     Left
  143.      ^K        ^V        ^L        ^H
  144.  
  145. It would be convenient to translate these arrow keys as follows:
  146.  
  147.      Up        Down      Right     Left           Arrow key
  148.      ^K        ^V        ^L        ^H             Received character
  149.      ^E        ^X        ^D        ^H             Translated character
  150.  
  151. The problem is that ^K and ^V are used by the Check Register Program for
  152. other commands.  To solve this problem, alternative CONTROL keys may be
  153. mapped into ^K and ^V.  For example, ^[ may be translated as ^K, and ^\
  154. as ^V.  The corresponding values for lines 17, 18, and 19 of CHECKS.SCR
  155. would be:
  156.  
  157.      100   1   0   1                    Dloop  Inserton  _Leadin  keymap
  158.        0   1   2   3   4   5   6   7   8   9  10   5   4  13  14  15
  159.       16  17  18  19  20  21  24  23  24  25  26  11  22  29  30  31
  160.  
  161. These values indicate that ^@ thru ^J should be translated into
  162. themselves, ^K becomes ^E, ^L becomes ^D, ^M thru ^U are unchanged, ^V
  163. becomes ^X, ^W thru ^Z are unchanged, ^[ becomes ^K, ^\ becomes ^V, and
  164. the remaining three are unchanged.  Notice that _Leadin is zero, so
  165. _Funkey and _Newkey values are not supplied.
  166.  
  167. For a final example, the Televideo 912/920 and the Lear Siegler ADM-31
  168. provide arrow keys which would be conveniently translated as follows:
  169.  
  170.      Up        Down      Right     Left           Arrow key
  171.      ^K        ^J        ^L        ^H             Received character
  172.      ^E        ^X        ^D        ^H             Translated character
  173.  
  174. This is similar to the previous example except that ^J (LINE FEED) is
  175. generated by the down arrow key instead of ^V.  Unfortunately, the Check
  176. Register Program uses ^J as its help command.  For this example, we will
  177. translate function key F1 into ^K and F2 into ^J using the following
  178. input on lines 17 thru 21 of the CHECKS.SCR file:
  179.  
  180.      100   1   1   1                    Dloop  Inserton  _Leadin  keymap
  181.       64  13  65  13                    _Funkey table for F1, F2
  182.       11   0  10   0                    _Newkey table for ^K, ^J
  183.        0   1   2   3   4   5   6   7   8   9  24   5   4  ^X, ^E, ^D
  184.        0                                balance translated into self
  185.  
  186. To help you determine which decimal ASCII values are transmitted by the
  187. special keys on your keyboard, a program written in Microsoft MBASIC has
  188. been provided in the ASCII.BAS file.  Its function is to display the
  189. decimal value of each character received.  This file contains standard
  190. ASCII text, so it may be displayed using TYPE or a similar command.  If
  191. necessary, it should be fairly easily converted to another dialect of
  192. BASIC or to any other language.
  193.