Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 468.lha / KeyMacro_v1.8 / KeyMacro.doc < prev next >

Wrap

Text File | 1991-02-08 | 13.0 KB | 287 lines

====================================================================== =========================== KeyMacro v1.8 ============================ ================== * A macro key handler utility * =================== ====================================================================== ============================= IMPORTANT ============================== ====================================================================== The current release of KeyMacro requires arp.library and Null-Handler to be present in your system. Put the library into LIBS: and the handlers into L:. Then add the following lines to DEVS:MountList: NULL: Handler = L:Null-Handler Stacksize = 500 Priority = 5 GlobVec = -1 # You _M_U_S_T_ install the Null-Handler using the CLI command 'Mount NULL:' before starting KeyMacro or the KeyMacro handler won't budge. ============================ BACKGROUND ============================== ====================================================================== Some time ago I played around with a keymap editor to customize my keymap settings. But there was a feature I missed: there wasn't any hot-key support (just like PopCLI or DMouse). I also discovered another disadvantage: to change the keymap settings you had to load the keymap editor, edit the map, save it to disk and then install it via SetMap - and even that didn't guarantee that the new keymap was accepted: do you remember that SetMap does not load new keymaps if the name matches a keymap already in memory? Furthermore keymap keys may only generate string sequences of up to 32 characters. With these topics in mind I decided to write my own keyboard macro handler. ============================= FEATURES =============================== ====================================================================== KeyMacro provides an easy way to manage keyboard macros (character sequences) and hot-key program execution. You edit a script file in which all required key combinations are defined and call KeyMacro to update the macro list - that's all. You can map up to eight functions to each key, including keys such as the cursor keys, the return key, etc. The hot-key programs will use an AmigaDOS search path list when getting executed. Each macro key call gets processed asynchronously, i.e. invoking one hot-key command after the other will start all commands in a row, nothing will be skipped. =========================== INSTALLATION ============================= ====================================================================== Place KeyMacro-Handler in L:, KeyMacro in C: or SYS:, arp.library in LIBS:, copy your KeyMacro.config to S:. Type "KeyMacro" to install/update macro keys, "KeyMacro quit" to remove. Note: if the installation fails the main process ("KeyMacro") will wait for a handshake signal which may never arrive. In this case pressing CTRL-C will stop the main process. It will shut down and issue an error message. =============================== USAGE ================================ ====================================================================== KeyMacro is controlled via a script file. Here is a sample: ; KeyMacro v1.8 configuration file. ; The semicolon says that this is a comment: ; Some keyboard macros. key ctrl+esc = "EndCLI > NIL:\n" key lalt+0 = "CD DF0:\n" key lalt+1 = "CD DF1:\n" ; A hot-key command definition command lalt+v = "C:vt100 +i s:vt100.init" window "VT100" Each definition must be "key" or "command". "Key" means that the following definition will be a sequence of characters to be inserted into the input stream. "Command" means that the following definition will be the name and the arguments of a program to be executed. The macro type is followed by the key combination to be pressed to execute the macro definition. This combination consists of the keyboard qualifier and the key. An unlimited number of qualifiers is allowed. KeyMacro knows the following qualifiers: NONE .......... No qualifier (note: a qualifier MUST be given!) CTRL .......... The control key NUMPAD ........ The numeric pad LSHIFT ........ The left shift key RSHIFT ........ The right shift key LALT .......... The left alternate key RALT .......... The right alternate key LAMIGA ........ The left Amiga key (Commodore key) RAMIGA ........ The right Amiga key A qualifier must be given or the macro parser will panic; if you don't need a qualifier simply enter NONE as the qualifier. The qualifier is followed by the key to attach the macro expression to. This can be any key on the keyboard, including function keys, cursor keys, etc. If there is no ASCII value available for the key, you can take a name from the following list: TAB ........... The tabulator key ESC ........... The escape key SPACE ......... The space key RETURN ........ The return key ENTER ......... The enter key (numeric pad) DEL ........... The delete key BACKSPACE ..... The backspace key HELP .......... The help key LEFT .......... The cursor-left key RIGHT ......... The cursor-right key UP ............ The cursor-up key DOWN .......... The cursor-down key F1 ............ The function key #1 F2 ............ The function key #2 F3 ............ The function key #3 F4 ............ The function key #4 F5 ............ The function key #5 F6 ............ The function key #6 F7 ............ The function key #7 F8 ............ The function key #8 F9 ............ The function key #9 F10 ........... The function key #10 These equivalents can be used just like characters. Note: if you enter more than one single character as the command key only the first character will be taken (except for the key names listed above). The key is followed by a '=' sign, this tells the macro parser to remember the following string as the macro string to be entered/executed. This string must be enclosed in quotes or the parser will take only the first word. Inside this string sequences of two characters can be used to generate key codes not supported by the ASCII keyboard. These sequences are: \u ............ Cursor-up key \d ............ Cursor-down key \l ............ Cursor-left key \r ............ Cursor-right key \n ............ The return key \h ............ The help key \b ............ The backspace key \e ............ The delete key (sorry, \d was already used) \f1 - \f10 .... The function keys \" ............ A quote \\ ............ The escape symbol ('\') A hot-key command definition can be followed by a "window" keyword. This keyword identifies the next string (enclosed in quotes) as the typical window title of the command to be loaded. Before this command is executed each open window is checked for this title. If a window title matches the name it is brought to the front, no new command will be loaded. KeyMacro has some problems if you try to map macros to keys which are to be found on the standard keyboard and the numeric key pad as well. The keymap routine will map the macro to the numeric key pad. The only exception are the number keys which are by default mapped to the number row. * KeyMacro has the following command-line options: Startup ....... Followed by the name of the file to be used as configuration file will keep KeyMacro from looking for S:KeyMacro.config as the standard configuration file. Quit .......... Removes KeyMacro from memory. Delay ......... You will need this keyword if the keypresses KeyMacro emits do not produce sensible results, i.e. the output is garbled or characters are swallowed. You may specify the delay between the single keypresses. The rate must be given in microseconds, i.e. a value of 1000000 will produce a delay of one second (you won't be needing this much, will you?), 500000 will wait half a second. For technical reasons the delay rate has to be >= 10000. Info .......... Gives a brief information on the program. =============================== FUTURE =============================== ====================================================================== There is a good chance that there will be no further KeyMacro revisions available for machines running Kickstart revisions lower than 2.x. I plan to bring KeyMacro to an entirely system-integrated state in which there is no need to rely on undocumented system data structures (keymap inversion) and to get along with DOS the way I am currently dealing with it. KeyMacro users: what is your opinion on this topic? ============================== CREDITS =============================== ====================================================================== Credits go to ARP Programmers for the most recent version of ARP, to Paul Kienitz for his FakeCLI package, to Mark R. Rinfret for the buffered Arp I/O routines and to Matt Dillon for DMouse. A special mention must also go to Bill Hawes, author of ARexx, and to the authors of CygnusEd Pro 2 (Bruce Dawson & Colin Fox) whose programs both controlled the compiler runs. ================== COPY FEE, AUTHORS REQUEST, ETC. =================== ====================================================================== This is the first time I release a program as shareware. Consider it as a "test balloon" for coming projects. A small contribution of at least $10 US or at least DM 15,- will insure your registration, giving you the opportunity to receive updates, new programs from MXM and more. Think about it, if you like this program and use it often this small amount of money will support the author and encourage him to start new projects. Send comments, bug reports, ideas and contributions to: Olaf Barthel, MXM Brabeckstrasse 35 D-3000 Hannover 71 Federal Republic of Germany Permission hereby granted to re-distribute KeyMacro v1.8 in its entirety for non profit usage only. ============ REVISION HISTORY (most recent change first) ============= ====================================================================== V1.8 The keymap inversion routines were responsible for funny sideeffects, such as characters being swallowed instead of being fed into the input stream. It took me about three hours to figure out what a `dead key-modifiable' keymap entry is and another hour to program my own keymap reader. V1.7 Added the delay keyword and fixed a bug in KeyMacro which caused a crash if KeyMacro-Handler could not be loaded. V1.6 Thanks to user persistance KeyMacro was thoroughly revised (yes, I mean what I say!). Bert L. Allen discovered problems with the numeric key pad, Ralf Thanner suggested that I should get rid of mxm.library, Martin Berndt and Benito Lombardi made helpful suggestions. The dreaded mxm.library was finally removed, saving about 20 KByte when there is no other program to access the mxm.library routines. The routine to simulate the key events will produce a key-down followed by a key-up event. Macros will no longer invoke other macros on the way. InputEvents created by KeyMacro-Handler will have a valid timestamp. Key names are no longer abbreviated (i.e. 'f10' != 'f1'). The return key will finally work in cases where it wouldn't work in revision 1.4. V1.5 Small changes to library and code, recompiled using the new Aztec 'C' 5.0b compiler. V1.4 Wow! It works! The reasons for the constant failures were located in 1) mxm.library, 2) in the Arp wrapper for Lattice 'C', 3) in KeyMacro itself and 4) of course in KeyMacro-Handler. Needless to say, mxm.library was fixed and the code has once more changed the compiler - KeyMacro 1.4 now compiles under Aztec 5.0. Programs started by the executor-process will no longer block until the program exits. This is now probably the only input.device example program written in Aztec 'C' which doesn't use ANY inline assembly language code (#asm/#endasm). V1.3 Well, I wouldn't shoot my grandma to get it working, but it really starts to become a nuisance: 1.2 still wasn't the success I had expected. I took a second look into RKM Exec and discovered that interrupt handlers be located in public ram. As a result almost all static data declarations have been replaced by memory allocations. V1.2 I guess you know what happened: it still didn't work right. The code is now much more compact and has been recompiled using Lattice 'C' 5.04. V1.1 KeyMacro obviously worked on only one machine: my Amiga. This is the first attempt to fix it. I cleaned up the code I didn't think to be that much important which hopefully will fix the problem. V1.0 First public release; seems that it works (what did I do wrong?). * Do only its possibilities make it an Amiga? WHERE IS THE MAGIC ???