home *** CD-ROM | disk | FTP | other *** search
/ Amiga Computing 65 / ac065b.adf / ToolManager / ToolManager.doc / ToolManager.doc
Text File  |  1993-08-06  |  18KB  |  445 lines
  1. Documentation for ToolManager 1.4                                   09.07.1991
  2.  
  3. NOTE to first time users: Please read the entire document!
  4.  
  5. NOTE to users of ToolManager 1.0-1.3: This version contains MANY changes and
  6.                                       enhancements, so please re-read the
  7.                                       entire document!
  8.  
  9. This program is freely distributable, but copyrighted by me. This means that
  10. you can copy it freely as long as you don't ask for any more money than a
  11. nominal fee for copying. THIS APPLIES TO GERMAN PD DEALERS TOO!!! This program
  12. may be put on PD disks, especially on Fred Fish's AmigaLibDisks. If you want to
  13. distribute this program you MUST keep this document and the source code with
  14. it. Program, document and source code must be distributed in their original
  15. unmodified form. Of course you can use an archiver like LHarc to make it
  16. available on mailboxes and FTP sites. This program cannot be used for
  17. commercial purposes without written permission from the author. The author can
  18. not be made responsible for any damage which is caused by using this program.
  19.  
  20. This program is freely distributable, so you don't have to spend a buck for it.
  21. But this program has costed me a lot of time (and sweat) to create it
  22. (especially the version 1.3), so the only thing that I demand for it is, that
  23. you sent me 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. ToolManager is a management utility for tools under the 2.0 Workbench. You can
  36. add your own programs to the Tools menu or add a special Application Icon to
  37. the Workbench. The programs can be started by selecting their entries in the
  38. Tools menu and any selected icon from the Workbench will be the startup
  39. parameters for the program. You can also start a program by dropping an icon on
  40. the Application Icon or by double-clicking the icon. Last but not least you can
  41. start a program with a keyboard short cut.
  42.  
  43. BEWARE: This program makes heavely use of the new 2.0 functions, so its
  44.         completely useless to all people who are still forced to use 1.3 :-)
  45.  
  46.  
  47.  II. How to start ToolManager
  48.  
  49. ToolManager can be started from the CLI or the Workbench:
  50.  
  51.    CLI:   Run ToolManager NOICON/S,CONFIG/K,POPUP/S,POPKEY/K,CXPRIO/K/N,
  52.                           NOREQ/S,Tools/M
  53.  
  54.     Parameter       Description                         Default
  55.  
  56.     NOICON        : Don't show the program icon         Show icon
  57.     CONFIG <file> : Name of configuration file          S:ToolManager.config
  58.     POPUP         : Open status window after startup    Don't open
  59.     POPKEY <key>  : Commodities HotKey definition       "rcommand help"
  60.     CXPRIO <num>  : Commodities priority                0
  61.     NOREQ         : Don't display quit requester        Show requester
  62.     Tools         : Name of programs to add to the menu
  63.  
  64.    The name of tool x will also be the name of its corresponding menu item.
  65.    All programs will be added as CLI tools.
  66.  
  67.    NOTE: If you want to start ToolManager at boot time, you can add the
  68.          following line to your S:Startup-Sequence:
  69.  
  70.                Run >NIL: ToolManager [parameters...]
  71.  
  72.    NOTE: For a quick reminder of this options type: ToolManager ?
  73.  
  74.    Workbench:   <Click on ToolManager's icon>
  75.                 [<Click on program 1's icon>] ...
  76.                 [<Double click program n's icon>]
  77.  
  78.     ToolTypes: SHOWICON=NO|YES   Show the icon
  79.                INTERNALICON      Use the internal icon instead of the startup
  80.                                  icon
  81.                CONFIG=<name>     Read "name" as configuration file instead of
  82.                                  "S:ToolManager.config"
  83.                CX_POPUP=YES|NO   Open the status window after startup
  84.                CX_POPKEY=<key>   Set status window HotKey
  85.                CX_PRIORITY=<num> Set ToolManagers Commodities priority
  86.                SHOWREQ=YES|NO    Show quit requester
  87.  
  88.    The name of the icon will also be the name of its corresponding menu item.
  89.    All programs will be added as WB tools.
  90.  
  91.    NOTE: If you want to start ToolManager at Workbench startup time, move its
  92.          icon into the Wbstartup drawer and add the ToolType 'DONOTWAIT' to
  93.          it. ToolManager uses the icon from which it was started as its icon,
  94.          if you don't set the 'INTERNALICON' ToolType.
  95.  
  96. After startup you will notice additional entries in the Workbench Tools menu
  97. and a neat icon on the Workbench (if you don't disable it). To stop ToolManager
  98. you can select the menu entry "Quit ToolManager" or send a break signal to his
  99. process.
  100.  
  101. NOTE: You can't exit ToolManager if a Workbench tool is still running.
  102.       ToolManager will flash the screen if you try it.
  103.  
  104.  
  105.  III. The configuration file
  106.  
  107. After processing the startup parameters, ToolManager reads the configuration
  108. file. It is normally called "S:ToolManager.config", but this can be overriden
  109. by the CLI/WB Parameter 'CONFIG'. The configuration file consists of one or
  110. more of the following entries (all keywords are case insensitiv):
  111.  
  112. <Tool type keyword>:
  113. <Parameter keyword> = <parameter>
  114.    .
  115.    .
  116. <Parameter keyword> = <parameter>
  117. #
  118.  
  119.    Tool type keyworda
  120.  
  121.     dummy   Non operational dummy tool
  122.     cli     CLI tool
  123.     wb      WB tool
  124.  
  125.    Parameter keywords
  126.  
  127.     alias      Name for the menu entry and the icon.
  128.     realname   Program name of the tool. If this one is missing, the alias
  129.                name will be used to start the tool.
  130.     workdir    Path name of the current directory for the tool. When a tool is
  131.                started, it will use this directory as current directory.
  132.                ToolManager will also search the icon file in this directory. If
  133.                this one is missing, ToolManager's startup directory will be
  134.                used.
  135.     stack      Stack size for the tool. Minimum is 4096 bytes.
  136.     hotkey     Hot key description. When you issue this key combination
  137.                Toolmanager will start this tool. See table below for the
  138.                Commodities HotKey description keywords. Default: No hot key.
  139.     args       Switch the arguments passing on or off. If a tool does not
  140.                except startup parameters or doesn't need them, you can switch
  141.                off the argument passing with this option. Default: On.
  142.     menu       Switch the menu item on or off. Default: On.
  143.     icontype   Type of icon file. This can be a normal icon (Icon) or an
  144.                IFF file (Brush). Default: Icon.
  145.     iconfile   File name of icon. If this one is missing the real name or the
  146.                alias name will be used.
  147.     iconpos    Position of the icon. Default: No fixed position.
  148.  
  149. The icon will appear if any of the icon parameters are supplied.
  150.  
  151. There is one special configuration file line for describing the position of the
  152. ToolManager icon:
  153.  
  154.       ICON:<x>,<y>
  155.  
  156.    NOTE
  157.     If the program name contains spaces (e.g. ram disk:prog) you MUST enclose
  158.     it with double quotes (e.g. "ram disk:prog").
  159.  
  160.    NOTE (Dummy tools)
  161.     This tools do actually nothing and exist only for "aesthetic" reasons.
  162.  
  163.    NOTE (CLI tools)
  164.     You can add any command line parameters after the program name.
  165.  
  166.    NOTE (WB tools)
  167.     It is not possible to supply command line parameters for a WB tool.
  168.  
  169. HotKeys are done via via Commodities. A hot key description looks like this:
  170.  
  171.    [<qualifier> [<qualifier>...]] <key>
  172.  
  173.    Qualifier keywords
  174.  
  175.     alt           either Alt key
  176.     ralt          right Alt key
  177.     lalt          left Alt key
  178.     shift         either Shift key
  179.     rshift        right Shift key
  180.     lshift        left Shift key
  181.     capslock      Caps Lock key
  182.     rcommand      right Amiga key
  183.     lcommand      left Amiga key
  184.     control       Control key
  185.     numericpad    Enables the use of a key on the numeric keypad
  186.     rbutton       Click the right mouse button
  187.     midbutton     Click the middle mouse button
  188.     leftbutton    Click the left mouse button
  189.     newprefs      Preferences changed
  190.     diskremoved   Disk removed
  191.     diskinserted  Disk inserted
  192.  
  193.    Keys
  194.  
  195.     a .. z, 0 .. 9, etc.   Normal keys
  196.     f1 .. f10              Function keys
  197.     up, down, left, right  Cursor keys
  198.     help                   Help key
  199.     del                    Delete key
  200.     return                 Return key
  201.     enter                  Enter key
  202.     backspace              Backspace key
  203.     esc                    Escape key
  204.     space                  Space key
  205.     comma                  Comma key
  206.     upstroke               Upstroke key
  207.  
  208.    NOTE
  209.     Choose your hot keys CAREFULLY, because Commodities has a high priority in
  210.     the input events chain!
  211.  
  212. Configuration file examples:
  213.  
  214. ICON:200,10
  215. WB:
  216. Alias    = New Shell
  217. RealName = C:NewShell
  218. Menu     = OFF
  219. IconFile = SYS:Shell
  220. IconPos  = 300,200
  221. #
  222. CLI:
  223. Alias    = Edit Text (CLI)
  224. RealName = C:DME
  225. WorkDir  = SYS:
  226. Stack    = 20000
  227. HotKey   = ralt e
  228. IconFile = Editor.iff
  229. IconType = Brush
  230. IconPos  = 300,250
  231. #
  232. DUMMY:
  233. Alias    =
  234. #
  235.  
  236. The last one gives you an empty menu entry. For more examples please look into
  237. the supplied configuration file.
  238.  
  239.  
  240.  IV. How to use ToolManager
  241.  
  242. When ToolManager is active, you can see additional entries in the Workbench
  243. Tools menu. To start a tool you select its entry. Easy, isn't it? You can also
  244. select some icons on the Workbench to supply the tool with parameters. If the
  245. tool has an icon you can start it with a double-click or by dropping another
  246. icon on the tool icon. Last but not least you can start a tool with a HotKey.
  247.  
  248. ToolManager supports two different startup methods for tools:
  249.  
  250.    CLI startup
  251.     The tool is started as a CLI process. The selected icons will be converted
  252.     to file names, which are then joined with the tool name to a CLI command
  253.     line. The system default stack size will be used to run the tool.
  254.  
  255.     NOTE: There is a limitation of 256 characters for the resulting command
  256.           line.
  257.  
  258.    Workbench startup
  259.     The tool is started as a Workbench process. If the tool has a project icon,
  260.     ToolManager will retrieve the name of the default tool. From the tool icon
  261.     it will read the ToolWindow definition and the stack size. This one will
  262.     override the configuration file stack parameter if it is greater. The
  263.     selected icons will be directly passed to the tool.
  264.  
  265. There are two special menu entries. The first one is "Quit ToolManager", which
  266. causes ToolManager to quit if you select it. The second one is "Open TM Window",
  267. (this one shows only up if the program icon is switched off ) which causes
  268. ToolManager to open its status window. You can also open this window by double
  269. clicking the program icon.
  270.  
  271. To add a new tool, you just drag a Tool (or Project) icon on ToolManager's icon
  272. or on the status window and it will be added as a WB tool. If you start
  273. ToolManager a second time, it will pass its startup parameters to the already
  274. running ToolManager process. They will be added as WB tools if an icon exists
  275. for them, otherwise as CLI tools.
  276.  
  277. The status window contains a list of all tools and allows you to manipulate
  278. them. You can select a tool by clicking on its name in the list. If you double
  279. click an item the tool will be started. The status windows contains some
  280. gadgets to manipulate the tool list or to control ToolManager. All these
  281. gadgets also have entries in the status window menu (Right Amiga keyboard short
  282. cuts in parenthesis).
  283.  
  284.    New (N)
  285.     This adds an empty dummy tool to the list.
  286.  
  287.    Edit (E)
  288.     A new window will open, which shows the actual definition of the selected
  289.     tool. It is displayed in the same format which is used in the configuration
  290.     file. You can now change the definition. If you select the OK gadget, the
  291.     changes will be used over by ToolManager. To cancel your action, click on
  292.     the cancel or close gadget.
  293.  
  294.     NOTE: The changed menu entry will be added to the END of the list. This
  295.           is because 2.0 provides no choice where to put the menu entry. But
  296.           the tool entry will remain at the old position and if when you save
  297.           the configuration, it will appear at its old place.
  298.  
  299.     NOTE: To create a menu entry with an empty name, the Alias string gadget
  300.           MUST contain at least one space.
  301.  
  302.    Start (S)
  303.     Start the selected tool.
  304.  
  305.     NOTE: You can not supply any selected icons as startup parameters if you
  306.           use the start gadget or the double click feature of the list gadget.
  307.           The same is true for HotKey startup.
  308.  
  309.    Remove (R)
  310.     Remove the selected tool.
  311.  
  312.    Save (C)
  313.     A file requester will open, in which you can select the name of the
  314.     configuration save file. If you click on the OK gadget, ToolManager will
  315.     write its actual configuration on this file.
  316.  
  317.    Enable (A)
  318.     This enables the HotKey feature.
  319.  
  320.    Disable (D)
  321.     This disables the HotKey feature.
  322.  
  323.    Quit (Q)
  324.     Quit ToolManager.
  325.  
  326. You can close the status window by clicking its close gadget or using the Hide
  327. menu entry (Short cut: Right Amiga H). It will remember its current screen
  328. position for the next time you open it.
  329.  
  330.  
  331.  V. Caveats
  332.  
  333. If you start a program as Workbench tool and it immediately crashes with a
  334. GURU #87000004, then the startup code of this program contains a bug. This
  335. can be circumvented (hopefully :-) by using it as a CLI tool.
  336.  
  337. There have been several reports of mysterious ToolManager crashes, but they
  338. turned out to be bugs in the tools or the configuration. So if you experience
  339. mysterious crashes, check your tools and configuration first, before you start
  340. to yell at me:
  341.  
  342.    - Set the stack size higher,
  343.    - Switch the tool type from CLI to WB (or vice versa),
  344.    - Check if the selected icons crashed the tool (e.g. wrong parameters).
  345.      If so, switch off the argument passing (Args=Off)
  346.    - Set the stack size even higher,
  347.    - Try a newer version of the tool,
  348.    - Set the stack size to the highest possible value,
  349.    - and last (but not least): The tool is TOO BUGGY, dump it and try another
  350.                                one :-)
  351.  
  352. The configuration files of version 1.0-1.3 will NOT be recognized by the new
  353. version 1.4. Please re-read the corresponding chapter for the changes.
  354.  
  355. Now to some weird things, that are NOT bugs or 'undocumented features' of my
  356. my program:
  357.  
  358.    - The Workbench seems not to support multiple menu selects.
  359.  
  360.    - The Workbench looses menu select events when it is busy (e.g. if a disk is
  361.      inserted). So if you insert a disk and select a tool menu entry at the
  362.      same time, the tool will NOT be started, because ToolManager didn't
  363.      receive the menu event.
  364.  
  365.  
  366.  VI. How to compile ToolManager
  367.  
  368. This program was developed with DICE (nice job Matt!). You will need the
  369. registered version, because I used the __chip keyword, but DICE is worth its
  370. $50 anyway. Of course you need the 2.0 include files and the 2.0 amiga.lib.
  371.  
  372.  
  373.  VII. TODO (or not :-)
  374.  
  375.    - Load 2 IFF images to build an icon with two images.
  376.    - Better looking internal icon (hey, I'm not a painter :-).
  377.    - "About" menu entry with a super MEGA demo, containing astonishing 2D & 3D
  378.      graphics and 16 Bit digitized stereo sound (Hi Juergen :-).
  379.  
  380. The following things CANNOT be implemented (yet):
  381.  
  382.    - More than one Tools menu.
  383.    - Sub menus in the Tools menu.
  384.    - The 2.0 menu bar line cannot be used in menu entries.
  385.  
  386.  
  387.  VIII. HISTORY
  388.  
  389. 1.4: Release version (09.07.1991)
  390.    - Keyboard short cuts for tools.
  391.    - AppIcons for tools.
  392.    - Menu item can be switched off.
  393.    - Configuration file format completely changed (hopefully the last time)
  394.    - CLI commandline parsing is now done by ReadArgs().
  395.    - Status & edit window updated to new features.
  396.    - Safety check before program shutdown added.
  397.    - Menu item "Open TM Window" only appears, if the program icon is disabled
  398.    - WB startup method changed. Now supports project icons.
  399.    - several internal changes.
  400.  
  401. 1.3: Release version (13.03.1991)
  402.      (Appeared on Fish Disk #476)
  403.    - Now supports different configuration files
  404.    - Format of the configuration file slightly changed
  405.    - Tool definitions can be changed at runtime
  406.    - Now supports CLI & Workbench startup method
  407.    - Selected icons are passed as parameters to the tools
  408.    - Now uses the startup icon as program icon if started from Workbench
  409.    - The position of the icon can now be supplied in the configuration file
  410.    - The program icon can now be disabled
  411.    - New menu entry "Show TM Window"
  412.    - Every new started ToolManager passes its startup parameters to the
  413.      already running ToolManager process
  414.  
  415. 1.2: Release version (12.01.1991)
  416.      (First version to appear on a Fish Disk: #442)
  417.    - Status window changed to a no-GZZ & simple refresh type
  418.      (this should save some bytes)
  419.    - Status window remembers its last position
  420.    - New status window gadget "Save Configuration": saves the actual tool
  421.      list in the configuration file
  422.    - Small bugs removed in the ListView gadget handling
  423.    - Name of the icon hard-wired to "ToolManager"
  424.  
  425. 1.1 Release version (01.01.1991)
  426.    - Icons can be dropped on the status window
  427.    - Status window contains a list of all tool names
  428.    - Tools can be removed from the list
  429.  
  430. 1.0 Release version (04.11.1990)
  431.    - Initial release
  432.  
  433.  
  434.  IX. THANKS TO
  435.  
  436.    Martin Horneffer, Juergen Lueg, Georg Sassen,
  437.    Brian Wright (icons, IRC online debugging & never ending source of ideas),
  438.    Roger Westerlund & Rickard Olsson (strange bug reports :-),
  439.  
  440. and anyone I forgot to mention for their suggestions, beta testing, support,
  441. flames.....
  442.  
  443.          Stefan Becker
  444.  
  445.