home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Frozen Fish 1: Amiga
/
FrozenFish-Apr94.iso
/
bbs
/
alib
/
d9xx
/
d995
/
parm.lha
/
ParM
/
ParM.DocE
< prev
next >
Wrap
Text File
|
1994-04-05
|
28KB
|
677 lines
Documentation for ParM V4.5, SetMouse V2.1, parm.library V10.2
**************************************************************************
***************************** ********************************
***************************** WARNING ********************************
***************************** ********************************
**************************************************************************
If you use a previous release of ParM, and tools that makes use of
parm.library, you _MUST_ replace ALL theses with those given in this
release. The new parm.library version 7 is not compatable with previous
ones. It was just not possible to do it.
As promised in previous release, this new ParM only works with AmigaDOS
version 37 or higher.
ParM no more needs arp nor req libraries. OS 2.0 made it possible.
**************************************************************************
**************************************************************************
ParM stands for Parametrable Menu.
ParM allows you to build your own menus in order to run all the programs
you can have on one ore more disks. This is very useful for hard disk
owners who have programs deeply enclosed in subdirectories. With ParM,
you can run them without going through directories under either WorkBench
or CLI.
With ParM, you can start programs in either WorkBench or CLI mode. The
advantage of WorkBench mode is that the default directory of the program
you run is the one in which the program file is. But not all programs can
be run in this mode.
ParM now has an integrated SunMouse, screen blank, mouse accelerator...
We decided to implement this since an input-handler was already present in
parm.library, and we had 3 windows in the workbench screen's title bar.
One for sunmouse, one for memory/time display, and the useless ParM's
window. So now, ParM's window is usefull, and is easier to catch for menu
access.
Using ParM:
-----------
Reading this documentation can make you being confused with all modes
you can use to run your favorite tools. So, you will find at the end of
this text a tutorial about what modes you'd better use.
Installation:
-------------
Put ParM and SetMouse with their icons wherever you want, and just put
the default config file "ParM.cfg" in S: if you use it. If you
don't, you'll have to specify the config file in the command line or
in the tool types of the icon, otherwise, you will have to cancel the
requester and won't have any menus. Since version 2.6r, you must also
put parm.library in your LIBS: directory.
Running:
--------
It is recommended to run ParM from CLI if you want your programs to
have a default path other than the current directory and C: which is
the case if you start it from WorkBench.
ParM can work in three ways.
1) You can attach ParM to the CLI you are using. In this case, if you
don't specify any of the window options, the menus will be attached to
the CLI window you start it from. You may then only "Run" it to
prevent you from closing the CLI. In this case, commands launched in
RUN mode will use the cli/shell window for their input/output. If you
dont want your shell to be trashed by these commands, use the USENULL
option.
2) ParM can have its own window. This is allways the case when it is run
from WorkBench, but you can also tell it to open it's own window when
run from CLI using OWNWINDOW option or any of the window options. You
should then "RunBack" it to be able to close the CLI later.
3) ParM can be attached to Workbench, ala MyMenu.
ParM have some options which are available for most either from
WorkBench or from CLI. Arguments documentation is now available from
within ParM itself. Just type ParM ?, and then ? again. Arguments
with /S are switches, and arguments with /K are keywords and need
something more (a number, ON or OFF, a filename,...). added /N are for
numeric arguments.
From workbench, keywords are the same. You just have to add =TRUE
for switches, or =Argument for keywords.
CLIWINDOW and USENULL are not available from WorkBench.
ParM's CLI Help:
MYMENU/S,CLIWINDOW/S,OWNWINDOW/S,LEFTEDGE/K/N,TOPEDGE/K/N,DETAILPEN/K/N,BLOCKPEN/K/N,
DRAGBAR/K,DEPTH/K,AUTOFRONT/K,SHOWMEM/K,SHOWTIME/K,REFRESHTIME/K/N,MTDETAILPEN/K/N,
MTBLOCKPEN/K/N,MENUCOLOR/K/N,STACKSIZE/K/N,CONFIGFILE/K,USENULL/K: ?
ParM V4.2 © 1990-92 by S.R. & P.C.
MYMENU Attach menus to Workbench's (Like MyMenu)
CLIWINDOW Attach menus to CLI/Shell Window
OWNWINDOW Open its own window (default)
LEFTEDGE Left edge of ParM Window (default 0)
TOPEDGE Top edge of ParM Window (default 0)
DETAILPEN Detail pen of ParM Window (default 1)
BLOCKPEN Block pen of ParM Window (default 2)
DRAGBAR ON|OFF Drag bar (You can't move ParM window) (default on)
DEPTH ON|OFF Depth gadgets (default off)
AUTOFRONT ON|OFF Automatic window to front (default: on)
SHOWMEM ON|OFF Show available memory (default off)
SHOWTIME ON|OFF Show time. (default off)
REFRESHTIME Interval time for Mem/Time refresh in 0.1s (default 1s)
MTDETAILPEN DetailPen for Mem/Time (default: DetailPen)
MTBLOCKPEN BlockPen for Mem/Time (default: BlockPen)
MENUCOLOR Color for ParM's main menu (defaut: DetailPen)
STACKSIZE Default stack size for commands (defaut: ParM process stack)
CONFIGFILE Configuration file (default: S:ParM.cfg)
USENULL ON|OFF Redirect output to NULL: (or NIL:) for commands in RUN mode (default: off)
Environnement variable ParMOpt:
-------------------------------
In addition to the command line, your preferences can now be saved in
the Env:ParMOpt variable. Just snap your cli arguments and paste them
into your text editor. Then, save the file as Env:ParMOpt. This file
will be parsed first, and then the CLI/WB arguments, which will
override the environnement variable. (See example given).
Configuration file:
-------------------
You will best understand what follows if you have in front of you a
printout of the config file supplied.
A configuration file looks like a structured program. You should
indent your lines to make the file as readable as possible.
The default configuration file should be in the S: directory and be
named ParM.cfg.
The configuration file defines the menus you want, and what commands
they will run. Comments begin with a #, and continue until the end of
the line. Upper and lowercase do not make a difference.
Keywords:
---------
CMDWIN console_name
This will override the default console used for Command output
which is "CON:0000/0011/0640/0100/Command window/AUTO/CLOSE/WAIT".
This should be placed anywhere in the file but better be at top of
it. This console will in 2.0 have a close gadget, a defered open,
and wait user to hit close gadget before closing window.
Under 2.0, if you use Command in Simple mode, you MUST specify the
/WAIT option for your console, or it will close before you could
read it.
SHELLWIN console_name
This will override the default console used for SHELL commands
which is "CON:0000/0011/0640/0100/Shell/Auto/Close/Wait". This
should be placed anywhere in the file but better be at top of it.
SHORTCUTQUAL qual
This can be used to add keys to access menus short-cuts. For
example, you can use Left-Amiga, ALT, SHIFT or Ctrl. If you want
several keys, you just have to add qualifiers listed below:
Left-Shift 1
Right-Shift 2
Ctrl 8
Left-Alt 16
Right-Alt 32
Left-Amiga 64
If for example you want both left and right ALT keys to work for
menu shortcuts: ( 16 + 32 = 48 ! )
SHORTCUTQUAL 48
If you want shortcuts without a qualifier key, you can use 32768
(IEQUALIFIER_RELATIVEMOUSE), which is allways present in RAWKEY
events. (Use with great care).
This works only when ParM has its own window or when attached to
Workbench.
ACTIVATEKEY [SCREENTOFRONT] [PASSTHROUGH] [NOCHECK] qualifier rawkey
This gives you access to the simple but powerfull parm's library
input handler. Be carefull, rawkey is the keyboard key code, not
the ASCII code of the key.
This gives you the possibility to define one or more hot keys to
activate parm's window, or any parm.library user, like "The Great
BrowserII".
Options:
1. SCREENTOFRONT
The screen which contains ParM's window comes to front.
2. PASSTHROUGH
This may be hard to understand for non-programmers, but is
powerfull and quite simple. Let's say that if you don't
use this option, the hot-key will just activate ParM's
window, and that's all. If you use it, the event will not
be removed from list, and as ParM's window has just been
activated, it will receive the raw key. So, if this raw
key is also a menu short cut, it will be executed without
having to activate ParM's window with the mouse.
Example:
SHORTCUTQUAL 64 (Left-Amiga)
ACTIVATEKEY PASSTHROUGH 64 50 (Left-Amiga - X)
Menu System
Item {X} Xoper RUN Xoper
This allways runs Xoper, without touching the mouse,
even if ParM's window is not the active one.
Another example:
# Left ALT - Right Mouse Button
ACTIVATEKEY PASSTHROUGH SCREENTOFRONT 8208 105
This activate ParM's menus, in a single click. No more
need to search for little ParM's window.
3. NOCHECK
The library keeps a list of hot-keys. When you add a new
hot-key with ACTIVATEKEY command, ParM controls if it is
not already used. If it is, you will be requested, and it
will be ignored. If you specify NOCHECK, hot-key will be
inserted in head of the list, and will take precedence
over the old one.
Here is what I do with that: I have a hot-key in ParM to
load BrowserII. The same hot-key has the NOCHECK flag in
BrowserII.menu. So, if BrowserII is already loaded, the
hot-key brings BrowserII's screen to front, else,
BrowserII is loaded by ParM. Nice, isn't it ?
ParM.cfg :
SHORTCUTQUAL 64
# Left Amiga - Z (Load BrowserII)
ACTIVATEKEY PASSTHROUGH 64 49
menu Tools
item {Z} BrowserII RUN HD:Tools/BrowserII
BrowserII.menu :
SHORTCUTQUAL 64
# Left Amiga - Z
ACTIVATEKEY SCREENTOFRONT NOCHECK 64 49
COLOR n
This will set the foreground pen color for new items. You can
change this as often as you want. The arguments is the pen number
to use. The default is window detail pen. If the color was
window block pen, the item would be invisible, in this case, ParM
replaces the color with window detail pen.
MENU menu_name
Creates a new menu. Each menu must have at least one item or
submenu.
SUBMENU submenu_name
Creates a new submenu. Each submenu must have at least one item
and can't have submenus.
Each SUBMENU must end with an ENDSUBMENU
ENDSUBMENU
See SUBMENU.
ITEM [{command-char}] item_name [WBTF] [REQUEST] command_def
Defines a new menu item. Each item definition must have an
item_name and an associated command. Each item is linked to the
current menu or submenu. An ENDSUBMENU statement tells ParM to
attach next items to the current menu rather than to the current
submenu. If any of the menu, submenu and item names may contain
whitespaces. In this case, enclose the name in double quotes. A
command character may be defined for the menu item by putting the
character after the ITEM keyword and surround it with {}'s.
WBTF is optional. Brings workbench to front just after running the
command. REQUEST is also optional. Opens a requester enabling you
to modify the command before running it. Not available for WB mode
Command syntax is decribed below.
command_def
Programs can be run in three ways: RUN, SHELL, and WB.
For all modes, STACK and PRI are optionnal. If STACK is less
than 4000 bytes, or if no stack is specified, the stack will
be set to the ParM task Stack. That is to say the stack size
at time ParM was run. There's an exception: If ParM is
resident, ParM stack will allways be 4000 bytes.
1) RUN syntax
RUN [WIN console_window] [STACK n] [PRI n] command [args][;command [args]]...
This mode creates a background shell. This mode should be
used for scripts. If the bit s of your script file is set, it
is automaticaly sourced (No need of the execute command). In
this mode, commands won't be detached if ParM is attached to a
CLI (except if you use USENULL option). Redirection can be
done in this mode.
You can specify several commands separated with semicolons ;.
2) SHELL syntax
SHELL [WIN console_window] [STACK n] [PRI n] command [args][;command [args]]...
This mode now does the same as RUN, but if no window is given,
the default shell window is taken.
3) WB syntax
WB [STACK n] [PRI n] command
Execute command in WorkBench mode. No arguments are allowed
in this mode. Warning: If STACK is specified here, it will
override the stack specified in the icon of the command. Your
command may crash if you ask a smaller stack than in the icon.
Do it at your own risk.
5) CFG action
CFG ConfigFile
ParM loads the new ConfigFile like ParM->Open in the Menu.
Very usefull to use different cfg file on different disk to
choose programs on this disk.
BARLABEL
Adds a bar between last item and next one.
For all modes but WB, your command is searched first in resident
list and then in CLI Path at time ParM was run. To know the path in
which ParM search its commands, just issue the Path command in the
requester of ParM Command command, or open a newcli or shell from ParM
and issue the Path command.
A config file is given with ParM as an example.
ParM commands:
--------------
Open: Pops up a requester asking to select the new config file.
UpDate: UpDate the menu reloading the config file. Usefull if you
modify the config file while ParM is running.
Std Cfg: Load the standard 'S:ParM.cfg' configuration file.
Usefull to return in your favorite cfg when you are lost
in one disk cfg.
Command: Execute cli commands. Your CMDWIN console MUST have the
/Wait option if you want to be able to read the command
output.
Change Dir: Changes ParM current directory. Commands run in all modes
but WB will inherit ParM's current directory.
Quit: Why? You don't like it!
Separated commands:
-------------------
End:
The End command can now close a CLI in which a ParM is attached. End
needs EndCLI to work. If there is no ParM attached to the CLI, End
will only do an EndCLI. End and EndCLI can be made resident for
maximum speed. You can for example put ParM in your CLI-Startup or
Shell-Startup to have menus in all of your CLI/Shells and you'll be
able to leave them with the End command without worrying about ParM.
Don't use this command in a WShell since it loads EndCLI from disk and
WShell only accept its built in EndCLI command.
ParMCD:
The ParMCD change the current directory of the ParM attched to the
current cli window. Without argument, ParM will take the cli current
dir. Otherwise, you can specify a directory as an argument to ParMCD.
Note:
-----
These commands do not work if you use the console replacement DHOpts.
DHOpts doesn't support packet ACTION_DISK_INFO when ParM has installed
it's menu on the console window. THIS IS NOT A PARM BUG.
Limitations:
------------
If a command in RUN or SHELL mode can't be started, you will never
know, except you won't see it working.
When attached to a CLI, commands executed in RUN mode won't be
detached, which means that you won't be able to close the cli before
those commands end. This is the same problem as if you had run your
command in a CLI with
1> Run mycommand
By the way, theses commands will have their output file handles in
this window, and advantages can be taken from that. You can redirect
these to NIL: or use USENULL option to avoid trashing of your cli
window. In this case, commands will be detached.
Known bugs:
-----------
See notes for external commands.
RUN PRI 1 NewShell does not work. Pri is allways 0. Not a ParM bug.
Future plans:
-------------
Localization.
Release notes:
--------------
1.0: Internal. Major MyMenu rework.
1.1: First official release. (Sent to Fred Fish)
Old CLI option changed to RB (stands for RunBack).
New CLI option added.
Config file syntax changed. (Old was MyMenu's one).
1.4: Internal. Option -l -d and WBRun enhanced.
Now you can run projects icons which have no file. For example
Serial, Pointer and Printer in the Prefs drawer.
1.6: Second official realease. 29/09/90
Code Cleanup
New CFG option added.
New 'Std cfg' menu added.
1.7: Internal
No more uses c16.lib, but use my owns instead.
Code size about 1.5K smaller.
2.0: Third Official release. 13/10/90.
ParM can now be made resident.
End command created.
Directory path string built in 'Change Dir'.
2.1: ParMCD command created.
2.1r: This version uses the great req.library (r for req!)
2.2r: No more RB and CLI modes. New modes are ARUN, RUN, and SHELL.
STACK and PRI available in all modes but WB now.
No more need of the Run command in your C: directory.
Syntax errors in config file will now be reported with a line
and char number.
2.3r: You will never see again 'Workbench processes still active'.
ParM now creates a public MsgPort to handle workbench replies
and leave it if there's still messages to be replied.
Now, if your console has a close gadget, ParM will end if you
hit it. This is usefull for lucky owners of WShell.
Characters of ascii value over 127 now supported. (accents)
WAITCMD added.
2.4r: WB mode rewriten. STACK and PRI available in all modes now.
WB mode no more crashes if command not found. You can now run
tools that haven't an associated icon.
Memory for menus items is allocated by 1 K blocks to decrease
fragmentation.
2.5r: -s and -o option added.
-s (stack) is specially usefull when ParM is resident because
in this case ParM stack is allways 4000 bytes whereas it takes
the default stack size of your cli when it is not resident. As
all commands run from ParM take as default the ParM stack size
you can specify a higher stack with this option.
2.51r: Minor update. Bug fixes.
ParM no more crashes when run from workbench if arp.library
cannot be found.
2.6r: ParM now implemented as a shared library. This allow BrowserII
to take advantage of ParM's parsing and creating parametrables
menus. Put "parm.library" in LIBS:, and ParM at the same place
as before.
When ParM is used with it's own window, menus short-cuts can
be accessed with Left-Amiga as well as standard Right-Amiga
key, except for M and N which are intuition private.
ParM window is now autofront. (user request).
2.7: -o option now attempt to use NULL: rather than NIL:, which
allow to really redirect output for RUN commands to NIL: or
better to say NULL: ! This prevent programs which open "*"
after the cli from which ParM was run to crash if cli has been
closed. With NULL:, RUN mode is now perfectly safe and should
work in all cases. If NULL: isn't found, NIL: will be used.
'r' removed from version number. Making a version which
doesn't use req.library is no more planned.
2.8: Bug fixes.
Qualifier for menu short-cuts now parametrable.
2.9: Implementation of an input handler in parm.library. It makes
possible to run a command with a hot-key, without touching the
mouse, or to activate ParM's menus without activating ParM's
window.
3.0: As a user request, ParM can now be attached to Workbench, just
like MyMenu. (Code stolen from MyMenu once again). Sorry and
thanks, Darin and John.
ParM now works with Console-Buffer. With some limitations. You
MUST run ParM AFTER CB, and leave ParM BEFORE CB.
You can now put several commands, separated by a ; in RUN mode
and in Command, like in SHELL mode.
3.1: Bug fix in workbench menus coordinates.
3.2: First version of SunMouse/Accelerator...
SetMouse V1.0 for Mouse Opts settings.
Optionnal Mem/Time display in ParM's window.
ParM arguments now handled with GADS() (amiga standard style).
3.3: InputHandler rewritten. Intuition calls done from a separate
process rather than from input-handler (prevent dead locks).
3.4: InputHandler and RUN mode now works under KickStart 2.0.
VGA and SuperHires video modes not yet supported.
Default Shell Command is now NewShell (for OS 2.0).
Default Shell/Command window have 2.0 specifications.
Command in Simple mode is asynchronous under 2.0 and handle
inputs and CTRL-C properly.
SetMouse V1.1. Added Qualifier for WindowToFront.
3.5: Bug fix. (incompatibility between USENULL and CLIWINDOW).
3.6: Bug fix in workbench startup.
ParM can now be attached to Workbench 2.0 menus.
You no more need NULL: under 2.0
Under 2.0, you can specify a console window for the RUN mode.
4.0: Internal. First 2.0 only version.
No more arp nor req libraries.
Handler for SetMouse handle all screen resolutions now.
parm.library NOT compatible with previous releases. You MUST
replace all utilities which use parm.library with new ones.
SHELLCMD, WAITCMD, TMPDIR removed. Remove these commands from
your S:ParM.cfg and S:BrowserII.menu if any.
External command WaitReturn no more needed with /Wait consoles
ParM can no more be made resident. Who used this ?
4.1: Still internal. BarLabel available.
Better handling of ASCII chars > 127 in parse.
4.2: Added REQUEST flag, and WBTF handled in ParM.
Bug fixes.
Tags for NewCreateProc same as Workbench in WBRun().
(More V37.4 crashed in WB mode)
Input Handler initialised in ParMHandlerTask.
CliArg CONFIGFILE/K didn't work.
Added /N for all numerical args in command line.
First special 2.0 release.
4.3: Localized. (Only French available for now).
4.4: Handle Stack in Project icons for WB Startup.
New option NEWLOOKMENUS for AmigaDOS 3.0. This turns off the
possibility to have individual colors for items, but enhance
item highlightening for multicolored screens.
4.5: SHOWMEM now shows Retina available memory if you have such
a board! :-)
4.6: ParM gets a copy of the Workbench's Path when started from
workbench. You can now put it in your WBStartup drawer and
it will run without loosing your path.
Recompiled using SAS 6.50.
Tutorial:
---------
Now you read about all ParM was able to do, I think you'd like to
know which mode you should use to run your favorite tools.
First, when you want to add a manu item, you should know:
1) Does your tool support workbench run ?
2) Do you want your tool to inherit ParM's current dir, or have its own ?
3) Do you want your tool to inherit ParM's CLI Path ?
4) Do you want your tool to use a console window for its output ?
SHELL mode is now the same as RUN but with a default console
if not specified.
So, choice between RUN and WB is easy.
If you need a console or the Path, use RUN mode.
Else, you can use WB mode.
SetMouse:
---------
SetMouse is self explanatory.
WToFront Qual:
Key to be hold while double clicking to bring window to front.
Screen Blank is done by turning off DMA.
Mouse Blank is done by turning off DMA Sprites.
Handler Pri can be changed for eventual compatibility problems with
other input handlers. It is 51 by default. If changed, it will become
active next reset. (Or parm.library must be flushed then reopen)
Note: Mouse utility will be active as long as parm.library has a user.
(BrowserII, ParM, or SetMouse actually).
Acknowledgements:
-----------------
The first release (internal) of ParM was a major rework of MyMenu by
Darin Johnson. The problem was that it wasn't possible to have MyMenu
without workbench, and program started from MyMenu didn't have a Path.
So, lots of thanks to Darin Johnson for menu allocations and workbench
run. The idea of attaching menus to the CLI and some other ideas came
from a friend who also made a menu but wasn't easy to configure.
Thanks to S.R. and P.C. for ParM!
Thanks to Darin Johnson for MyMenu.
Thanks to William S. Hawes for ARexx and WShell.
Thanks to Pierre Ardichvili for his help to me and to Amiga.
Thanks to CygnusSoft and ASDG for their GREAT CygnusEd 2.
Signature:
----------
S.R. & P.C.
This is not Status Register and Program Counter but
Sylvain Rougier & Pierre Carrette.
We are Frenchies so we hope the documentation is readable. We put our
work in making english language comments, but it isn't allways easy,
so be fair with us.
Donations:
----------
This program is not public domain. This program is ShareWare. If you
use it or if you want the last revision, send $10 ($25 for both ParM
and BrowserII) and/or bugs report to:
Sylvain Rougier
39 rue Carnot
86000 Poitiers
France.