home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Club Amiga de Montreal - CAM
/
CAM_CD_1.iso
/
files
/
563.lha
/
ToolManager_v1.5
/
ToolManager.doc.pp
/
ToolManager.doc
Wrap
Text File
|
1991-11-08
|
28KB
|
734 lines
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 <string> Name of the program icon ToolManager
IC0NFILE <file> File name for the program icon Internal icon
CONFIG <file> Name of configuration file S:ToolManager.config
OUTPUT <file> Name of the CLI output file (see below)
PATH <pathlist> List of directories for CLI path No path
CX_POPUP Open status window after startup Don't open
CX_POPKEY <key> Commodities HotKey definition "rcommand help"
CX_PRIORITY <num> Commodities priority 0
NOREQ Don't display quit requester Show requester
DELAY <num> 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: <Click on ToolManager's icon>
[<Click on program 1's icon>] ...
[<Double click program n's icon>]
ToolType Description Default
NOICON Don't show the program icon
ICONNAME=<string> Use <string> as name for the
ToolManager icon ToolManager
INTERNALICON Use the internal icon instead
of the startup icon
CONFIG=<file> Read <file> as config file S:ToolManager.config
OUTPUT=<file> Use <file> as CLI output file (see above)
PATH=<pathlist> Use <pathlist> as CLI path No path
CX_POPUP=YES|NO Open status window after startup No
CX_POPKEY=<key> Set status window HotKey. rcommand help
CX_PRIORITY=<num> Set TM's Commodities priority. 0
NOREQ Don't show quit requester.
DELAY=<num> Wait <num> 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 keyword>:
<Parameter keyword> = <parameter>
.
.
<Parameter keyword> = <parameter>
#
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:<x>,<y>
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:<x pos>,<y pos>,<x size>,<y size>,<H or V><B or F>
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> [<qualifier>...]] <key>
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 <num> 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