home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 575.lha / ToolsX_v1.00 / ToolsX.doc.pp / ToolsX.doc
Text File  |  1991-12-06  |  9KB  |  217 lines
  1.  
  2.  
  3.                   ToolsX and ToolsXConfig Documentation
  4.  
  5.                            by Steve Tibbett
  6.  
  7.                  Version 1.00
  8.  
  9.  
  10.  
  11. NOTICE
  12.  
  13. ToolsX and ToolsXConfig (TX and TXC from now on) are programs meant
  14. for use under Kickstart 2.0 and are totally useless under 1.3.  
  15.  
  16.  
  17. OVERVIEW
  18.  
  19. These two programs let you add items to the 2.0 Workbench TOOLS menu.
  20. The items you add to the menu can also have a Hotkey associated with
  21. them, provided the commodities library is available.  (It normally is
  22. under 2.0 unless you erase it).
  23.  
  24. ToolsX is meant to be put in your WBStartup drawer and forgotten.  It
  25. will read the environment variable that ToolsXConfig creates, 
  26. and adds the items to the Tools menu.  It then goes to sleep waiting
  27. for either menu selections, or hotkeys to be hit.
  28.  
  29. ToolsXConfig is where you define what ToolsX is going to do.  You can
  30. add menu items, delete them, assign hotkeys, stack size, and home
  31. directory, to each menu item.  
  32.  
  33.  
  34. FEATURES
  35.  
  36.     - Allows you to put menu items on the Workbench
  37.         Tools menu.
  38.  
  39.     - Lets you attach a hotkey to each of the menu items.
  40.  
  41.     - Uses Commodities - the hotkeys use standard commodities
  42.       definitions and ToolsX can be controlled via Exchange.
  43.  
  44.     - Gives a proper path to spawned programs even if ToolsX
  45.       is started from the WBStartup drawer.
  46.  
  47.     - Very easy to install
  48.     
  49.     - Graphic user interface for editing tools menu items.
  50.  
  51.     - Allows you to specify a home directory and a stack size
  52.       for each individual menu item.
  53.  
  54.  
  55. INSTALLATION
  56.  
  57. Drag ToolsX's icon into your WBStartup drawer on your System partition
  58. or floppy, and put ToolsXConfig somewhere convenient.  The Prefs drawer
  59. would be a logical place for it to live, or perhaps in the Tools directory.
  60.  
  61. Now run ToolsXConfig and add the items to the tools menu that you
  62. want to be there.  Exactly how to do this is described in the section
  63. on ToolsXConfig, but the program has a graphic user interface that you
  64. should be able to use without having to read the documentation.
  65.  
  66. I have also included a very simple ToolsList containing just a 
  67. single menu item which starts a Shell window when you select it from
  68. the menu, or press Control-Shift-F1.  If you want to use this, copy 
  69. it to ENV:ToolsList before starting ToolsXConfig or ToolsX.
  70.  
  71.  
  72. TOOLSX
  73.  
  74. ToolsX reads the file "ENV:ToolsList", and adds the tools to the tools
  75. menu that the file specifies.  The "ENV:ToolsList" is created by
  76. >ToolsXConfig.
  77.  
  78. ToolsX can be placed in your WBStartup drawer.  This is the best way
  79. to run it, as everything in the WBStartup Drawer is automatically loaded
  80. when you reboot, by Workbench.  ToolsX has code in it (supplied by Mike
  81. Sinz) to get a proper path, so shells launched from ToolsX will have
  82. the proper path.  (Normally programs started from WBStartup do not
  83. have a path).  If you are just using Workbench, the path is of no 
  84. concern to you.
  85.  
  86.  
  87. TOOLSXCONFIG
  88.  
  89. This program is how you talk to ToolsX.  When you run this program, 
  90. it will open a window with a scrollable list in the center of the
  91. window showing you the tools currently in the list, and gadgets for
  92. adding, deleting, and editing existing tools.  There are also 3
  93. gadgets at the bottom of the window for Save, Use, and Cancel.
  94.  
  95. There are two ways to add items to the list.  One is to click on
  96. Add, and fill in the requester that will pop up asking for the
  97. Title (the text that goes into the menu), the command itself, what
  98. directory the command will be executed from, the hotkey that will
  99. activate this item (or an empty string for no hotkey), and the
  100. stack size.
  101.  
  102. The other way is to just drop a Workbench icon into the TXC window!
  103. The program that the icon would call up if you double-clicked it
  104. will be in the Command field, the name of the icon will be the
  105. Title, and the stack size and directory will come from the icon.
  106.  
  107. When you select SAVE, the ToolsList file is written to ENV: and
  108. to ENVARC: where it will be stored permanently.  (The standard 2.0
  109. startup-sequence copies the environment variables from ENVARC: to
  110. ENV:).  Selecting USE will save the ToolsList to ENV: only - not to
  111. ENVARC:, so the changes will only last until you reboot.
  112.  
  113. When ToolsXConfig exits, it signals ToolsX (if it's running) that
  114. it should take another look at the ToolsList file.  This way, your
  115. changes take place as soon as you select SAVE or USE, rather than
  116. having to reboot to see them.
  117.  
  118. In the requester where you edit or add new tools, there are 5 fields
  119. that you can fill in.  The first one, "Title: ", is informational
  120. only - this is the text that shows up in the Tools menu.
  121.  
  122. The next field, the "Command: " field, is the name of the program 
  123. to load when this item is selected.  The command's current directory
  124. when it is started will be the "Directory: " field - so if you want
  125. to add "DPaint" as the Command, and DPaint was in WORK:DeluxePaint,
  126. then you could set the Directory: to WORK:DeluxePaint.  Or you 
  127. could put WORK:DeluxePaint/DPaint as the Command: and have
  128. WORK:Pictures as the Directory.  The latter way would have the 
  129. WORK:Pictures directory be DPaint's current directory, so when
  130. it opens a file requester, it would show that directory.
  131.  
  132. If you select a command's menu item with one or more Workbench
  133. icons already selected, then those icons will be the arguments
  134. for the command being started.  If the command has a "%s" anywhere
  135. in it, then the %s will be replaced with the name of a single
  136. command - if the command has a %l in it, it will be replaced with
  137. a list of ALL the icons currently selected.
  138.  
  139. For example, if you select IconOne, IconTwo and IconThree and select
  140. a tool menu item whose command is 'Echo %s', then it would behave
  141. as if you had typed 'Echo "IconOne"' and then 'Echo "IconTwo"' and then
  142. 'Echo "IconThree"' - the command is started once for each selected
  143. icon.  If the command was 'Echo %l' then it would be as though you
  144. had typed 'Echo "IconOne" "IconTwo" "IconThree"' from the CLI.
  145. (Note that the arguments that ToolsX inserts are always quoted).
  146.  
  147. The Stack: field will be the stack size for the program being
  148. started.  If you don't know what to put here, put in a number
  149. like 8192 - some programs need more stack.  If a program crashes
  150. randomly, increasing the stack may help.  
  151.  
  152. The Hotkey: field is where you specify what keystroke you want 
  153. to start this program.  These are global - no matter what window you
  154. are currently working in, if you hit this keystroke, then this
  155. program will be started.  Be careful to avoid conflicts with keystrokes
  156. your normal programs may use.
  157.  
  158. The strings that you can put here to say what key you want to use
  159. are documented in the AmigaDOS manual, in the section on commodities.
  160. If any of your menu items have a hotkey, then ToolsX becomes a
  161. commodity - running Exchange will show ToolsX and let you Enable,
  162. Disable, and Kill it off.
  163.  
  164.  
  165. ADDTOOLS
  166.  
  167. If you used my earlier AddTools program, then you've probably got
  168. a ToolsList in your S: directory.  To update this to the new format
  169. that ToolsX uses, simply add two blank lines after each entry.  You'll
  170. have to save this new file to ENV: and to ENVARC:.
  171.  
  172. (AddTools used 3 lines for each menu item, ToolsX uses 5).  
  173.  
  174. ToolsX is AddTools with the 3 most requested features added:  Hotkeys,
  175. a GUI, and an X on the end of the name.  8-)
  176.  
  177.  
  178. QUITTING
  179.  
  180. There are two ways to quit ToolsX.  One is to find it's task and
  181. send it a BREAK signal - if you have run ToolsX from the WBStartup
  182. drawer (as you should!), then the tools that come with AmigaDOS 
  183. will not let you send it a Break signal.
  184.  
  185. But if any of your menu items have a hotkey, then you can run
  186. the Exchange program (in the Utilities directory of your Workbench
  187. disk), and it will show you ToolsX in it's list of commodities.
  188. Select ToolsX, and select "Kill" and all the ToolsX-added tools 
  189. will disappear from the Tools menu, and ToolsX will exit.
  190.  
  191.  
  192. CREDITS
  193.  
  194. Thanks go to Craig Dorrell, Jim Ogilvie, and Ken Robinson, for
  195. testing and suggestions, and to Mike Sinz for the WB2CLI() code that
  196. lets ToolsX have a proper path even when started from the 
  197. WBStartup drawer.
  198.  
  199.  
  200. THE AUTHOR
  201.  
  202. You can reach me via Portal (SteveX), Usenet (SteveX@cup.portal.com),
  203. my BBS (613-731-3419), or voice phone (613-731-5316).
  204.  
  205. Since you're obviously using 2.0 if you're using ToolsX, look for
  206. other 2.0-enhancing programs by the same author.  PointerX puts
  207. a spin on the Workbench Busy pointer's clock, and AssignX will
  208. add an "Assign..." and "Mount" buttons to the "Retry" and "Cancel"
  209. buttons on those pesky "Please insert volume..." requesters.
  210.  
  211.  
  212. COPYRIGHT
  213.  
  214. These programs are Copyright 1991 by Steve Tibbett.  These programs
  215. may be freely distributed, unaltered.
  216.  
  217.