Documentation for ToolManager 1.5 10.10.1991 ================================= NOTE to first time users: Please read the entire document! NOTE to users of ToolManager 1.0-1.4: This version contains MANY changes and enhancements, so please re-read the entire document! This program is freely distributable, but copyrighted by me. This means that you can copy it freely as long as you don't ask for any more money than a nominal fee for copying. THIS APPLIES TO GERMAN PD DEALERS TOO!!! This program may be put on PD disks, especially on Fred Fish's AmigaLibDisks. If you want to distribute this program you MUST keep this document and the source code with it. Program, document and source code must be distributed in their original unmodified form. Of course you can use an archiver like LHarc to make it available on mailboxes and FTP sites. This program cannot be used for commercial purposes without written permission from the author. The author can not be made responsible for any damage which is caused by using this program. This program is freely distributable, so you don't have to spend a buck for it. But this program has cost me a lot of time (and sweat) to create it (especially version 1.3), so the only thing I'm asking for for it is that you send me a note if you are using ToolManager. Send comments, suggestions or bug reports to: Snail : Stefan Becker, Holsteinstrasse 9, 5100 Aachen, GERMANY Domain: stefanb@cip-s01.informatik.rwth-aachen.de FIDO : 2:242/7.6, Stefan_Becker@mowgli.fido.de I. What is ToolManager? ----------------------- ToolManager's purpose is starting Workbench tools and CLI programs. You can add your own programs to the Tools menu or put a special Application Icon on the Workbench, which works even with CLI tools. Every tool can have a special icon that is "docked" to a line of icons. The programs can be started by selecting their entries in the Tools menu and any selected icon from the Workbench will be the startup parameters for the program. You can also start a program by dropping an icon on the Application Icon or by double-clicking the icon. Or you can drop an icon on the "docked" icon or by clicking the "docked" icon. Last but not least you can start a program with a keyboard short cut. BEWARE: This program makes heavily use of new 2.0 functions, so its completely useless to all people who are still forced to use 1.3 :-) To get the full functionality you should run it only under 2.04. II. How to install ToolManager ------------------------------ ToolManager needs to know what to put in the Tools menu. It can obtain this information from three possible sources: Either from the command line when it is started from CLI (in which case all applications must be CLI startable), interactively from the user on the workbench (applications must be WB startable), or from a configuration file. * CLI Run ToolManager NOICON/S,ICONNAME/K,ICONFILE/K,CONFIG/K,OUTPUT/K,PATH/K, CX_POPUP/S,CX_POPKEY/K,CX_PRIORITY/K/N,NOREQ/S,DELAY/K/N, Tools/M Parameter Description Default NOICON Don't show the program icon Show icon ICONNAME Name of the program icon ToolManager IC0NFILE File name for the program icon Internal icon CONFIG Name of configuration file S:ToolManager.config OUTPUT Name of the CLI output file (see below) PATH List of directories for CLI path No path CX_POPUP Open status window after startup Don't open CX_POPKEY Commodities HotKey definition "rcommand help" CX_PRIORITY Commodities priority 0 NOREQ Don't display quit requester Show requester DELAY Wait "num" seconds before startup Don't wait Tools Name of programs to add to the menu The default for the OUTPUT window is: CON:0/0/640/150/ToolManager CLI Tool Output/INACTIVE/AUTO/WAIT/ALT The path list is a comma separated list of directory names, which will be scanned by CLI tools to find programs they want to execute. Example: BIN:,SYS:,S: The name of tool x will also be the name of its corresponding menu item. All programs will be added as CLI tools. To install ToolManager permanently, add the following line to the S:StartupSequence somewhere after the LoadWB command: Run >NIL: ToolManager [parameters...] * Workbench: [] ... [] ToolType Description Default NOICON Don't show the program icon ICONNAME= Use as name for the ToolManager icon ToolManager INTERNALICON Use the internal icon instead of the startup icon CONFIG= Read as config file S:ToolManager.config OUTPUT= Use as CLI output file (see above) PATH= Use as CLI path No path CX_POPUP=YES|NO Open status window after startup No CX_POPKEY= Set status window HotKey. rcommand help CX_PRIORITY= Set TM's Commodities priority. 0 NOREQ Don't show quit requester. DELAY= Wait seconds before adding App* stuff Don't wait The name of the icon will also be the name of its corresponding menu item. All programs will be added as WB tools. If you want to start ToolManager at Workbench startup time, move its icon into the Wbstartup drawer and add the ToolType 'DONOTWAIT' to it. ToolManager uses the icon from which it was started as its icon, if you don't set the 'INTERNALICON' ToolType. After startup you will notice additional entries in the Workbench Tools menu and a neat icon on the Workbench (if you don't disable it). To stop ToolManager you can select the menu entry "Quit ToolManager" or send a break signal to its process. NOTE: You can't exit ToolManager if a Workbench tool is still running. ToolManager will flash the screen if you try it. III. The configuration file --------------------------- After processing the startup parameters, ToolManager reads the configuration file. It is normally called "S:ToolManager.config", but this can be overridden by the CLI/WB Parameter 'CONFIG'. The configuration file consists of one or more of the following entries (all keywords are case insensitive): : = . . = # Tool type keywords dummy Non-operational dummy tool cli CLI tool wb WB tool Parameter keywords alias Name for the menu entry and the icon. realname Program name of the tool. If this one is missing, the alias name will be used to start the tool. workdir Path name of the current directory for the tool. When a tool is started, it will use this directory as the current directory. ToolManager will also search the icon file in this directory. If this one is missing, ToolManager's startup directory will be used. path (CLI Tools only!) Comma separated list of directory names for the path of the CLI tool. The Global path list will be appended to this list before the tool is started. Default: No path outfile (CLI Tools only!) File name for CLI output file. This keyword sets the "output" flag. Default: No output stack Stack size for the tool. Minimum is 4096 bytes. hotkey Hot key description. When you issue this key combination ToolManager will start this tool. See table below for the Commodities HotKey description keywords. Default: No hot key. menu Switch the menu item on or off. Default: On. args Switch the argument passing on or off. If a tool does not except startup parameters or doesn't need them, you can switch off the argument passing with this option. Default: On. wbfront Move the Workbench screen to front before starting the tool. Default: Off. output (CLI Tools only!) Use the CLI output file as standard output for the tool. Default: Off. iconname Show the name of the icon. Default: On. icontype Type of the icon file. This can be a normal icon (Icon) or an IFF file (Brush). Default: Icon. iconfile File name for the icon. If this one is missing, the real name or the alias name will be used. The suffix ".info" is automatically appended if the type is set to Icon. iconpos Position of the icon. Default: No fixed position. dockon This enables the "docked" icon. Default: No "docked" icon. sameicon Use the same image for the Application icon and the "docked" icon. Default: Use separate image. docktype Type of the dock file. This can be a normal icon (Icon) or an IFF file (Brush). Default: Icon. dockfile File name for the dock icon. If this one is missing, the real name or the alias name will be used. The suffix ".info" is automatically appended if the type is set to Icon. If you want to switch off one entry temporarily, then put a semicolon before its keyword like this: ";Menu" BEWARE: Don't save the configuration when some entries are commented out, because they will disappear! The Application icon will appear if any of the icon parameters are supplied. If the Workbench decides that the icon won't fit on the place you selected, the icon will be moved to a free place chosen by the Workbench. The "docked" icon will appear if any of the dock parameters are supplied. It will be added at the end of the dock line. You should only use icons with the same size for "docking," otherwise the dock window will have empty spaces. DUMMY entries: Dummy tools do actually nothing and exist only for "aesthetic" reasons. CLI entries: You can add any command line parameters after the program name of a CLI tool. WB entries: You cannot supply command line parameters for a WB tool. ICON entry: There is one special configuration file line for describing the position of the ToolManager icon: ICON:, DOCK entry: There is one special configuration file line for describing the position, orientation and the backdrop state of the dock window and the size of one "docked" icon: DOCK:,,,, H stands for horizontal, V for vertical orientation. B stands for move to back, F for stay in front after opening. If you move the dock window around, this entry will be updated automatically if you save your configuration. Default: DOCK:0,0,41,41,VB NOTE: If a program name contains spaces (e.g. ram disk:prog) you MUST enclose it in double quotes (e.g. "ram disk:prog"). HotKeys are done via Commodities. A HotKey description looks like this: (everything is case insensitive) [ [...]] Qualifier keywords alt either Alt key ralt right Alt key lalt left Alt key shift either Shift key rshift right Shift key lshift left Shift key capslock Caps Lock key rcommand right Amiga key lcommand left Amiga key control Control key numericpad Enables the use of a key on the numeric keypad rbutton Click the right mouse button midbutton Click the middle mouse button leftbutton Click the left mouse button newprefs Preferences changed diskremoved Disk removed diskinserted Disk inserted Keys a .. z, 0 .. 9, etc. Normal keys f1 .. f10 Function keys up, down, left, right Cursor keys help Help key del Delete key return Return key enter Enter key (MUST be combined with 'numericpad'!) backspace Backspace key esc Escape key space Space key comma Comma key upstroke Upstroke key Examples lalt ralt enter ramiga f10 alt x NOTE: Choose your hot keys CAREFULLY, because Commodities has a high priority in the input events chain (i.e. will override existing definitions). NOTE: The Workbench screen can be moved to front before starting the tool via HotKey. Configuration file example: ICON:200,10 WB: Alias = New Shell RealName = C:NewShell Path = BIN:,S: Menu = OFF IconFile = SYS:Shell IconPos = 300,200 SameIcon = On # CLI: Alias = Edit Text (CLI) RealName = C:DME WorkDir = SYS: Stack = 20000 HotKey = ralt e WBFront = ON IconName = OFF IconFile = Editor.iff IconType = Brush IconPos = 300,250 # CLI: Alias = Show Directory RealName = Dir SYS: all Output = CON:0/0/640/256/Test # DUMMY: Alias = # The last one gives you an empty menu entry. For more examples please look at the supplied configuration file. IV. How to use ToolManager -------------------------- When ToolManager is active, you can see additional entries in the Workbench Tools menu. To start a tool you select its entry. Easy, isn't it? You can also select some icons on the Workbench to supply the tool with parameters. If the tool has an icon you can start it with a double-click or by dropping another icon on the tool icon. If the tool has a "docked" icon you can start it with a click or by dropping another icon on it. Last but not least you can start a tool using a HotKey. ToolManager supports two different startup methods for tools: CLI startup The tool is started as a CLI process. The selected icons will be converted to file names, which are then joined with the tool name to a CLI command line. The system default stack size will be used to run the tool. NOTE: There is a limitation of 4096 characters for the resulting command line. NOTE: You can supply a path for a CLI tool. NOTE: The output of a CLI tool can be redirected into the CLI output file. Workbench startup The tool is started as a Workbench process. If the tool has a project icon, ToolManager will retrieve the name of the default tool. From the tool icon it will read the ToolWindow definition and the stack size. This one will override the configuration file stack parameter if it is greater. The selected icons will be directly passed to the tool. There are two special menu entries. The first one is "Quit ToolManager", which causes ToolManager to quit if you select it. The second one is "Open TM Window", (this one shows only up when the program icon is switched off ) which causes ToolManager to open its status window. You can also open this window by double clicking the program icon, or you can use the status window HotKey, in which case the Workbench screen will be moved to front so that you can see the window. To add a new tool, you just drag a Tool (or Project) icon on ToolManager's icon or on the status window and it will be added as a WB tool. If you start ToolManager a second time, it will pass its startup parameters to the already running ToolManager process. They will be added as WB tools if an icon exists for them, otherwise as CLI tools. The status window contains a list of all tools and allows you to manipulate them. You can select a tool by clicking on its name in the list. If you double click an item the tool will be started. The status windows contains some gadgets to manipulate the tool list or to control ToolManager. All these gadgets also have entries in the status window menu (Right Amiga keyboard short cuts in parenthesis). Start (G, menu only) Start the selected tool. NOTE: You can not supply any selected icons as startup parameters if you use the start menu entry or the double click feature of the list gadget. The same is true for HotKey startup. Top (T) Move the selected tool to the top of list NOTE: If the tool has a menu entry or a "docked" icon, these entries will NOT be moved. But the tool entry will be saved at the right place in the configuration, so the entry will be at the right position next time you start ToolManager. The same is true for the gadgets Up, Down and Bottom. Up (<) Move the selected tool one place up in list Down (>) Move the selected tool one place down in list Bottom (B) Move the selected tool to the bottom of list New Add an empty dummy tool to the list, which can then be edited. If a tool is selected, then the new entry will be inserted after that tool, otherwise it will be added at the end of the list. Edit (E) Opens a window for editing the definition of the selected tool. Remove Remove the selected tool. Enable (A) This enables the HotKey feature. HotKeys (Menu item: List, L) Opens a window with a list of all active HotKeys. Disable This disables the HotKey feature. Dock On If tools with "docked" icons exist, then the dock window will be opened. Dock H/V Change the orientation of the dock window from horizontal to vertical or vice versa. Dock Off (C) Close the dock window. Save (A) A file requester will open, in which you can select the name of the configuration save file. If you click on the OK gadget, ToolManager will write its current configuration on this file. Hide (H) Close the status window. NOTE: It will remember its current screen position for the next time you open it. Quit (Q) Quit ToolManager. Additional menu entries in the Project menu: New (N) Delete the current configuration. Open (O) Delete the current configuration and load a new one from a file. Append Read new tool definitions from a file and append them to the list. Save (S) Save the current configuration to the last specified configuration file. About Tells you something about ToolManager. The edit window shows the current definition of the selected tool. It is displayed in the same format which is used in the configuration file. You can now change the definition. If you select the OK gadget, the changes will be used by ToolManager. To cancel your action, click on the cancel or close gadget. NOTE: The changed menu entry and the "docked" icon will be added to the END of the list. This is because 2.0 provides no choice where to put the menu entry. But the tool entry will remain at the old position and when you save the configuration, it will appear at its old place. NOTE: To create a menu entry with an empty name, the Alias string gadget MUST contain at least one space. Every string gadget, which represents a file name, has an additional button gadget. If you click on this button gadget, a file requester will open and you can choose the file name that should be put into the string gadget. The edit window has gadgets which allows you to select the position of the tool icon with the mouse. To use this feature you either click on the "Position" gadget, then press the right mouse button, move the mouse pointer to the position you want and release the right mouse button, or you can also type in the coordinates directly. The icon will then be moved to the new position and the Icon X/Y gadgets will be updated. (BTW.: If you wonder about this strange method, you must remember that there are many mouse-auto-activate programs!) NOTE: The edit window MUST be active when you release the right mouse button. If it is not active any more, simply reselect it and press the right mouse button again. NOTE: If the Workbench decides that the icon won't fit on the place you selected, the icon will be moved to a free place chosen by the Workbench. NOTE: ToolManager tries to retrieve the correct coordinates of the mouse relative to the Workbench screen, but it may sometimes fail. V. How to use DeleteTool ------------------------ DeleteTool is a program that can be used in conjunction with ToolManager to build a trashcan. It will delete all files and their icons; just drop their icons on the Application icon. NOTE: It really deletes files and does NOT move them to a temporary directory as the Workbench does! NOTE: It puts up a safety requester before it deletes the files. This requester can be suppressed with the option QUIET. NOTE: It can't delete drawers that are open on the Workbench. To use DeleteTool, copy it to your C: directory and add the following entry to the configuration file: CLI: Alias = Trashcan RealName = C:DeleteTool Menu = OFF IconFile = sys:Trashcan # VI. Caveats ----------- If you start a program as Workbench tool and it immediately crashes with a GURU #87000004, then the startup code of this program contains a bug. This can be circumvented (hopefully :-) by using it as a CLI tool. There have been several reports of mysterious ToolManager crashes, but most of them turned out to be bugs in the tools or the configuration. So if you experience mysterious crashes with some tools, check them and the configuration first, before you start to yell at me: - Set the stack size higher, - Switch the tool type from CLI to WB (or vice versa), - Check if the selected icons crashed the tool (e.g. wrong parameters). If so, switch off the argument passing (Args=Off) - Set the stack size even higher, - Try a newer version of the tool, - Set the stack size to the highest possible value, - and last (but not least): The tool is TOO BUGGY, dump it and try another one :-) There have been several reports that TM slows down and crashes the machine sometimes. I wasn't able to reproduce it and so I have to guess where the bug is hidden. I think the main problem is that the Workbench doesn't like adding App* stuff too early, so I have added a DELAY switch for it. You should try this switch if you get those crashes. The configuration files of version 1.0-1.3 will NOT be recognized by the new version 1.4 (or above). Please re-read the corresponding chapter for the changes. Some of the ToolManager CLI parameters/Workbench tooltypes have been changed in the release 1.5. Please re-read the corresponding chapter for the new names. Now to some weird things, that are NOT bugs or 'undocumented features' of my my program: - The Workbench seems not to support multiple menu selects. - The Workbench loses menu select events when it is busy (e.g. if a disk is inserted). So if you insert a disk and select a tool menu entry at the same time, the tool will NOT be started, because ToolManager didn't receive the menu event. VII. How to compile ToolManager and DeleteTool ---------------------------------------------- This program was developed with DICE (nice job, Matt!). You will need the registered version, because I used the __chip keyword, but DICE is worth its $50 anyway. Of course you need the 2.0 include files and the 2.0 amiga.lib. VIII. TODO (or not :-) ---------------------- - ARexx interface - Load 2 IFF images to build an icon with two images - Better looking internal icon (hey, I'm not a painter :-) - "About" menu entry with a super MEGA demo, containing astonishing 2D & 3D graphics and 16 Bit digitized stereo sound (Hi Juergen :-) The following things CANNOT be implemented (yet): - More than one Tools menu - Sub menus in the Tools menu - The 2.0 menu bar line cannot be used in menu entries - "Snapshot" of Application icons IX. HISTORY ----------- 1.5: Release version (10.10.1991) - Status Window: New/Open/Append/Save As menu items for config file - Edit Window: File requesters for file string gadgets - Added a Dock Window (a la NeXT) - Added a DeleteTool - A list of all active HotKeys can be shown - Tools can be moved around in the list - Icon positioning in the edit window added - Name of the program icon can be set - CLI tools can have an output file and a path list - Uses UserShell for CLI tools. - Maximum command line length for CLI tools is now 4096 Bytes - AppIcons without a name are supported now - Workbench screen will be moved to front, if you pop up the Status window - Workbench screen can be moved to front before starting a tool via HotKey - TM will wait up to 20 seconds for the workbench.library - Added a DELAY switch, which causes TM to wait seconds before adding any App* stuff - renamed some tooltypes/parameters - some visual cues added - some internal changes 1.4: Release version (09.07.1991) (Appeared on Fish Disk #527) - Keyboard short cuts for tools. - AppIcons for tools. - Menu item can be switched off. - Configuration file format completely changed (hopefully the last time) - CLI commandline parsing is now done by ReadArgs(). - Status & edit window updated to new features. - Safety check before program shutdown added. - Menu item "Open TM Window" only appears, if the program icon is disabled - WB startup method changed. Now supports project icons. - several internal changes. 1.3: Release version (13.03.1991) (Appeared on Fish Disk #476) - Now supports different configuration files - Format of the configuration file slightly changed - Tool definitions can be changed at runtime - Now supports CLI & Workbench startup method - Selected icons are passed as parameters to the tools - Now uses the startup icon as program icon if started from Workbench - The position of the icon can now be supplied in the configuration file - The program icon can now be disabled - New menu entry "Show TM Window" - Every new started ToolManager passes its startup parameters to the already running ToolManager process 1.2: Release version (12.01.1991) (First version to appear on a Fish Disk: #442) - Status window changed to a no-GZZ & simple refresh type (this should save some bytes) - Status window remembers its last position - New status window gadget "Save Configuration": saves the actual tool list in the configuration file - Small bugs removed in the ListView gadget handling - Name of the icon hard-wired to "ToolManager" 1.1 Release version (01.01.1991) - Icons can be dropped on the status window - Status window contains a list of all tool names - Tools can be removed from the list 1.0 Release version (04.11.1990) - Initial release X. THANKS TO ------------ Martin Horneffer, Juergen Lueg, Georg Sassen, Olaf 'Olsen' Barthel, Georg Hessmann, Martin Steppler, Bill Hogsett, Roger Westerlund, Rickard Olsson, Dominik Mueller (scripts & documentation enhancement), Brian Wright (icons, IRC online debugging & never ending source of ideas), and anyone I forgot to mention for their suggestions, alpha/beta testing, support, flames..... Stefan Becker