home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 372.lha / Keys_v1.05 / KeysDocs.pp / KeysDocs
Text File  |  1990-04-01  |  24KB  |  517 lines
  1. (*======================================================================*)
  2. (*   Program Name `Keys'                                                *)
  3. (*   A Macro Key/Hot Key Utility for all Amiga Computers                *)
  4. (*======================================================================*)
  5. (*   Written in M2Sprint                                                *)
  6. (*======================================================================*)
  7. (*   Copyright © 1990 E.J. Lippert II, All Rights Reserved.             *)
  8. (*   These Programs are freely redistributable as `shareware' as long   *)
  9. (*   as this file is included.                                          *)
  10. (*======================================================================*)
  11. (*   Version: 1.05                  Author : E.J. Lippert II            *)
  12. (*   Date   : 11-APR-90             Changes: None...(Yet)               *)
  13. (*======================================================================*)
  14. (*                                                                      *)
  15. (*   Shareware Registration:                                            *)
  16. (*                                                                      *)
  17. (*   Users finding this program of value may wish to become registered  *)
  18. (*   owners. Registered owners will recieve automatic notification of   *)
  19. (*   program updates and will be elligible for customer support by      *)
  20. (*   mailing their questions directly to the author. The source code    *)
  21. (*   for all modules is also available to registered owners for a       *)
  22. (*   minimal additional fee. Be sure to include your name, address      *)
  23. (*   AND the version (as shown above) of the program that you have.     *)
  24. (*                                                                      *)
  25. (*                                                                      *)
  26. (*   Send a $10.00 registration fee to:                                 *)
  27. (*                                                                      *)
  28. (*                          E.J. Lippert II                             *)
  29. (*                          4525 E. 2nd St.                             *)
  30. (*                          Wichita, Kansas                             *)
  31. (*                                    67028                             *)
  32. (*                                                                      *)
  33. (*   To recieve the complete source code include an additional $20.00   *)
  34. (*                                                                      *)
  35. (*======================================================================*)
  36.  
  37. (*************************** General Notes ******************************)
  38.  
  39. Included in this distrubition are ten files:
  40.  
  41.     Arp.Library       - the Arp.Library file
  42.     EdKeys            - an executable program
  43.     EdKeys.info       - a workbench icon for the EdKeys program
  44.     Install           - an automatic installation program
  45.     Install.info      - a workbench icon for the KeysInstall program
  46.     Keys              - an executable program
  47.     Keys.info         - a workbench icon for the Keys program
  48.     Keys.Prefs        - a file containing some macro definitions
  49.     KeysDocs          - the file you are reading
  50.     KeysDocs.info     - a workbench icon for this file
  51.  
  52. (********************* Notes About The Programs *************************)
  53.  
  54. The function of this program is to provide short-hand definitions (called
  55. `MacroKeys' or `Macro Initiators') that the user can define that will
  56. automatically type in a series of key strokes (called `Macros'), just as if
  57. they had been typed in manually.  There are two main functions involved in
  58. the creation and use of Macros/MacroKeys.  The first is the actual ability
  59. to intercept and handle the `MacroInitiator' key stroke combinations that
  60. actuate the `Macros'.  The second is the means to define the the `Macros'
  61. and assign the Macro Initiator key stroke combinations that will cause them
  62. to be sent.
  63.  
  64. In my Macro program, two programs are used to perform these two discrete
  65. functions.  The `KEYS' program is the program that intercepts and handles
  66. the `MacroInitiator' key stroke combinations.  And the EdKeys program is the
  67. program that provides the means to define the the `Macros' and assign the
  68. Macro Initiator key stroke combinations to them.
  69.  
  70.  
  71. (********************* Notes About The `Keys' Program ********************)
  72.  
  73.  
  74. Program Startup:
  75. ****************
  76.  
  77. The `KEYS' program may be initiated either from the Amiga Workbench by
  78. selecting its Icon, or from any CLI window.  When started up from the
  79. Workbench the program creates its own window which will stay active as long
  80. as the program is running.  No options are allowed when the program is
  81. started from the Workbench and the program automatically uses the
  82. `S:Keys.Prefs' file (discussed later) as its source of Macro definitions.
  83.  
  84. When started from CLI, however, the user can specify the name of the file
  85. containing the Macro definitions.  CLI operation also provides the user with
  86. the ability to set the priority of the `KEYS' program and, in fact, launch
  87. several versions of the program with different Macro definitions and
  88. priorities.  (In addition to the obvious ability to load specific Macor
  89. combinations to be used with specific programs, this feature also allows you
  90. the unique opportunity, by using the priority setting, to set up Macros that
  91. call or re-define other Marcos.)
  92.  
  93. The CLI format is:
  94.  
  95.    FORMAT:    KEYS  [path|filename]  [-priority]
  96.  
  97.    Two Command Line Options are available:
  98.  
  99. [path|filename] is an optional directory path and/or file name to be used.
  100. Unless specified in a command line argument, the Keys program will always
  101. look for the `S:Keys.Prefs' file for input.  If the input file (either
  102. `S:Keys.Prefs' or a user specified file name) is not found, the program will
  103. abort, notifying the user of the problem.
  104.  
  105. [-priority] sets the user specified of the program (ie.  where in the input
  106. chain of events the program intercepts input messages) can also be set with
  107. a command line argument in the format `-val' where the `-' is required and
  108. val is the numeric value of the priority from 0 to 255.  The priority used
  109. by Intuition is 50, so this program should be greater than 50, but less than
  110. 255 so as to allow other programs to exert a higher priority if needed.  The
  111. default priority is 60.  (NOTE:  the - (hyphen) character is required and it
  112. must directly preceed the value with no intervening spaces.
  113.  
  114.  
  115. Program Operation:
  116. ******************
  117.  
  118. While the program is active, you may temporarily inactivate the program by
  119. pressing
  120.  
  121.      <Left-Amiga><Right-Amiga><Space-Bar>
  122.  
  123. which will temporarily suspend the MacroKey functions. Pressing
  124.  
  125.      <Left-Amiga><Right-Amiga><Space-Bar>
  126.  
  127. again will re-activate the program.
  128.  
  129.  
  130. You may also remove the program entirely and clear all memory.  If the
  131. program was started fron the Workbench Icon, simply locate the program's
  132. window, click in the window to activate it and then press the <CTRL> and `C'
  133. keys.  If the program was `RUN' from CLI, from any CLI, type:
  134.  
  135.      Break <TASK> ALL  <RETURN>
  136.  
  137.  Where <TASK> is the task number assigned to the program.
  138.  
  139.  
  140.  
  141. (******************* Notes About The `EdKeys' Program ********************)
  142.  
  143.  
  144. Program Startup:
  145. ****************
  146.  
  147. The `EdKeys' program may be initiated either from the Amiga Workbench by
  148. selecting its Icon, or from any CLI window.  When started up from the
  149. Workbench the program creates its own window which will stay active as long
  150. as the program is running.  No start-up options are available from either
  151. the Workbench or CLI start-up.
  152.  
  153.  
  154. NOTE:  The EdKeys program is just beginning to take shape and is still
  155.        missing a lot of features.  Please bear with me as I work through it
  156.        as the end results should, with your help and feed back, be worth
  157.        the effort.
  158.  
  159.  
  160. Program Operation:
  161. ******************
  162.  
  163. When you first start-up the EdKeys program you will be presented with the
  164. Main program window.  (This is actually two windows overlayed.) At the top
  165. of the window there are several gadgets.  From this window you may select
  166. any of these gadgets.  The following is a description of each gadget and a
  167. sub-description of the functions available after the gadget is selected.
  168.  
  169.  
  170. N/A
  171. ***
  172.  
  173. The first gadget is reserved for future use and is not yet defined.
  174.  
  175.  
  176. N/A
  177. ***
  178.  
  179. The second gadget is also reserved for future use and is not yet defined.
  180.  
  181.  
  182. Print
  183. *****
  184.  
  185. One of the problems I have with Macros is that I forget them!  I even used
  186. to write out a list and keep it by my computer.  This program provides you
  187. with the ability to get a printed list of all available macros.  If you
  188. prefer you can route the list to a file which can then be edited and printed
  189. out in whatever format you are most comfortable with.
  190.  
  191. When you select the `PRINT' gadget from the main window, you will be
  192. presented with a file requester with the text `PRT:' in the area normally
  193. used to display the selected directory path.  If you simply select the
  194. `O.K.' gadget, the list of macros will be sent to your printer.
  195. Alternatively, you could provide a directory path and filename in the
  196. appropriate areas of the requester.  In this case, the list will be sent
  197. (fully formatted) to the filename specified.
  198.  
  199.  
  200. D-KEY
  201. *****
  202.  
  203. This function is not yet implemented, but when completed, will allow you to
  204. re-assign key values.
  205.  
  206.  
  207. ADD
  208. ***
  209.  
  210. This is the Gadget to select when you want to create a new list of Marcos or
  211. ADD Macros to an existing list.  Selecting this gadget will bring up the
  212. ADD-A-MACRO function window.  To add a Macro to an existing list of Macros
  213. you should have used the `LOAD' gadget (discussed later) to load the file
  214. that contains the list of Macros to be extended.  If no existing list of
  215. Marcos is present, a new list will be started automatically.
  216.  
  217. The ADD-A-MACRO function window provides an easy method of selecting the
  218. keystroke combinations that will define the Macro Initiator for the Macro to
  219. be defined.  A Macro Initiator has two parts, one part is the actual
  220. `Initiator' key that must be pressed to initiate the Marco and the second is
  221. a list of quafifying keys (there are 8 `Qualifiers' and they are `CTRL'
  222. `Left Shift' `Left Alt' `Left Amiga' `Right Shift' `Right Alt' `Right Amiga'
  223. and `Caps Lock') that must also be held down at the time you press the
  224. Initiator key.  This system allows you to define Macros for ANY key on the
  225. keyboard (except the `Qualifier' keys) and actually assign several macros to
  226. the same key.  For example, you could assign a macro to the `F1' function
  227. key that activates every time the `F1' key is pressed, but if you hold down
  228. ANY of the `Qualifier' Keys the Macro will not be executed.  You could then
  229. assign another Macro to the `F1' key that only executes when the `CTRL' key
  230. (but ONLY the `CTRL' key) is being held down, and yet another Macro could be
  231. assigned to the `Left Shift' `Right Alt' and `F1' key combination.  With 8
  232. available qualifiers, theoretically, over 1600 `Qualifier' combinations are
  233. possible for EVERY key on your keyboard.  In reality several combinations
  234. can't be used because they are just to awkward and others may cause unwanted
  235. results (among other oddities, any combination that includes `Left Amiga'
  236. `Right Amiga' and `CTRL' will cause your Amiga to re-boot), but you have
  237. over 200 valid possible Qualifier' combinations for each Initiator key.
  238.  
  239. NOTE:  The `Caps Lock' key on all key boards acts like an on-off switch,
  240. pressing it down and releasing it sets the Caps Lock function on, Pressing
  241. and releasing it again turns the Caps Lock function off.  You DO NOT have to
  242. hold the `Caps Lock' Qualifier key down to use it as a Qualifier.  If the
  243. Caps Lock function is on (ie.  pressing and releasing the key) is all that
  244. is necessary.  The Caps Lock and Shift keys DO NOT perform the same
  245. function, you can use both as `Qualifiers', for example `Caps Lock' `Left
  246. Shift' `F1'.  This means that you could really re-define your entire
  247. keyboard (as a Dvorak Keyboard for exapmle) when the `Caps Lock' function is
  248. active, leaving the keyboard totally normal at all other times.
  249.  
  250. From the ADD-A-MACRO window you MUST select an `Macro Initiator' and you may
  251. select any optional `Qualifiers' to be used with the `Macro Initiator'.  To
  252. select the `Qualifiers', select one or more of the eight qualifiers using
  253. either the mouse to click on the appropriate gadget, or by pressing and
  254. releasing the corresponding `Qualifier' key.  A list of the currently
  255. selected qualifiers is displayed in the cetner of the cluster of `Qualifier'
  256. gadgets.  You may de-select a selected qualifier (delete it from the list of
  257. selected `Qualifiers') by using either the mouse to click on the appropriate
  258. gadget, or by pressing and releasing the corresponding `Qualifier' key.
  259.  
  260. To specify the `Macro Initiator' used to trigger this Macro, simply press
  261. and release the desired key.  The `Macro Initiator' can be any key on the
  262. keyboard other that the 8 `Qualifier' keys.  When any key is pressed, the
  263. key will be diplayed just below the type that says `Press The Macro
  264. Initiator Key'.  To change to another key simply press another key.
  265.  
  266. When you have completed the set-up of you `Macro Initiator' select (using
  267. your mouse) the `O.K.' gadget.  If you decide to abort the ADD-A-MACRO
  268. function, you can do so by selecting the `CANCEL' gadget.  Several methods
  269. of error checking, including checking for duplication of Macro Initiators,
  270. has been implemented which, hopefully, will prevent any undesirable effects.
  271.  
  272. If you did not abort the ADD-A-GADGET function, you will be dropped back to
  273. the main screen which will be used to enter the `body' text of your Macro
  274. definition.  The `body' of the Macro definition is the series of key strokes
  275. that will be sent whenever the Macro Initiator key combination is pressed.
  276. A Macro definition may be as simple as one key press, or may include up to
  277. 125 key strokes.  (The 125 key stroke limit was put on the definition by me
  278. to simplify programming, but because Macros can call other Macros when
  279. running two copies of the program concurrently, there is really no limit on
  280. the length of a Macro.)
  281.  
  282. Because any key on the keyboard including `delete' `backspace' `RETURN'
  283. `HELP' et al can be included in the `body' of the Macro definition, and
  284. because I haven't finished the `Editor' section of this program yet, there
  285. is CURRENTLY no capability to edit or correct mistakes made during the entry
  286. of a Macro definition.  Be careful when you are entering long Macro
  287. definitions.
  288.  
  289. All keyboard input consists of distinct key-down/key-up actions.  As you
  290. enter your Macro definition you will notice that when you press a key down
  291. it is immediatly displayed on the screen.  Normal characters are displayed
  292. as normal characters and special keys are shown by pneumonic representa-
  293. tions like <BS> for the `backspace' key and <SPC> for the Space Bar.  When,
  294. however you release the key an inverse video version of the key is printed
  295. to the screen.  (Note:  Blank spaces are added for readability and will not
  296. be present in the actual Macro definition.) For example, typing an upper
  297. case `S' will result in a screen display of:
  298.  
  299.        <LShft> s `s' `<LShft>'  ;NOTE: `s' signifies inverse video s.
  300.  
  301. Notice that the s character is lowercase, this is the way it is supposed to
  302. be, because when the Macro is played back, the computer will actually be
  303. sent a key-down for the left-shift key followed by a key-down for the s key
  304. before the key-up for the left-shift is recieved which will cause an upper
  305. case S as the result.
  306.  
  307. If you try to enter more that 125 keystrokes (250 key-down/key-up)
  308. combinations the keyboard will simply not register the additional
  309. keystrokes.  (I intend to add a warning here, but haven't done so yet.)
  310.  
  311. When you have completed entering your Macro definition, use your mouse to
  312. select the `ADD' gadget to add the Macro to the list.
  313.  
  314. After completing the Add function you will remain in the Main screen, but
  315. all of the Function gadgets will again be activated.
  316.  
  317.  
  318. EDIT
  319. ****
  320.  
  321. This function is not yet implemented, but when completed, will allow you to
  322. EDIT (modify) existing Macros.
  323.  
  324.  
  325. KILL
  326. ****
  327.  
  328. From time to time it is necessary to delete one or more macros, the `KILL'
  329. gadget is supplied as the tool to be used eliminate unwanted macros.  When
  330. the `KILL' gadget is selected the Kill-A-Macro window is displayed over the
  331. main window.  The Kill-A-Macro window works just like the Add-A-Macro window
  332. described earlier.  To delete a macro simply provide the Initiator and the
  333. Qualifiers that comprise the Macro Initiator for the Macro that you want to
  334. delete and then select the `O.K.' gadget.  If deletion of the specified
  335. Macro is successful the Kill-A-Macro window will go away and you will be
  336. returned to the main window.  If a Macro Initiator that exactly matches the
  337. specifications you provided cannot be located a warning will be provided and
  338. the Kill-A-Macro wimdow will remain active.
  339.  
  340. ASCII
  341. *****
  342.  
  343. This function is not yet implemented, but when completed, will allow you to
  344. select an ASCII representation (as opposed to the key-down/key-up represen-
  345. tation) of the Macro definiton being edited or created.  This format will
  346. allow easier viewing of the Macro definition, but you will probably not be
  347. able to edit the Macro definition while in the ASCII display format.
  348.  
  349.  
  350. CODES
  351. *****
  352.  
  353. This function is not yet implemented, but when completed, will allow you to
  354. select the key-down/key-up representation of the Macro definiton being
  355. edited or created.  NOTE:  This is the default mode of the display and will
  356. only become necessary when the `ASCII' display function is completed and can
  357. be selected.
  358.  
  359.  
  360. LOAD<
  361. *****
  362.  
  363. Selecting this gadget brings up the `world renowned' ARP File Requester with
  364. which every one should be familiar by now.  Select the file to load and you
  365. are on your way, but because the EDIT and KILL functions are not yet active,
  366. this function can only be used to load files to which you want to ADD
  367. additional Macros.
  368.  
  369.  
  370. >SAVE
  371. *****
  372.  
  373. This gadget also brings up the `world renowned' ARP File Requester.  Give
  374. the file you want to save a name and you are on your way.  Two items of
  375. interest here, first I DID NOT put in any thing to prevent you from, or warn
  376. you about saving a file over an existing file with the same name so it is
  377. your responsibility to save with care.  Second, until the EDIT function is
  378. complete, I left in a little diagnostic routine that displays the Macro
  379. Initiators, the Attribute value and the Macro definition on their way to the
  380. disk.  (Use the Right Mouse button to freeze the display.) Although somewhat
  381. awkward this will at least allow you to see what's there.
  382.  
  383.  
  384. (********************* Notes About The `Keys.Prefs' file *****************)
  385.  
  386.  
  387. Three sample Macros are included in the Keys.Prefs file provided
  388. with this distribution.
  389.  
  390. Initiator:          Macro Definition:
  391.  
  392. <RShft><RAlt>D      sys:system/diskcopy DF0: to DF1: <RETURN>
  393.  
  394. <LShft><LAlt>D      sys:system/diskcopy DF1: to DF0: <RETURN>
  395.  
  396. <RShft><RAlt>E      ed s:startup-sequence <RETURN>
  397.  
  398.  
  399. Looking at the file with a file editor will show that:
  400.  
  401.  
  402. Byte 0 - 3     = 1st Macro Descriptor
  403.    Byte 0      = Offset <n> to Start of next Macro
  404.    Byte 1      = Macro Input Event Key Code
  405.    Byte 2,3    = Input Event Qualifier Set
  406. Byte 4..n-1    = 1st Macro of n-4 Bytes of key-dn/key-up codes
  407.  
  408. Byte n - n+3   = 2nd Macro Descriptor
  409.    Byte n      = Offset <m> to Start of next Macro
  410.    Byte n+1    = Macro Input Event Key Code
  411.    Byte n+2,3  = Input Event Qualifier Set
  412. Byte n+4..m-1  = 2nd Macro of m-n-4 Bytes of key-dn/key-up codes
  413.  
  414. Byte m - m+3   = 2nd Macro Descriptor
  415.    Byte m      = Offset <p> to Start of next Macro
  416.    Byte m+1    = Macro Input Event Key Code
  417.    Byte m+2,3  = Input Event Qualifier Set
  418. Byte m+4..p-1  = 2nd Macro of m-p-4 Bytes of key-dn/key-up codes
  419.  
  420.  
  421. The Offset byte of the last Macro should be 0 indicating no more Macros.
  422.  
  423. Input Event Qualifier Set Bits:
  424.  
  425. Byte 3
  426.  
  427. Bit 8  = Numeric Pad,           If desired add            1
  428. Bit 9  = Repeat,                If desired add            2   (Never Set)
  429. Bit 10 = Interrupt,             If desired add            4   (Never Set)
  430. Bit 11 = MultiBoradcast,        If desired add            8   (Never Set)
  431. Bit 12 = Mid Mouse Button,      If desired add           16   (Never Set)
  432. Bit 13 = Right Mouse Button,    If desired add           32   (Never Set)
  433. Bit 14 = Left Mouse Button,     If desired add           64
  434. Bit 15 = Relative Mouse,        If desired add          128   (Never Set)
  435.  
  436.  
  437. Byte 4
  438.  
  439. Bit 0  = Left Shift,            If desired add           1
  440. Bit 1  = Right Shift,           If desired add           2
  441. Bit 2  = CapsLock Shift,        If desired add           4
  442. Bit 3  = Control Shift,         If desired add           8
  443. Bit 4  = Left Alt,              If desired add          16
  444. Bit 5  = Right Alt,             If desired add          32
  445. Bit 6  = Left Amiga,            If desired add          64
  446. Bit 7  = Right Amiga,           If desired add          128
  447.  
  448. SPECIAL NOTE: If bytes 3 and 4 are both set to 255, all qualifiers will
  449.               be ignored, this allows the simple re-definition of a key
  450.               like the >< key used in the example above and will allow
  451.               it to act like any other key with LSHIFT/LALT/LAMIGA etc.
  452.               without having to define a special case for each qualifier.
  453.  
  454.               If bytes 3 is set to 255 and 4 to 254, all qualifiers will
  455.               be ignored and WILL NOT have any effect on the resulting
  456.               output character. For example defining the s key as Left
  457.               Shift-S with these qualifier values will cause an upper-
  458.               case S to be output any time the s key is pressed..
  459.  
  460.  
  461.  
  462. NOTE: Over 100,000 potential MacroKey combinitations can be defined.
  463.       Program artificially limits total available Macro Storage to 32K.
  464.       Only 4 Bytes of overhead is required for each key combination.
  465.  
  466. Final Note:  The Last Macro MUST be terminated with a CHR(0)!
  467.  
  468.  
  469.  
  470.  
  471.                   ************************************
  472.                   *                                  *
  473.                   *  Changes Documented in REV 1.06  *
  474.                   *                                  *
  475.                   ************************************
  476.  
  477.  
  478. (*======================================================================*)
  479. (*   Version: 1.06                  Author : E.J. Lippert II            *)
  480. (*   Date   : 14-APR-90             Changes: None...(Yet)               *)
  481. (*======================================================================*)
  482.  
  483.  
  484.  
  485. NOTE:  ALL REV 1.06 CHANGES HAVE BEEN INCORPORATED INTO THE ABOVE TEXT.
  486.        The entries below are sinply to provide documentation of the 
  487.        changes made from version 1.05 to 1.06
  488.  
  489.  
  490. Changes to KEYS Program:
  491. ************************
  492.  
  493. Added HotKey:    <Left Amiga> <Right Amiga> <RETURN> 
  494.  
  495. This key combination can now be used to totally remove the KEYS program
  496. from the system, flushing all buffers and freeing all memory.
  497.  
  498.  
  499. Changes to EdKeys Program:
  500. **************************
  501.  
  502.  
  503. Added ` N/A ' gadget to main window.
  504. Added ` N/A ' gadget to main window.
  505. Added `PRINT' gadget to main window.
  506. Added `D-KEY' gadget to main window.
  507.  
  508. Activated `KILL ' gadget allowing deletion of existing Macros.
  509. Activated `PRINT' gadget allowing printing of a formatted list of
  510.   currently existing Macros to either PRT: or to a specified file.
  511. Added error checking to the ` ADD ' function to prevent the creation
  512.   of a Macro Initiator that duplicates an existing Macro Initiator.
  513.  
  514.  
  515.  
  516.       --------------------- END OF FILE ------------------------
  517.