home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d1xx / d193 / keymaped.lha / KeyMapEd / KeyMapEd.doc < prev    next >
Text File  |  1989-03-13  |  12KB  |  263 lines
  1.                Key Map Editor
  2.                  Tim Friest
  3.                  March, 1989
  4.  
  5.                 version 1.0
  6.  
  7. ***************************************************************************
  8. * The KeyMapEditor is copyright © 1989 to Tim Friest              *
  9. *                                      *
  10. * this program is FREE, you may copy it or distribute it as long as there *
  11. * is no charge for the program (small handling fees are allowed if this   *
  12. * program is distributed on a disk with other PD/FreeWare/ShareWare      *
  13. * programs or on a charge BBS), the executable is unaltered and this      *
  14. * file accompanies it.                              *
  15. *                                      *
  16. * please send any and all comments and/or bug reports to:          *
  17. *                                      *
  18. * USMail:    Tim Friest        bitnet: AXTBF@ALASKA.BITNET      *
  19. *        3861 Steller Dr                          *
  20. *        Anchorage, AK 99504    bix:    TFRIEST              *
  21. *                                      *
  22. * Voice:    (907) 337-5108                          *
  23. *                                      *
  24. * Compiled with Lattice C 5.02                          *
  25. *                                      *
  26. * tested on: B2000 rev 4.3, ROMs v1.3, NTSC, 3Mb RAM, AmigaDOS v1.3      *
  27. *                                      *
  28. ***************************************************************************
  29.  
  30. Introduction:
  31.  
  32. KeyMapEd allows you to modify the KeyMaps destributed by Commodore-Amiga
  33. with AmigaDOS.  These KeyMaps may then be installed on your system with
  34. the SetMap command.
  35.  
  36. Basically, any key may have 'key macros'.  Each key may have a seperate
  37. value for pressing the key alone, with shift, with alt, with shift & alt,
  38. with control, with control & shift, with control & alt, and with shift, alt,
  39. & control (the latter is refered to as vanilla).  Thus, each key may have up
  40. to 8 seperate values when pressed.  Further, keys may be capsable (use the
  41. shift value when the caps lock key is on) and/or repeatable (key repeats
  42. when held down).  Finally, pressing the combination of a dead key with a
  43. key that is deadable (modified by a dead key) allows the addition of accents
  44. to the key value (for instance an 'alt-g' then 'a' will produce an 'à' or an
  45. 'a' with an accent grav above it).
  46.  
  47. Any program which is written correctly and uses the default keymap will
  48. fully support all these features and fully support any changes you make
  49. to your keymap.  Unfortunately there are many programs which are not written
  50. correctly and/or do not use the default keymap (hint! hint! developers!!!).
  51.  
  52. I believe that with this utility, it will be much easier to write a program
  53. which uses a special keymap, and still fully support the keymap capablities,
  54. then to hardcode what each key does within the progam.
  55.  
  56. Note:    SetMap adds the keymap to a list in memory and if you do
  57.  
  58.         SetMap usa1
  59.         SetMap f
  60.         SetMap usa1
  61.  
  62.     SetMap will only read usa1 once!  Further, usa1 and f will both
  63.     remain in memory until you reboot.
  64.  
  65.     This impacts KeyMapEd since modifying a keymap that you've already
  66.     done a SetMap on, then trying to SetMap it again, will not update
  67.     the keymap in memory (it will just use the version it had already
  68.     loaded into memory).   You would have to save the keymap out under
  69.     a different name from KeyMapEd to get SetMap to use the new version.
  70.     The name is hardcoded in the file, so it is recommended you do not
  71.     rename the file.  The reason for this is that SetMap compares the
  72.     name within the file to the keymap that is requested, and if it is
  73.     the same, the version already in memory is used.  Supose you edited
  74.     the usa1 keymap, saved it as usa1 and then renamed it to foo.  Then
  75.     you changed your Startup-Sequence to do a SetMap foo instead of
  76.     SetMap usa1 (which is normal for A500/A2000s).  The system still
  77.     thinks that the keymap it has loaded is usa1 (not foo) since that was
  78.     the name coded in the file... For this reason, doing a SetMap usa1
  79.     will not load in usa1, but use the one in memory (which is really foo).
  80.     Also, SetMap foo will load another copy of foo into memory since
  81.     foo doesn't match usa1.
  82.  
  83. Description:
  84.  
  85. There are four basic types of keys definable within a keymap.
  86.  
  87.  
  88. NOP
  89.  
  90. A NOP key does nothing, and has no value.
  91.  
  92.  
  93. Normal (NoQual)
  94.  
  95. A normal key may contain up to 4 single character values (plus a special
  96. value for vanilla keys).  This format uses the least amount of space, so
  97. you should use this if possible (as apposed to the next two).
  98.  
  99. The four values can correspond to any combination of the key alone with
  100. up to two of the shift/alt/ctrl combinations.  If you want the key to be
  101. vanilla, the ctrl key modifies the value of certain alphabetic keys plus
  102. some others (@ for example), giving you 5 values for that key.  For example
  103. the 't' key contains the values 't', 'T', alt-t '\xfe', alt-T '\xde', and
  104. ctrl-t '\x14' (note the ctrl-t value isn't actually stored, it is calculated).
  105.  
  106.  
  107. String
  108.  
  109. A string key may contain all 8 possible values, and each value may be up
  110. to 32 (as of AmigaDOS v1.3) characters in length.  A good example of string
  111. keys are the function keys, the arrow keys, or the application keys.  These
  112. keys will send a string whenever the key is pressed.  This is basically what
  113. will give you that 'key macro' capability.  Any key which is not dead or
  114. deadable may be string and output up to 8 different 32 character values
  115. when pressed.  Therefore, if you want alt-f10 to issue a 'list dh0:" command
  116. you could simply code that into the keymap.
  117.  
  118.  
  119. Dead
  120.  
  121. Dead keys output up to a single character in one of three ways.  A key that
  122. is dead (when you press it it modifies the value of the next key pressed), a
  123. key that is deadable (modified by a dead key), and a key that is uneffected
  124. by a dead key.  If a key is dead, it contains the value of the accent that
  125. it will use (for instance alt-k will produce an umlat with deadable keys).
  126. If a key is deadable, seperate values will be stored for each possible accent
  127. available on that key (there are currently five: accent accute (´), accent
  128. grav (`), caret (^), circumflex (~), and umlat (¨) (I produced these by
  129. pressing alt-f space, alt-g space, alt-h space, alt-j space, alt-k space with
  130. the USA1 keymap)).  Finally, if the key can not be modified by a dead key,
  131. then simply place the value in the keymap (for instance an alt-a is not
  132. modified by a dead key).
  133.  
  134.  
  135. Using KeyMapEd:
  136.  
  137. KeyMapEd will prompt for a keymap if you do not specify one.  It auto-
  138. matically assumes the keymap is located in devs:keymaps so you must specify
  139. the full pathname if it is not located there (SetMap requires the keymap
  140. be in devs:keymaps so you might as well put them there anyway).
  141.  
  142. The KeyMapEd window is very similar to KeyToy and should display the current
  143. value for each key with the current combination of shift/alt/ctrl/capslock.
  144. Simply press the shift/alt/ctrl/capslock gadgets to change the display.  The
  145. keyboard displayed is that of an Amiga 2000.  The keymap for an Amiga 500 or
  146. 1000 is exactly the same!  The A2000 keyboard has a few additional keys
  147. that the A1000 did not, and some of the keys have migrated, but other then
  148. that, the keymap for ALL keys on the A1000 keyboard is exactly the same as
  149. that for an A2000, there are just fewer values on the A2000 keyboard listed
  150. as unused (i.e. there are still spaces left so an A3000 might very well have
  151. even more keys then the A2000 and still be fully compatible with the A1000
  152. (at least keymap wise)).
  153.  
  154. Clicking on a key gadget other then the shift, alt, ctrl, or capslock will
  155. display the key editor window for that key.
  156.  
  157. The top row of gadgets define what type of key this is (NOP, Normal, String,
  158. or Dead).  The second row shows which of the shift/alt/ctrl keys effect this
  159. key.  The third row displays whether the key is capsable and/or repeatable.
  160. Finally the rest of the window shows the values for each of the shift/alt/ctrl
  161. combinations available for this key.  The rest of the window will be different
  162. depending on whether the key is NOP, Normal, String, or Dead.
  163.  
  164. Values for a key will be displayed in standard C string format.  This means
  165. that if the value is normally printable, the value should appear, otherwise
  166. the hex value for the key will be displayed in the format '\x##'.  A few
  167. notable exceptions to this rule are certain of the common control codes have
  168. special values '\r' for return, '\n' for newline, '\f' for formfeed, etc.
  169. Finally, since the '\' is used as an introducer for the control sequences,
  170. you must use '\\' to specify a single backslash.
  171.  
  172. Since up to 4 characters may be used to specify a single character value,
  173. the string gadgets for a single value may hold up to 4 characters.  Please
  174. note that Normal keys and dead keys may contain 1 and only 1 value, and if
  175. you place more characters in the string gadget then what will equate to
  176. a single character, the string will be truncated to 1 character.  Likewise,
  177. String keys may only contain 32 characters, I have made the string gadget
  178. size 127 to hold many control sequences.  Again, the resultant string will
  179. be truncated to 32 characters.
  180.  
  181. Switching back and forth betwean the types of keys (NOP, Normal, String, and
  182. Dead) will produce strange results as strings are truncated to fit within
  183. certain limits or altered as dead or deadable keys.
  184.  
  185. Selecting either the Use or Cancel gadgets will end the key edit mode and
  186. either update the keymap or not depending.
  187.  
  188.  
  189. Saving the KeyMap:
  190.  
  191. Once you have gotten the keymap as you like, you will want to save it.
  192. Selecting the Save option from the Project Menu will give you a file requester
  193. which you may use to save the keymap either to the same filename as read or
  194. a new filename.  Again the default directory is devs:keymaps, and you must
  195. specify otherwise if you desire it to be elsewhere.
  196.  
  197. Note: The Key Map Editor uses the filename as the node name of the keymap,
  198.       thus if you save a keymap as USA1 the system will not differenciate
  199.       betwean the real (system) USA1 and your modified version, but if you
  200.       save it as NEWUSA1, the system will always see it as NEWUSA1 even if
  201.       you rename the file to USA1.  This is important to remember because
  202.       of the way SetMap works (see note at top).
  203.  
  204.  
  205. ---------------------------------------------------------------------------
  206.  
  207. Changes to v0.99 since v0.91:
  208.  
  209.     Fixed bug with interpretation of Vanilla keys for normal type
  210.  
  211.     Added options in options menus
  212.  
  213. ---------------------------------------------------------------------------
  214.  
  215. Changes to v1.0 since v0.99:
  216.  
  217.     Center text within gadgets on keyboard display
  218.  
  219.     Fixed return key (used Masked Boolean gadget so all of key
  220.     highlights when selected)
  221.  
  222.     Modified CTRL and CapsLock keys so rapidly and repeatly clicking
  223.     them would not continually refresh the screen (this already worked
  224.     on Shift and Akt keys)
  225.  
  226.     Fixed problem with key labels for NOP keys which causes GURUs
  227.  
  228.     Fixed a problem with deadable keys which were not Vanilla
  229.  
  230.     Fixed title/version number
  231.  
  232. ---------------------------------------------------------------------------
  233.  
  234. Changes to v1.01 since v1.0:
  235.  
  236.     Fixed a major bug when converting from one type of key to another
  237.     (for instance editing a normal key and changing it to a string
  238.     key caused a GURU)
  239.  
  240.     Fixed a problem with the key label centering code (didn't update
  241.     properly).
  242.  
  243. ---------------------------------------------------------------------------
  244.  
  245. Changes to v1.02 since v1.01:
  246.  
  247.     Fixed the Return key to not overright the ] when edited
  248.  
  249. ---------------------------------------------------------------------------
  250.  
  251. Known Bugs/Features: v1.02 March 9, 1989
  252.  
  253.     String gadgets don't erase the last character when scrolled to the
  254.     right.  Seems to be a bug with intuition???
  255.  
  256.     Return key gadget erases part of ] key on refresh
  257.  
  258. ----------------------------------------------------------------------------
  259.  
  260. Planned Inhancements: v1.02
  261.  
  262.     see known bugs/features
  263.