Fresh Fish 4

home *** CD-ROM | disk | FTP | other *** search

/ Fresh Fish 4 / FreshFish_May-June1994.bin / bbs / amigalib / d995 / parm.lha / ParM / ParM.DocE < prev next >

Wrap

Text File | 1994-04-05 | 27.8 KB | 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.