home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD2.img / d4xx / d476 / toolmanager / toolmanager.doc < prev    next >
Text File  |  1991-04-17  |  12KB  |  278 lines
  1. Documentation for ToolManager 1.3                                   13.03.1991
  2.  
  3. NOTE to first time users: Please read the entire document!
  4.  
  5. NOTE to users of ToolManager 1.0-1.2: This version contains MANY changes and
  6.                                       enhancements, so please re-read the
  7.                                       entire document!
  8.  
  9. This program is freeware, but copyrighted by me. This means that you can copy
  10. it freely as long as you don't ask any more money for it than a nominal fee for
  11. copying. THIS APPLIES TO GERMAN PD DEALERS TOO!!! This program may be put on PD
  12. disks, especially on Fred Fish's AmigaLibDisks. If you want to distribute this
  13. program you should keep this document and the source code with it. Program,
  14. document and source code must be distributed in their original unmodified form.
  15. Of course you can use an archiver like LHarc to make it available to Mailboxes
  16. and FTP sites. This program cannot be used for commercial purposes without
  17. written permission from the author. The author can not be made responsible for
  18. any damage which is caused by using this program.
  19.  
  20. This is program is freeware, so you don't have to spend a buck for it. But
  21. this program has costed me a lot of time (and sweat) to create it (especially
  22. the version 1.3), so the only thing that I demand for it is, that you sent me
  23. a note if you are using ToolManager.
  24.  
  25. Send comments, suggestions or bug reports to:
  26.  
  27.    Snail : Stefan Becker, Holsteinstrasse 9, 5100 Aachen, GERMANY
  28.    Domain: stefanb@cip-s01.informatik.rwth-aachen.de
  29.    Bang  : ..mcvax!unido!rwthinf!cip-s01!stefanb
  30.    FIDO  : 2:242/7.6
  31.  
  32.  
  33.  I. What is ToolManager?
  34.  
  35. With ToolManager you can add your own programs to the Tools menu of the 2.0
  36. Workbench. The programs can now be started by selecting their entries in the
  37. Tools menu. The user can select icons from the Workbench, which will be the
  38. startup parameters for a tool.
  39.  
  40. BEWARE: This program makes heavely use of the new 2.0 functions, so its
  41.         completely useless to all people who are still forced to use 1.3 :-)
  42.  
  43.  
  44.  II. How to start ToolManager
  45.  
  46. ToolManager can be started from the CLI or the Workbench:
  47.  
  48.    CLI:   Run ToolManager [options] [<program 1>] ... [<program n>]
  49.  
  50.     Options: '-n'        Don't show the icon
  51.              '-f <name>' Read "name" as configuration file instead of
  52.                          "S:ToolManager.config"
  53.  
  54.     The name of program x will also be the name of its corresponding menu item.
  55.     All programs will be added as CLI tools.
  56.  
  57.     NOTE: If you want to start ToolManager at boot time, you can add the
  58.           following line to your S:Startup-Sequence:
  59.  
  60.                Run >NIL: ToolManager [parameters...]
  61.  
  62.     NOTE: For a quick reminder of this options type: ToolManager ?
  63.  
  64.    Workbench:   <Click on ToolManager's icon>
  65.                 [<Click on program 1's icon>] ...
  66.                 [<Double click program n's icon>]
  67.  
  68.     ToolTypes: 'SHOWICON=NO|YES' Don't show the icon
  69.                'INTERNALICON'    Use the internal icon instead of the startup
  70.                                  icon
  71.                'CONFIG=<name>'   Read "name" as configuration file instead of
  72.                                  "S:ToolManager.config"
  73.  
  74.     If you selected a Tool icon, its name will also be the name of the menu
  75.     item. If you selected a Project icon, the icon name will be the name of the
  76.     menu entry. The default tool of this icon will be called if the menu item
  77.     is selected. All programs will be started as WB tools.
  78.  
  79.     NOTE: If you want to start ToolManager at Workbench startup time, move its
  80.           icon into the Wbstartup drawer and add the ToolType 'DONOTWAIT' to
  81.           it. ToolManager uses the icon from which it was started as its icon,
  82.           if you don't set the 'INTERNALICON' ToolType.
  83.  
  84. After startup you will notice additional entries in the Workbench Tools menu
  85. and a neat icon on the Workbench (if you don't disable it). To stop ToolManager
  86. you can select the menu entry "Quit ToolManager" or send a break signal to his
  87. process.
  88.  
  89. NOTE: You can't exit ToolManager if a Workbench tool is still running.
  90.       ToolManager will flash the screen if you try it.
  91.  
  92.  
  93.  III. The configuration file
  94.  
  95. After processing the startup parameters, ToolManager reads the configuration
  96. file. It is normally called "S:ToolManager.config", but this can be overriden
  97. by the CLI Parameter '-f' or the WB Parameter 'CONFIG'. The file consists of
  98. lines which look like this:
  99.  
  100.    <Keyword>:<Parameters>
  101.  
  102.    ICON:<x>,<y>
  103.     Set the position of the program icon to (x,y)
  104.  
  105.    CLI:<Menu entry name>[;<Real program name>]
  106.     Add a CLI tool. If only one name is given, it will be the name of the menu
  107.     entry and also of the program to be called for this entry. If two names are
  108.     given, the first will be the name of the menu entry and the second one will
  109.     be the name of the program to be called. You can add any command line
  110.     parameters after the program name.
  111.  
  112.     NOTE: If the program name contains spaces (e.g. ram disk:prog) you MUST
  113.           enclose it with double quotes (e.g. "ram disk:prog")
  114.  
  115.    WB:<Menu entry name>[;<Real program name>]
  116.     Add a WB tool. For the names apply the same rules as stated above.
  117.  
  118.     NOTE: You MUST supply an absolute path name for WB tools, otherwise
  119.           ToolManager can't find the executable.
  120.  
  121.     NOTE: It is not possible to supply command line parameters for a WB tool.
  122.  
  123. To create a dummy entry without function for "aesthetic" reasons, use the
  124. following configuration line. Note that the trailing semicolon is mandatory.
  125.  
  126.    CLI:<Dummy menu entry name>;
  127.  
  128. EXAMPLES:
  129.  
  130.    ICON:200,10
  131.    CLI:Editor
  132.    CLI:Edit Text;Ed
  133.    CLI:Blanker off;DMouse -s0
  134.    WB:C:DME                      (not really useful)
  135.    WB:Edit Text;C:DME
  136.  
  137. For more examples please look into the supplied configuration file.
  138.  
  139.  
  140.  IV. How to use ToolManager
  141.  
  142. When ToolManager is active, you can see additional entries in the Workbench
  143. Tools menu. To start a tool you select its entry. Easy, isn't it? You can also
  144. select some icons on the Workbench to supply the tool with parameters.
  145. ToolManager supports two different startup methods for tools:
  146.  
  147.    CLI startup
  148.     The tool is started as a CLI process. The selected icons will be converted
  149.     to file names, which are then joined with the tool name to a CLI command
  150.     line. The system default stack size will be used to run the tool.
  151.  
  152.     NOTE: There is a limitation of 256 characters for the resulting command
  153.           line.
  154.  
  155.    Workbench startup
  156.     The tool is started as a Workbench process. If an icon exists for the tool,
  157.     ToolManager will read the ToolWindow definition and the stack size from it.
  158.     If no icon can be found, the ToolWindow will be empty and a default stack
  159.     size of 4096 Bytes is used. The selected icons will be directly passed to
  160.     the tool.
  161.  
  162. There are two special menu entries. The first one is "Quit ToolManager", which
  163. causes ToolManager to quit if you select it. The second one is "Open TM Window",
  164. which causes ToolManager to open its status window. You can also open this
  165. window by double-clicking the program icon.
  166.  
  167. To add a new tool, you just drag a Tool (or Project) icon on ToolManager's icon
  168. or on the status window and it will be added as a WB tool. If you start
  169. ToolManager a second time, it will pass its startup parameters to the already
  170. running ToolManager process. They will be added as WB tools if an icon exists
  171. for them, otherwise as CLI tools.
  172.  
  173. The status window contains a list of all menu entries and allows you to
  174. manipulate them. You can select a tool by clicking on its name in the list.
  175.  
  176.    Remove Tool
  177.     Remove the selected icon.
  178.  
  179.    Edit Tool Definition
  180.     A new window will open, which shows the actual definition of the selected
  181.     tool. It is displayed in the same format which is used in the configuration
  182.     file. You can now change the definition. If you press the return key, the
  183.     changes will be taken over by ToolManager. To cancel your action, click on
  184.     the close gadget of the window.
  185.  
  186.     NOTE: The changed menu entry will be added to the END of the list. This
  187.           is because 2.0 provides no choice where to put the menu entry.
  188.  
  189.    Save Configuration
  190.     A file requester will open, in which you can select the name of the
  191.     configuration save file. If you click on the OK gadget, ToolManager will
  192.     write its actual configuration on this file. Workbench tools will be
  193.     converted to absolute path names, so they can be found the next time you
  194.     read in the configuration file,
  195.  
  196. You can close the status window by clicking its close gadget. It will remember
  197. its current screen position for the next time you open it.
  198.  
  199.  
  200.  V. Caveats
  201.  
  202. If you start a program as Workbench tool and it immediately crashes with a
  203. GURU #87000004, then the startup code of this program contains a bug. This
  204. happened to me as I tried to start programs which were compiled with DICE. I
  205. have informed Matt Dillon and he told me that it will be fixed in the next
  206. release.
  207.  
  208. The configuration files of version 1.0-1.2 will NOT be recognized by the new
  209. version 1.3. Please re-read the corresponding chapter for the changes.
  210.  
  211. Now to some weird things, that are NOT bugs or 'undocumented features' of my
  212. my program:
  213.  
  214.  - The Workbench seems not to support multiple menu selects.
  215.  
  216.  - The Workbench looses menu select events if a disk is inserted. So if you
  217.    insert a disk and select a tool at the same time, the tool will NOT be
  218.    started, because ToolManager didn't receive a menu event.
  219.  
  220.  
  221.  VI. How to compile ToolManager
  222.  
  223. This program was developed with DICE (nice job Matt!). You will need the
  224. registered version, because I used the __chip keyword, but DICE is worth its
  225. $50 anyway. Of course you need the 2.0 include files and the 2.0 amiga.lib.
  226.  
  227.  
  228.  VII. TODO
  229.  
  230.  - Better looking internal icon (hey, I'm not a painter :-)
  231.  - "About" menu entry with a super MEGA demo, containing astonishing 2D & 3D
  232.    graphics and 16 Bit digitized stereo sound (Hi Juergen :-)
  233.  
  234.  
  235.  VIII. HISTORY
  236.  
  237. 1.3: Release version (13.03.1991)
  238.    - Now supports different configuration files
  239.    - Format of the configuration file slightly changed
  240.    - Tool definitions can be changed at runtime
  241.    - Now supports CLI & Workbench startup method
  242.    - Selected icons are passed as parameters to the tools
  243.    - Now uses the startup icon as program icon if started from Workbench
  244.    - The position of the icon can now be supplied in the configuration file
  245.    - The program icon can now be disabled
  246.    - New menu entry "Show TM Window"
  247.    - Every new started ToolManager passes its startup parameters to the
  248.      already running ToolManager process
  249.  
  250. 1.2: Release version (12.01.1991)
  251.      (First version to appear on a Fish disk: #442)
  252.    - Status window changed to a no-GZZ & simple refresh type
  253.      (this should save some bytes)
  254.    - Status window remembers its last position
  255.    - New status window gadget "Save Configuration": saves the actual tool
  256.      list in the configuration file
  257.    - Small bugs removed in the ListView gadget handling
  258.    - Name of the icon hard-wired to "ToolManager"
  259.  
  260. 1.1 Release version (01.01.1991)
  261.    - Icons can be dropped on the status window
  262.    - Status window contains a list of all tool names
  263.    - Tools can be removed from the list
  264.  
  265. 1.0 Release version (04.11.1990)
  266.    - Initial release
  267.  
  268.  
  269.  IX. THANKS TO
  270.  
  271.    Martin Horneffer, Juergen Lueg, Georg Sassen, Brian Wright
  272.  
  273. and anyone I forgot to mention for their suggestions, beta testing, support,
  274. flames.....
  275.  
  276.          Stefan Becker
  277.  
  278.