home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 300-399 / ff398.lzh / KeyMacro / KeyMacro.doc < prev    next >
Text File  |  1990-11-01  |  12KB  |  268 lines
  1. ======================================================================
  2. =========================== KeyMacro v1.6 ============================
  3. ================== * A macro key handler utility * ===================
  4. ======================================================================
  5.  
  6. ============================= IMPORTANT ==============================
  7. ======================================================================
  8. The  current release of KeyMacro requires arp.library and Null-Handler
  9. to  be  present  in  your system.  Put the library into LIBS:  and the
  10. handlers into L:.  Then add the following lines to DEVS:MountList:
  11.  
  12.     NULL:    Handler        = L:Null-Handler
  13.         Stacksize    = 500
  14.         Priority    = 5
  15.         GlobVec        = -1
  16.     #
  17.  
  18. You  _M_U_S_T_  install  the Null-Handler using the CLI command 'Mount
  19. NULL:' before starting KeyMacro or the KeyMacro handler won't budge.
  20.  
  21. ============================ BACKGROUND ==============================
  22. ======================================================================
  23. Some  time  ago  I  played around with a keymap editor to customize my
  24. keymap  settings.  But there was a feature I missed:  there wasn't any
  25. hot-key  support  (just  like  PopCLI  or  DMouse).  I also discovered
  26. another  disadvantage:   to change the keymap settings you had to load
  27. the  keymap  editor, edit the map, save it to disk and then install it
  28. via  SetMap  -  and even that didn't guarantee that the new keymap was
  29. accepted:   do  you  remember that SetMap does not load new keymaps if
  30. the  name matches a keymap already in memory?  Furthermore keymap keys
  31. may only generate string sequences of up to 32 characters.  With these
  32. topics in mind I decided to write my own keyboard macro handler.
  33.  
  34. ============================= FEATURES ===============================
  35. ======================================================================
  36. KeyMacro  provides  an  easy  way to manage keyboard macros (character
  37. sequences)  and  hot-key program execution.  You edit a script file in
  38. which  all  required key combinations are defined and call KeyMacro to
  39. update the macro list - that's all.  You can map up to eight functions
  40. to  each  key, including keys such as the cursor keys, the return key,
  41. etc.   The hot-key programs will use an AmigaDOS search path list when
  42. getting  executed.  Each macro key call gets processed asynchronously,
  43. i.e.   invoking  one  hot-key  command  after the other will start all
  44. commands in a row, nothing will be skipped.
  45.  
  46. =========================== INSTALLATION =============================
  47. ======================================================================
  48. Place  KeyMacro-Handler in L:, KeyMacro in C:  or SYS:, arp.library in
  49. LIBS:,   copy   your   KeyMacro.config  to  S:.   Type  "KeyMacro"  to
  50. install/update  macro  keys, "KeyMacro quit" to remove.  Note:  if the
  51. installation  fails  the  main  process  ("KeyMacro")  will wait for a
  52. handshake signal which may never arrive.  In this case pressing CTRL-C
  53. will  stop  the  main  process.   It will shut down and issue an error
  54. message.
  55.  
  56. =============================== USAGE ================================
  57. ======================================================================
  58. KeyMacro is controlled via a script file.  Here is a sample:
  59.  
  60.     ; KeyMacro v1.6 configuration file.
  61.     ; The semicolon says that this is a comment:
  62.  
  63.     ; Some keyboard macros.
  64.  
  65.     key ctrl+esc = "EndCLI > NIL:\n"
  66.     key lalt+0 = "CD DF0:\n"
  67.     key lalt+1 = "CD DF1:\n"
  68.  
  69.     ; A hot-key command definition
  70.  
  71.     command lalt+v = "C:vt100 +i s:vt100.init" window "VT100"
  72.  
  73. Each  definition  must  be  "key"  or "command".  "Key" means that the
  74. following  definition  will be a sequence of characters to be inserted
  75. into  the input stream.  "Command" means that the following definition
  76. will be the name and the arguments of a program to be executed.
  77.     The  macro  type  is  followed  by  the  key combination to be
  78. pressed to execute the macro definition.  This combination consists of
  79. the keyboard qualifier and the key.  An unlimited number of qualifiers
  80. is allowed.  KeyMacro knows the following qualifiers:
  81.  
  82.     NONE ..........    No qualifier (note: a qualifier MUST be given!)    
  83.     CTRL ..........    The control key
  84.     NUMPAD ........    The numeric pad
  85.     LSHIFT ........    The left shift key
  86.     RSHIFT ........    The right shift key
  87.     LALT ..........    The left alternate key
  88.     RALT ..........    The right alternate key
  89.     LAMIGA ........    The left Amiga key (Commodore key)
  90.     RAMIGA ........    The right Amiga key
  91.  
  92. A qualifier must be given or the macro parser will panic; if you don't
  93. need a qualifier simply enter NONE as the qualifier.
  94.     The  qualifier  is  followed  by  the  key to attach the macro
  95. expression  to.   This  can  be  any  key  on  the keyboard, including
  96. function keys, cursor keys, etc.  If there is no ASCII value available
  97. for the key, you can take a name from the following list:
  98.  
  99.     TAB ...........    The tabulator key
  100.     ESC ...........    The escape key
  101.     SPACE .........    The space key
  102.     RETURN ........    The return key
  103.     ENTER .........    The enter key (numeric pad)
  104.     DEL ...........    The delete key
  105.     BACKSPACE .....    The backspace key
  106.     HELP ..........    The help key
  107.  
  108.     LEFT ..........    The cursor-left key
  109.     RIGHT .........    The cursor-right key
  110.     UP ............    The cursor-up key
  111.     DOWN ..........    The cursor-down key
  112.  
  113.     F1 ............    The function key #1
  114.     F2 ............    The function key #2
  115.     F3 ............    The function key #3
  116.     F4 ............    The function key #4
  117.     F5 ............    The function key #5
  118.     F6 ............    The function key #6
  119.     F7 ............    The function key #7
  120.     F8 ............    The function key #8
  121.     F9 ............    The function key #9
  122.     F10 ...........    The function key #10
  123.  
  124. These  equivalents  can  be  used just like characters.  Note:  if you
  125. enter more than one single character as the command key only the first
  126. character will be taken (except for the key names listed above).
  127.     The key is followed by a '=' sign, this tells the macro parser
  128. to   remember   the  following  string  as  the  macro  string  to  be
  129. entered/executed.   This  string  must  be  enclosed  in quotes or the
  130. parser will take only the first word.  Inside this string sequences of
  131. two  characters can be used to generate key codes not supported by the
  132. ASCII keyboard.  These sequences are:
  133.  
  134.     \u ............    Cursor-up key
  135.     \d ............    Cursor-down key
  136.     \l ............    Cursor-left key
  137.     \r ............    Cursor-right key
  138.  
  139.     \n ............    The return key
  140.  
  141.     \h ............    The help key
  142.     \b ............    The backspace key
  143.     \e ............    The delete key (sorry, \d was already used)
  144.     \f1 - \f10 ....    The function keys
  145.     \" ............    A quote
  146.     \\ ............    The escape symbol ('\')
  147.  
  148. A  hot-key  command  definition can be followed by a "window" keyword.
  149. This  keyword  identifies  the next string (enclosed in quotes) as the
  150. typical window title of the command to be loaded.  Before this command
  151. is  executed  each open window is checked for this title.  If a window
  152. title matches the name it is brought to the front, no new command will
  153. be loaded.
  154.     KeyMacro  has  some  problems if you try to map macros to keys
  155. which are to be found on the standard keyboard and the numeric key pad
  156. as  well.   The  keymap  routine will map the macro to the numeric key
  157. pad.   The  only  exception  are  the number keys which are by default
  158. mapped to the number row.
  159.  
  160.                                   *
  161.  
  162.            KeyMacro has the following command-line options:
  163.  
  164. Startup .......    Followed  by  the  name  of  the file to be used as
  165.         configuration  file will keep KeyMacro from looking
  166.         for S:KeyMacro.config as the standard configuration
  167.         file.
  168.  
  169. Quit ..........    Removes KeyMacro from memory.
  170.  
  171. Info ..........    Gives a brief information on the program.
  172.  
  173. =============================== FUTURE ===============================
  174. ======================================================================
  175. There  is  a  good  chance  that  there  will  be  no further KeyMacro
  176. revisions  available  for  machines  running Kickstart revisions lower
  177. than  2.x.   I plan to bring KeyMacro to an entirely system-integrated
  178. state  in  which  there is no need to rely on undocumented system data
  179. structures  (keymap  inversion) and to get along with DOS the way I am
  180. currently  dealing  with it.  KeyMacro users:  what is your opinion on
  181. this topic?
  182.  
  183. ============================== CREDITS ===============================
  184. ======================================================================
  185. Credits  go to ARP Programmers for the most recent version of ARP, Jim
  186. Mackraz  for  his  keymap 'inversion' routine, to Paul Kienitz for his
  187. FakeCLI package, to Mark R.  Rinfret for the buffered Arp I/O routines
  188. and to Matt Dillon for DMouse.
  189.     A special mention must also go to Bill Hawes, author of ARexx,
  190. and  to the authors of CygnusEd Pro 2 (Bruce Dawson & Colin Fox) whose
  191. programs both controlled the compiler runs.
  192.  
  193. ================== COPY FEE, AUTHORS REQUEST, ETC. ===================
  194. ======================================================================
  195. This  is the first time I release a program as shareware.  Consider it
  196. as  a  "test balloon" for coming projects.  A small contribution of at
  197. least $10 US or at least DM 15,- will insure your registration, giving
  198. you  the  opportunity  to  receive  updates, new programs from MXM and
  199. more.   Think about it, if you like this program and use it often this
  200. small  amount  of  money  will support the author and encourage him to
  201. start new projects.
  202.  
  203.        Send comments, bug reports, ideas and contributions to:
  204.  
  205.                           Olaf Barthel, MXM
  206.                           Brabeckstrasse 35
  207.                           D-3000 Hannover 71
  208.  
  209.                      Federal Republic of Germany
  210.  
  211. Permission  hereby  granted  to  re-distribute  KeyMacro  v1.6  in its
  212. entirety for non profit usage only.
  213.  
  214. ============ REVISION HISTORY (most recent change first) =============
  215. ======================================================================
  216. V1.6    Thanks  to  user  persistance  KeyMacro was thoroughly revised
  217.     (yes, I mean what I say!).  Bert L.  Allen discovered problems
  218.     with the numeric key pad, Ralf Thanner suggested that I should
  219.     get rid of mxm.library, Martin Berndt and Benito Lombardi made
  220.     helpful  suggestions.   The  dreaded  mxm.library  was finally
  221.     removed,  saving about 20 KByte when there is no other program
  222.     to  access  the mxm.library routines.  The routine to simulate
  223.     the  key  events  will produce a key-down followed by a key-up
  224.     event.   Macros will no longer invoke other macros on the way.
  225.     InputEvents  created  by  KeyMacro-Handler  will  have a valid
  226.     timestamp.   Key  names are no longer abbreviated (i.e.  'f10'
  227.     !=  'f1').  The return key will finally work in cases where it
  228.     wouldn't work in revision 1.4.
  229.  
  230. V1.5    Small changes to library and code, recompiled  using  the  new
  231.     Aztec 'C' 5.0b compiler.
  232.  
  233. V1.4    Wow!   It  works!   The reasons for the constant failures were
  234.     located  in  1) mxm.library, 2) in the Arp wrapper for Lattice
  235.     'C',   3)   in   KeyMacro   itself   and   4)   of  course  in
  236.     KeyMacro-Handler.   Needless to say, mxm.library was fixed and
  237.     the code has once more changed the compiler - KeyMacro 1.4 now
  238.     compiles   under   Aztec   5.0.    Programs   started  by  the
  239.     executor-process will no longer block until the program exits.
  240.     This  is  now  probably  the only input.device example program
  241.     written  in  Aztec  'C'  which doesn't use ANY inline assembly
  242.     language code (#asm/#endasm).
  243.  
  244. V1.3    Well, I wouldn't shoot  my  grandma  to get it working, but it
  245.     really  starts  to  become  a  nuisance:  1.2 still wasn't the
  246.     success  I  had  expected.  I took a second look into RKM Exec
  247.     and  discovered  that  interrupt handlers be located in public
  248.     ram.   As  a  result  almost all static data declarations have
  249.     been replaced by memory allocations.
  250.  
  251. V1.2    I  guess  you know what happened:  it still didn't work right.
  252.     The  code  is  now  much  more compact and has been recompiled
  253.     using Lattice 'C' 5.04.
  254.  
  255. V1.1    KeyMacro  obviously  worked  on  only  one machine:  my Amiga.
  256.     This  is the first attempt to fix it.  I cleaned up the code I
  257.     didn't  think  to  be that much important which hopefully will
  258.     fix the problem.
  259.  
  260. V1.0    First  public  release;  seems  that  it  works (what did I do
  261.     wrong?).
  262.  
  263.                                   *
  264.  
  265.              Do only its possibilities make it an Amiga?
  266.  
  267.                         WHERE IS THE MAGIC ???
  268.