home *** CD-ROM | disk | FTP | other *** search
/ Stars of Shareware: Animation & Sound / SOS-ANIM_SOUND.ISO / best_50 / ody200.zip / ODYDOC.LZH / MAKEKEY.DOC < prev    next >
Text File  |  1991-10-07  |  6KB  |  130 lines

  1.  
  2. MAKEKEY is a utility for creating Odyssey compatible keyboard definition
  3. files. These files allow you to configure Odyssey such that any key
  4. combination can be substituted with a user defined string of characters.
  5.  
  6. MAKEKEY accepts as input a text file describing the keyboard mapping, and
  7. it outputs a file with the extension .KEY, which you can use within
  8. Odyssey, at the General menu, or in a script by invoking the LoadKeyDef()
  9. function.
  10.  
  11. Keyboard definitions are also loaded automatically if its name matches the
  12. name of a terminal emulation being loaded, that is, if you load a terminal
  13. emulation called XYZ.TRM, and a keyboard definition file exists called
  14. XYZ.KEY then the keyboard file will also be loaded. This allows you to
  15. produce your own variants of the standard terminal emulations for use with
  16. special hardware, eg protocol converters. You would normally copy the
  17. standard emulation to a new name, eg VT100.TRM to VT_TSO.TRM, and prepare
  18. a keyboard definition called VT_TSO.KEY. Doing it this way ensures that
  19. the keyboard definition is not loaded when you want it to behave like a
  20. standard terminal.
  21.  
  22. The format of the keyboard definition source file is very simple, it is
  23. just a text file with one definition per line. The source file may also
  24. contain blank lines, and lines starting with a semicolon ';' are ignored
  25. so such lines may be used for comments.
  26.  
  27. Below are some sample definitions:-
  28.  
  29. <CtrlF1> = <Esc>[0~
  30. <CtrlF2> = <Esc>[1~
  31. <CtrlF3> = <Esc>[2~
  32. <CtrlF4> = <Esc>[3~
  33. <ShiftF1> = <AltS>E
  34. <AltShiftE> = XYZ123
  35.  
  36. Each line contains the key combination to be defined, an equals sign, and
  37. then the definition itself, which is made up of one or more key symbols (a
  38. letter or a key combination). Note that the definition on the right hand side
  39. does NOT need to be an ASCII sequence - you can have one keystroke simulate
  40. a number of other keystrokes whether those are ASCII characters or not - just
  41. enclose non-ASCII keys in angle brackets using the convention described below.
  42.  
  43. A key combination starts with '<' and ends with '>'. In between should be
  44. a key name optionally prefixed by 'Ctrl', 'Alt' or 'Shift', or any
  45. combination of those. There are some valid key definitions:-
  46.  
  47.        <ShiftTab>
  48.        <AltShiftTab>
  49.        <ShiftAltTab>
  50.        <ShiftCtrlTab>
  51.        <<>
  52.  
  53. Key combinations can contain the words 'Alt', 'Shift' and 'Ctrl' in any
  54. order, but the combination must end with a key name (the shift keys are
  55. not sufficient on their own). Table 1 lists the function key names
  56. recognised by MAKEKEY.
  57.  
  58. ------------- TABLE 1 - Recognised Function Key Names -----------------------
  59.  
  60.    (* These are the standard functions keys *)
  61.  
  62.    F1        F2         F3        F4        F5        F6        F7
  63.    F8        F9         F10       Esc       Tab       BS        UpArr
  64.    DownArr   LeftArr    RightArr  Ins       Home      PgUp      Del
  65.    End       PgDn       Enter
  66.  
  67.  
  68.    (* These keys are all generated on the keypad when NUMLOCK is in effect.
  69.       Since MAKEKEY recognises these keys it is possible to have '7' on the
  70.       keypad generate a different sequence from '7' on the main keyboard. *)
  71.  
  72.    K0        K1         K2        K3        K4        K5        K6
  73.    K7        K8         K9        KDot      KMinus    KPlus
  74.  
  75.  
  76.    (* The following keys are only useful if you have an Enhanced Keyboard,
  77.       they include three further keypad keys (KSlash, KStar and KEnter). *)
  78.  
  79.    F11       F12        ELeftArr  EHome      EEnd      EUpArr    EDownArr
  80.    EPgUp     EPgDn      ERightArr KSlash     KStar     KEnter
  81.  
  82. -----------------------------------------------------------------------------
  83.  
  84.  
  85. Once you have prepared your source definition file you then run the
  86. MAKEKEY utility, eg:-
  87.  
  88.     C:\ODYSSEY> makekey mydef.txt
  89.  
  90. Provided that there are no errors in the definition then Odyssey will
  91. create a file called MYDEF.KEY.
  92.  
  93. In operation, Odyssey's key substitution is not nested, ie a definition
  94. such as:-
  95.  
  96.     <Esc> = <Esc>
  97.  
  98. Is essentially a NOP, it does not produce a infinite recursive loop. In
  99. other words only keys actually read from the keyboard may be substituted,
  100. keys which are themselves substitutes are never replaced.
  101.  
  102. Odyssey can distinguish key combinations not normally distinguished by the
  103. keyboard BIOS. It does this by reading the keyboard flags at the same time it
  104. reads the key, and combines the character code, scan code and flags into one
  105. big keyboard code. Even when the BIOS generates the same scancode for ALT-F1
  106. as it does for ALT-SHIFT-F1, Odyssey can still tell the difference, because
  107. the shift states are different. Ody could have done the same trick by taking
  108. over the keyboard interrupt, but that introduces problems with foreign
  109. keyboard layouts - the method described still works when the Dos KEYB driver
  110. is used.
  111.  
  112. You should also be aware that the MAKEKEY utility makes no attempt to verify
  113. that a key combination you define can actually be generated by your keyboard
  114. or BIOS. For example, my keyboard does not generate a keystroke if I press
  115. CTRL,ALT and F1 together, but MAKEKEY will not prevent me from using this
  116. combination in a definition, eg:-
  117.  
  118.       <CtrlAltF1> = XYZ
  119.  
  120. This leaves open the possibility that you can use a replacement keyboard
  121. interrupt 9h handler which generates keystrokes for combinations which are
  122. normally ignored, thereby increasing the number of combinations able to be
  123. redefined. The extra keystrokes would have to generate standard scancodes (ie
  124. they should generate the same scancode as a legal sequence on that key - say
  125. the code for Alt-F1), and Odyssey distinguish the non-standard combination
  126. by checking the keyboard flags as described above.
  127.  
  128. Don Milne.
  129. 24-Mar-1990.
  130.