home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / reference / amiga_mail_vol1 / input / interkeyio < prev    next >
Text File  |  1990-01-26  |  11KB  |  238 lines
  1. (c)  Copyright 1989 Commodore-Amiga, Inc.   All rights reserved.
  2. The information contained herein is subject to change without notice, and 
  3. is provided "as is" without warranty of any kind, either expressed or implied.  
  4. The entire risk as to the use of this information is assumed by the user.
  5.  
  6.  
  7.  
  8.                        INTERNATIONAL KEYBOARD INPUT
  9.  
  10.                     Eric Cotton and Carolyn Scheppner
  11.  
  12.  
  13.         The Amiga computers are sold internationally with a variety of
  14.      local keyboards which match the standards of particular countries.
  15.      The 1.2 Enhancer manual contains diagrams of the keyboards which
  16.      are currently distributed.  If you look at the diagrams, you will
  17.      see that some letters and special symbols are in different
  18.      physical positions on the various keyboards.  For instance, on
  19.      the German and Italian keyboards, the Y and Z keys are swapped
  20.      when compared to the USA keyboard.  Since the physical position
  21.      of a key determines the raw key code that it generates, straight
  22.      RAWKEY input is not internationally compatible.  Pressing the second
  23.      key on the fifth row will generate the same raw key code on all
  24.      Amiga keyboards, but will be decoded as a Z on a US keyboard and
  25.      as a Y on a German.
  26.  
  27.         The 1.2 Amiga console device supports national keyboards by 
  28.      providing mapping of raw key codes to the proper ASCII characters 
  29.      and strings as specified in a Keymap.  In addition, the console 
  30.      device provides handling of the "dead keys" used to generate accented 
  31.      characters.  Any keyboard input which is processed by the console
  32.      device will be automatically translated to the installed keymap.
  33.      The new 1.2 Setmap command is used to install the default keymap
  34.      to be used by the console device.  If you wish to experiment with
  35.      the national keymaps, the KeyToy program on Extras 1.2 provides
  36.      a graphic presentation of the various keyboards.
  37.      
  38.         All of the national Keymaps, including USA, contain dead keys. 
  39.      Basically, a dead key is a key that produces no output until a second
  40.      key is pressed.  Thus the dead key modifies the output of another key.
  41.      Often a dead key is used to indicate that a particular accent mark is 
  42.      to be placed on the next character typed.  The ASCII values for these 
  43.      characters are all greater than 127. They are listed in the International
  44.      Character Codes table in the AmigaDOS manual.  If a dead key is used to 
  45.      request an invalid accent for a character, the normal unaccented 
  46.      character results.
  47.  
  48.         If you look at the U.S. keyboard diagram in the Enhancer manual,
  49.      you'll see that the F, G, H, J, and K keys (shadowed) are defined 
  50.      as dead keys.  In the diagram, various accent marks are printed in 
  51.      the lower half of each of these keys.  Pressing Alt and one of these
  52.      shadowed keys is a request for the illustrated accent to be placed 
  53.      on the next character you type.
  54.  
  55.        For example, try typing these with the default usa keymap:
  56.  
  57.          ALT/F (') then A  results in an A accented with '
  58.          ALT/H (^) then E  results in an E accented with ^
  59.          ALT/J (~) then C  results in a plain C (invalid accent for C)
  60.  
  61.  
  62.         Under 1.2, the console.device, IDCMP VANILLAKEY, and AmigaDOS
  63.      CON: and RAW: all provide automatic handling of dead keys and
  64.      translation of raw keycodes to ASCII based on the current keymap.
  65.      If your software requires non-VANILLA keys such as the cursor and
  66.      function keys, using console device keyboard input in your Intuition 
  67.      window will allow you to receive the escape sequences generated
  68.      by these keys.  If you are using IDCMP RAWKEY input in international
  69.      software, you must properly use the console device's RawKeyConvert()
  70.      function to get keymap translation and dead key handling.  See the
  71.      example DeadKeyConvert() in the 1.2 Enhancer manual (P. 65) or the 
  72.      1.2 Readmes for more on this.  Use NULL for the kmap argument to get 
  73.      translation to the currently installed Keymap.
  74.  
  75.         Be sure to test your code with ASCII characters greater than 127 
  76.      such as accented characters like Alt-F-A wherever your code accepts 
  77.      keyboard input to ensure that your logic and data structures work properly 
  78.      with high ASCII values.  In addition, test your code after using 
  79.      SetMap to install various keymaps, using the Enhancer manual keyboard
  80.      diagrams as a guide for what the keycaps would show in that country.
  81.      You won't be able to test all of the keys of some national keyboards,
  82.      but you can test enough keys to be sure you are getting translation.
  83.  
  84.         The following information is a supplement to chapter 8, The Console 
  85.      Device, in the Rom Kernel Manual: Libraries and Devices, which describes 
  86.      the Keymap format and console.device handling of dead keys.  
  87.  
  88.  
  89.  
  90. Dead-Class Keys
  91.  
  92. The term "dead-class key" refers to keys that either modify or can themselves
  93. be modified by other dead-class keys.  There are two types of dead-class keys:
  94. dead and deadable.  A dead key is one which can modify the key pressed 
  95. immediately following it.  For example, in all keymaps the H key acts as a 
  96. carat ("^") dead key when pressed along with the Alt or Shift-Alt qualifiers.
  97. When followed by the A key for instance, the combination will produce the 
  98. accented character @@ (international character code $E2).  A deadable key is
  99. is one that can be pre-fixed by a dead key.  The A key in this example is a 
  100. deadable key.  Thus, a dead key can only affect the output of a deadable key.
  101.  
  102. For any key that is to have a dead-class function, whether dead or deadable,
  103. the qualifier KCF_DEAD flag must be included in the entry for the key in the
  104. KeyMapTypes table.  The KCF_DEAD type may also be used in conjunction with
  105. the other qualifiers.  Furthermore, the key's KeyMap table entry must contain
  106. the longword address of the key's dead-key descriptor data area in place of
  107. the usual 4 ASCII character mapping.
  108.  
  109.  
  110. Consider the following example KeyMap excerpt:
  111.  
  112.  
  113.             Example 1: Dead-Class Keys
  114.  
  115.     new LoKeyMapTypes:
  116.         DC.B    KCF_DEAD+KCF_SHIFT+KCF_ALT+KCF_CONTROL  ;aA (Key 20)
  117.                 ...            ;(more...)
  118.         DC.B    KCF_DEAD+KCF_SHIFT+KCF_ALT+KCF_CONTROL    ;hH (Key 25)
  119.                 ...            ;(more...)
  120.  
  121.     new LoKeyMap:
  122.         DC.L    key20            ; a, A, ae, AE
  123.                             ...                 ;(more...)
  124.         DC.L    key25            ;h, H, dead ^
  125.                 ...            ;(more...)
  126.  
  127.     ;------ possible dead keys
  128.     key25:
  129.         DC.B    0,'h',0,'H'        ;h, H
  130.         DC.B    DPF_DEAD,3,DPF_DEAD,3    ;dead ^
  131.         DC.B    0,$08,0,$08,0,$88,0,$88    ;control translation
  132.                 ...            ;(more...)
  133.  
  134.     ;------ deadable keys (modified by dead keys)
  135.     key20:
  136.         DC.B    DPF_MOD,key20u-key20    ;deadable flag, number of
  137.                         ;bytes from start of key20
  138.                         ;descriptor to start of un-
  139.                         ;shifted data
  140.  
  141.         DC.B    DPF_MOD,key20s-key20    ;deadable flag, number of
  142.                         ;bytes from start of key20
  143.                         ;descriptor to start of shift-
  144.                         ;ed data
  145.  
  146.         DC.B    0,$E6,0,$C6        ;null flags followed by rest
  147.         DC.B    0,$01,0,$01,0,$81,0,$81    ;of values (ALT, CTRL...)
  148.     key20u:
  149.         DC.B    'a',$E0,$E1,$E2,$E3,$E4    ;'a' alone and characters to
  150.                         ;output when key alone is
  151.                         ;prefixed by a dead key
  152.     key20s:
  153.         DC.B    'A',$C0,$C1,$C2,$C3,$C4    ;SHIFTed 'a' and characters to
  154.                         ;output when SHIFTed key is
  155.                         ;prefixed by a dead key
  156.  
  157.  
  158.  
  159. In the example, key 25 (the H key) is a dead key and key 20 (the A key) is
  160. a deadable key.  Both keys use the addresses of their descriptor data areas as
  161. entries in the LoKeyMap table.  The LoKeyMapTypes table says that there are
  162. four qualifiers for both: the requisite KCF_DEAD, as well as KCF_SHIFT,
  163. KCF_ALT, and KCF_CONTROL.  The number of qualifiers determine length and
  164. arrangement of the descriptor data areas for each key.  Table 1 below shows
  165. how to interpret the KeyMapTypes for various combinations of the qualifier
  166. bits.  For each possible position a pair of bytes is needed.  The first byte
  167. in each pair tells how to interpret the second byte.
  168.  
  169.  
  170.         Table 1: Dead Key Qualifier Bits
  171.  
  172. If type     Then the pair of bytes in this position in the dead-class key
  173. byte is:    descriptor data is output when the key is pressed along with:
  174.  
  175. NOQUAL        alone    -    -    -    -    -    -    -
  176. A        alone    A    -    -    -    -    -    -
  177. C        alone    C    -    -    -    -    -    -
  178. S        alone    S    -    -    -    -    -    -
  179. A+C        alone    A    C    A+C    -    -    -    -
  180. A+S        alone    S    A    A+S    -    -    -    -
  181. C+S        alone    S    C    C+S    -    -    -    -
  182. S+A+C (VANILLA)    alone    S    A    S+A    C    C+S    C+A    C+S+A
  183.  
  184.     NOTE: the abbreviations A, C, S stand for ALT, Control, and Shift,
  185.     respectively.  Also note that the ordering is reversed from that in
  186.     the normal KeyMap table.
  187.  
  188.  
  189. Because keys 20 and 25 each use three qualifier bits (not including KCF_DEAD),
  190. according to the table there must be 8 pairs of data, arranged as shown.
  191. Had only KCF_ALT been set, for instance, (not including KCF_DEAD), just two
  192. pairs would have been needed: key alone and Alt-key.
  193.  
  194. As mentioned earlier, the first byte of data pair in the descriptor data area 
  195. specifies how to interpret the second byte.  There are three possible type
  196. values: 0, DPF_DEAD and DPF_MOD.  In Example 1, DPF_DEAD appears in the data
  197. for key 25,  while DPF_MOD is used for key 20.  It is the use of these flags
  198. which determines whether a dead-class key has dead or deadable function. A
  199. value of zero causes the unrestricted output of the following byte.
  200.  
  201. If the type byte is DPF_DEAD, then that particular key combination (determined
  202. by the placement of the pair of bytes in the data table) is dead and will 
  203. modify the output of the next key pressed, if deadable.  How it modifies is
  204. controlled by the second byte of the pair which is used as an index into
  205. parts of the data area for ALL the deadable keys (DPF_MOD set).
  206.  
  207. Before going further, an understanding of the structure of a descriptor data
  208. area wherein DPF_MOD is set for one or more of its members is necessary.
  209. Referring to the example, we see that DPF_MOD is set for the first and second
  210. pairs of bytes.  According to its LoKeyMapTypes entry, and using Table 1 as
  211. a guide, these pairs represent the alone and Shifted values for the key.  When
  212. DPF_MOD is set, the byte immediately following the flag must be the offset
  213. from the start of the key's descriptor data area to the start of a table of
  214. bytes describing the characters to output when this key combination is preceded
  215. by a dead key.  This is where the index mentioned above comes in.  The
  216. value of the index from a prefixing dead key is used to determine which of the
  217. bytes from the deadable keys special table to output.  The byte in the index+1
  218. position is sent out.  (The byte in the first position is the value to output if
  219. the key was not prefixed by a dead key.)  Thus, if Alt-H is pressed (carat) and
  220. then Shift-A, an @@ will be output.  This is because: 
  221.  
  222.     o  The byte pair for the Alt position of the H key (key 25) is
  223.        DPF_DEAD,3 so the index is 3.
  224.     o  The byte pair for the SHIFT position of the A key (key 20) is
  225.        DPF_MOD,key20s-key20, so we refer to the table-of-bytes at key20s.
  226.     o  The third+1 byte of the table-of-bytes is $C2, a @@ character.
  227.  
  228. Note that the number of bytes in the table-of-bytes for all deadable keys must
  229. be equal to the highest index value of all dead keys plus 1.
  230.  
  231.  
  232.  
  233.  
  234.  
  235.         
  236.      
  237.  
  238.