home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 2 / FFMCD02.bin / new / amigalibdisks / disk933 / editkeys / editkeys.doc < prev    next >
Text File  |  1993-12-21  |  23KB  |  522 lines
  1.  
  2.                 EditKeys v1.4
  3.                 -------------
  4.  
  5.                 ©1991-93 David Kinder
  6.                 ---------------------
  7.  
  8. Introduction
  9. ------------
  10.  
  11. Around late 1990, I was trying to find a program to allow me to edit the
  12. system keymap files. There were a few that let you put strings on keys, but
  13. none gave total control over all the features of keymaps. So I decided to
  14. write my own editor. I mean, how hard could it be..?
  15.  
  16. The result is EditKeys, a keymap editing program designed to work under
  17. AmigaDOS 1.3 and higher. EditKeys is written in machine code and compiled
  18. using HiSoft's Devpac v3 assembler, though it should not be that difficult
  19. to compile under other assemblers. EditKeys is freely distributable,
  20. provided that no more is charged than a nominal fee for copying and disk
  21. media. If you want to use a keymap created with EditKeys in a PD or
  22. commercial package then the only condition I impose is that I receive a
  23. credit somewhere in the program or its documentation.
  24.  
  25. Files
  26. -----
  27.     Program     - EditKeys
  28.               EditKeys.info
  29.     Documentation    - EditKeys.doc
  30.     Disk Libraries    - arp.library (must be in LIBS: for AmigaDOS 1.3)
  31.               asl.library (must be in LIBS: for AmigaDOS 2.0+)
  32.     Source files    - EditKeys.s
  33.               Graphics.s
  34.               xdef.i
  35.               xref.i
  36.               Tech.Notes
  37.  
  38. About EditKeys
  39. --------------
  40.  
  41. EditKeys allows you to edit or create keymap files (They are found in the
  42. Devs/Keymaps/ directory of the boot disk. If you don't know about these
  43. files, then perhaps I should explain.
  44.  
  45. When you press a key on the Amiga's keyboard, the key press is translated by
  46. the keymap file that the system is using. For instance, British Amigas use
  47. the keymap 'gb'. Different keymaps can be found on the system disks
  48. supplied with your Amiga. They are found in:
  49.  
  50.     AmigaDOS 1.3    Extras1.3:Devs/keymaps/
  51.     AmigaDOS 2.0    Extras2.0:Devs/Keymaps/
  52.     AmigaDOS 3.0    Storage3.0:Keymaps/
  53.  
  54. Under AmigaDOS 2.1 and higher keymaps have icons, and are loaded into the
  55. system with the Input prefs editor (or the SetKeyboard command). With
  56. earlier releases, keymaps are loaded with the SetMap program, found in the
  57. System drawer of the boot disk. If you load a keymap different to your
  58. native one, you will find typing some keys gives unexpected results
  59. (especially the non-alphanumeric keys (eg. [,;,# )).
  60.  
  61. Keymaps can be changed to give more radical results; you could redefine the
  62. numerical keypad to produce alphabetic characters if you wanted to, or you
  63. can configure keys to output strings (useful for disk-menus etc.).
  64.  
  65. Please note that any changes made using EditKeys do NOT come into effect
  66. until you load the keymap via the system software; only when you select
  67. 'Save' in EditKeys is a suitable keymap structure constructed and saved to
  68. disk so that AmigaDOS can use it.
  69.  
  70. Keymap Specifications
  71. ---------------------
  72.  
  73. At this point, perhaps I should define some of the terms I will use:
  74.  
  75.   Qualifier Key - CTRL, ALT or SHIFT keys. Do not produce output on their
  76.           own but qualify the output of other keys (eg Shift-f
  77.           produces 'F').
  78.  
  79.   Physical Key    - An actual key on the keyboard, the thing that you touch
  80.           when you type.
  81.  
  82.   Key        - A combination of a physical key and a qualifier, eg q is
  83.           a key, as is Shift-q, Alt-q, Shift-Alt-q, etc. Note that
  84.           Alt-q is an abreiviation for holding down the ALT key
  85.           while tapping the 'q' key.
  86.  
  87. Keymaps contain quite a lot of information, none of which appears in the user
  88. manuals but appears in the RKM under 'console.device' (Makes sense to put
  89. info about the keyboard in a programmer's manual eh?). Therefore I shall
  90. attempt to briefly describe what is possible.
  91.  
  92. Keys can be redefined to produce any character when pressed with one of the
  93. qualifiers, and also keys can produce strings of up to 32 characters.
  94. Physical keys with a STRING key on them may not have DEAD or MODIFIABLE keys
  95. on them (see below).
  96.  
  97. Some keys repeat when held down (eg all alphabetic keys), while others do not
  98. (eg the <RETURN> key). Physical keys which repeat are referred to as
  99. REPEATABLE (fairly obvious). Whether a key repeats or not is controlled by
  100. the keymap. Similarly, the keymap controls whether a key is CAPSABLE or not.
  101. When the 'Caps Lock' light is on, some keys produce their Shifted values (eg
  102. 'q'), while the numerical keys produce their normal values.
  103.  
  104. Some keys are DEAD, while others are MODIFIABLE. For an example of this, open
  105. a CLI window, then hold down ALT while tapping the 'f' key (From now on
  106. abrieviated to Alt-f); nothing happens. Now tap the 'a' key, the result is
  107. an a with an accent over it: 'á'. The key Alt-f is a DEAD key, while 'a' is a
  108. MODIFIABLE key. When you type Alt-f, the Amiga stores the deadkey, which it
  109. then uses to modify the output of the 'a' key. Not all keys are MODIFIABLE,
  110. Alt-f followed by 'q' just produces 'q'. A physical key with DEAD or
  111. MODIFIABLE keys on it may NOT have STRING keys on it.
  112.  
  113. There is a further limitation in that those physical keys that are not DEAD
  114. or MODIFIABLE use only 4 bytes for their definition, eg on the 'A' key on
  115. your keyboard there is 'a', 'A', 'æ' and 'Æ'. However, there are 8 different
  116. permutations of the Shift, Alt and Control qualifiers with the key, so not
  117. every combination of physical key with qualifier can be uniquely defined.
  118. Why didn't Commodore use 8 bytes for each key? (sigh). There is one other
  119. point; if a physical key has definitions for Shift and Alt (and thus
  120. Shift-Alt) then we can configure the key so that the Control qualifier
  121. outputs the value that would appear without the Control key being pressed,
  122. but with bits 6 and 7 cleared (eg Control-c). Confused? You're not the only
  123. one... But playing around with EditKeys should make all this clear (or at
  124. least clearer than it is at present).
  125.  
  126. It is worth noting before I start on a discussion of EditKeys that once you
  127. have loaded a keymap into the system, you cannot replace it with another
  128. of the same name using SetMap or SetKeyboard. This is because the system
  129. expects keymaps not to change. The solution to this is to use the supplied
  130. 'LoadKeymap' command.
  131.  
  132. The Program
  133. -----------
  134.  
  135. EditKeys allows you to modify all the above features of a keymap. Keys may be
  136. made DEAD or MODIFIABLE, or have STRING definitions put on them, as well as
  137. being redefined. The program may be started from CLI or Workbench:
  138.  
  139. From Workbench: Just double click on the program's icon. A file requester
  140.         will appear for you to select a keymap to load. Click on
  141.         a keymap or 'Cancel'.
  142.  
  143. From CLI:    1) Just type the program's name, ie
  144.  
  145.             1> EditKeys
  146.  
  147.         The program will attempt to display a file requester
  148.         prompting you for a keymap to load. Select a keymap or
  149.         click on 'Cancel' to start the program without a keymap
  150.         loaded. Or,
  151.  
  152.         2) Pass a keymap name to the program, ie.
  153.  
  154.             EditKeys [<keymap>] [NOMAP]
  155.  
  156.            eg    1> EditKeys gb
  157.            or    1> EditKeys NOMAP
  158.  
  159.         You do not need to specify the path of the keymap as
  160.         EditKeys will automatically look in DEVS:keymaps/. If
  161.         you specify the NOMAP option then EditKeys will start
  162.         without loading a keymap. Or,
  163.  
  164.         3) Enter the line
  165.  
  166.             1> EditKeys ?
  167.  
  168.         Which will bring up a template. Entering a further ? will
  169.         prompt you with a small help message. Enter a keymap name
  170.         or NOMAP (see above).
  171.  
  172. When the program has loaded it will open a window on the Workbench screen.
  173. In the titlebar is the name of the keymap being edited; below that is a
  174. representation of the A500/A2000/A1200 keyboard with the keymap you chose.
  175. Note that it may appear to you that the keyboard has acquired two extra keys
  176. (one to the right of the left Shift key and the other to the left of the
  177. Return key), as these are not present on the older UK and US Amigas.
  178.  
  179. Furthermore, the representation of the keymap usually shows what is output
  180. by that key, but for certain keys (eg Esc, Help, Del, F1-F10) I have chosen
  181. to use a little graphic which never changes as this looks better. If you need
  182. to be certain what a key outputs, click on it; its output will be displayed
  183. at the bottom to the EditKeys window.
  184.  
  185. Qualifier keys (Shift etc.) displayed on the screen work as expected; click
  186. on Shift to see the effect. The program is run using the menus and the five
  187. mode gadgets displayed below the keyboard; each gadget represents a different
  188. aspec