Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 552.lha / ParM_v3.0 / ParM.docE.pp / ParM.docE

Wrap

Text File | 1991-09-09 | 26.7 KB | 634 lines

Documentation for ParM 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. Building: ParM was made using AztecC 5.0a, CygnusEd release 2, and ARexx 1.10. File headers are done in such a way compilation can be launched from Ced. I use my own DevKit, completely rewritten since the original 1.2 version of the DevKit wasn't working at all. ParM needs arp.library version 39 and req.library version 1. I wrote my owns libraries for the Manx linker. The ones used here are called arps.lib and req.lib. The arps.lib provides a small startup code and glues for arp functions that cannot be prototyped, and the req.lib is the reqglue.o given with CygnusEd rewriten as a library. Installation: Put ParM with its icon 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. Make sure you have arp.library 39.1 or higher and req.library too. 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. 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 "-w" option or any of the window options. You should then "RunBack" it to be able to close the CLI later. Don't use arp ARun with NOIO because some programs don't like it, and those will not run from ParM. Warning: you shouldn't run ParM with "Run >NIL: ParM" because it would be detached from the CLI but still keep the console for it's default input and output file handles and some commands in RUN mode may crash if you 'EndCLI' before. Or you can do it but use -o option then. Note that RunBack use the C:Run command and you should place the arp version of the Run command of your C: directory if you want to use ParM as resident. 3) ParM can be attached to Workbench, ala MyMenu. ParM have some options which are available for most either from WorkBench or from CLI. Two of them are only available from CLI. "-w" since ParM allways open its own window when run from WorkBench and '-o' because it is the default when run from WorkBench. Option list: CLI WB -m MYMENU Attach menus to Workbench's. (Like MyMenu). -w (CLI only) Open its own window rather than taking CLI's one. -x LEFTEDGE Left edge of ParM Window (default 0) -y TOPEDGE Top edge of ParM Window (default 0) -d DETAILPEN Detail pen of ParM Window (default 3) -b BLOCKPEN Block pen of ParM Window (default 2) -c MENUCOLOR Color for ParM's main menu (default: Detail Pen) -r NODRAGBAR No drag bar (You can't move ParM), =1 to activate -g DEPTHGADGETS Depth gadgets, =1 to activate -s STACKSIZE Default stack size for commands (not parm's stack) -f CONFIGFILE Configuration file. -o Redirect output to NULL: for commands in RUN mode. -h or anything else to get help when run from CLI. To use workbench tool types, just use the keyword followed by an "=" and the value needed. For example DETAILPEN=1 this is equivalent to RunBack >NIL: ParM -d1 when run from CLI. if you specify any of the -x,-y,-d,-b,-g,-r options when run from cli, a window will be open and -w option is useless. 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:0/11/640/100/Command Window". This should be placed anywhere in the file but better be at top of it. SHELLWIN console_name This will override the default console used for SHELL commands which is "CON:0/11/640/100/ParM Shell". This should be placed anywhere in the file but better be at top of it. SHELLCMD command This will override the default command used to create an interactive shell, which is AShell. For example, if you own WShell, you can use NewWSH here. This should be placed anywhere in the file but better be at top of it. WAITCMD command This will override the default command used to wait for a user input telling to close the shell (default: WaitReturn). This should be placed anywhere in the file but better be at top of it. TMPDIR path This will override the default temp directory used for SHELL scripts which is T:. If your directory isn't in the root of the device, that is to say the dir name doesn't end with a colon (for example T:), you must append a slash '/' to your dir name (for example RAM:T/). 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". To help you experiment raw key code, there is a debug version of the library given. All you have to do is put it in your LIBS: directory. Make parm.library is not already loaded. Copy parm.library.debug libs:parm.library Run ParM -w Then, a window prints what follows: Class SubClass Code Qualifier. These codes are in hex, and you must convert them to hex for ParM. Only Code and Qualifier are usefull to the user. Once you got the codes you need, put back the normal parm.library in your LIBS: 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 (Amiga gauche) ACTIVATEKEY PASSTHROUGH 64 50 (Amiga gauche - 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 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. Command syntax is decribed below. command_def Programs can be run in four ways: ARUN, 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) ARUN syntax ARUN [WIN console_window] [STACK n] [PRI n] command [args] This mode should be used for most of your needs. The console window is now optionnal. This is a CreateProc() style mode. Some programs don't like it, but there is not many. For example scripts cannot be executed. As a general rule, you shouldn't use this mode for commands of the C: directory. Use RUN instead. This mode has the same limitations as the arp ARun command. Actually, the console is immediately closed after the program ends. We hope to fix this in a future release. For example, I use this mode to Format my floppies, and I see in a little window the format process. Commands cannot be redirected in this mode. Note: The ARUN mode with a console (ARUN WIN console) is the same as the old CLI mode. So, you can do a search/replace with your favorite editor to update your old config file to a version >= 2.2 of ParM. ( CLI ==> ARUN WIN ) 2) RUN syntax RUN [STACK n] [PRI n] 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, this is why you should use the ARUN mode as often as possible. Redirection can be done in this mode. 2) SHELL syntax SHELL [WIN console_window] [STACK n] [PRI n] command [args][;command [args]]... This mode creates an interactive shell. This mode should be used for scripts that needs input from the user. If the bit s of your script file is set, it is automaticaly sourced (No need of the execute command). One more feature of this mode is that you can specify several commands separated by semicolons, ie: CD SYS:Utilities;Dir In fact, ParM creates a script file in a temporary directory which is T: by default. So you can make a real script file. Type it normaly, and then, put a semicolon at each end of line, and join all the lines. You can then submit this line to ParM as a command. If a command needs a semicolon, you can put it after the override char '\'. Usualy, semicolons are taken as comment delimiters. If no console is specified, a parametrable default console will be used for the shell. 4) 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. For all modes but WB, your command is searched first in arp 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. Cmd Mode: Two modes are available. Simple and Shell. The current mode is checkmarked. This modes are for the Command command (see below) In 'Simple' mode, ParM will stay busy while your command isn't finished, where as in Shell mode, Command is asynchronous. To do that, an interactive shell is created, and your(s) command(s) is (are) put in a startup file. There is an (s) because in this mode, you can put several commands separated by semicolons. Same rules as SHELL mode in config file. If you own WShell and use PatchDOS, you will have access to all WShell facilities. (alias, residents commands...). Command: Allows you to execute a single CLI command. Change Dir: Changes ParM current directory. Commands run in all modes but WB will inherit ParM 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. WaitReturn: The WaitReturn is used by the Command command if in Shell mode. This one can also be made resident. You can use it in your scripts. It just wait for the user to hit return. Limitations: Scripts won't run in ARUN mode, use RUN or SHELL mode instead. 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 -o option to avoid trashing of your cli window. In this case, commands will be detached. ParM can be made resident only with the arp ARes command. Because ParM is not really pure, when it is resident, ParM duplicates its data and bss. Only arp make it possible to know if we are resident or not, and then, ParM will never copy its data if it is made resident with the commodore method. So I allways use the arp Run command to run parm since the arp Run first searches commands in the arp resident list. In MyMenu mode, if you use Command in Simple mode, Workbench will be inactive until command is finished and window closed. Known bugs: Specified PRI in SHELL mode isn't used. Pri is allways 0. Future plans: - Decrease code size under 2 K !!! - Make a single asynchronous Command Mode which doesn't use any disk loaded command. 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. 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. Great thanks to Olaf 'Olsen' Barthel for his update of arp startup for manx 5.0, the code from which I made my own libs. Thanks also to Colin Fox and Bruce Dawson for their fantastic req.library. We encourage every programmers to use it. Every professionnal software producers should at least have a look at the file requester. 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 ShearWare. If you use it or if you want the last revision, send donation and/or bugs report to: Sylvain Rougier Coiffure W 39 rue Carnot 86000 Poitiers France.