AMenu v1.3 (Anthony's Menu) Documentation AMenu is a complete reprogramed version of Darin Johnson's `MyMenu v1.0' from `Fish Disk 225'. Its purpose is to attach extra menus to the workbench menus and execute commands when selected. The original program `MyMenu' had a number of problems. Commands run in the CLI always had a current directory of the boot device and failed if no disk is present in that device. Also the stack size for the commands was fixed to 4000 bytes, too small for many such commands. Further more, if any program changes the Preferances of the workbench (Programs such as Preferences, AudioMaster, and many WordProcesses), the extra menus will be disconnected and need to be reattached by manually restarting MyMenu to continue their use. Also MyMenu required the Tool of a Project that was run in WB mode to have an attached icon. AMenu solves all these problems. The default current directory for CLI type commands is now selectable and defaults to the assigned `SYS:' directory rather than the boot device. Commands can also have their current directory, run prioity and stack size individually set. Commands can also be run with a console which will accept input as well as ouput to/from the command. Titles or comment items can also be added to the menus, and more style and coloring options are available and spacing between menus can also be adjusted to the users desire. The format for AMenu's script file is greatly different to that of MyMenu. Instead a structured format is used simular to another MyMenu derivative, `ParM' (Fish Disk 375). This format allows the addition of columned menus to AMenu and the ability to modify the style of a sub-menu after the head item of the sub-menu is given. AMenu performes more extensive error checking than MyMenu in both the reading of the configuration file and in the command execution making it easier on the user to debug his menus. MyMenu often just does nothing on an error, leaving the user in the dark. To top all this off, the size of the AMenu-Handler (the resident controlling program) is smaller than that of the MyMenu-Handler! ( AMenu-Handler - 4780 bytes vs. MyMenu-Handler - 5412 bytes ) I renamed MyMenu to AMenu so as to avoid any confusion in thier config files which are incompatable and to differentate my version from any future releases he may care to make. (Apology to Darin) Installation: NOTE: The "ARP.Library" (version 35 or greater) must be installed in the "L:" directory. AMenu does not directly require the "Run" command in "C:" as did MyMenu. Copy "AMenu-Handler" to the "L:" directory. AMenu will also look for this file in the current directory if it does not exist in the "L:" directory. Simularity the file "AMenu.Config" should be in the "S:". If not present, AMenu will also look in the current directory. If you already have a "MyMenu.Conf" in your "S:" directory, rename it "AMenu.Config", and then edit it to convert any `CLI' command execution mode to the AMenu's equivelent mode `RB' (RunBack). After that it is a matter of grouping items in the same menu together and changing the structure to the format given in the sample config file, and this manual. Running: Syntax : AMenu [quit] The command "AMenu" will load and start up the handler process. Or if already running, it will re-parse the configuration file. The quit argument will remove AMenu, and has been throughly checked for memory leaks. MyMenu does have a leak of about 40 bytes. ASIDE: It seems almost all Manx pograms have this leak. Configuration file: "AMenu.Config" is stored in the "S:" directory but is also looked for in the current directory. If any names used in the config file contain white space or non alpha-numeric characters they should be quoted, a single word name however does not need quotes. Example: "SubMenu ->" A Comment can appear almost anywhere in the command file. The only axception is after the name of a command to execute is given in an ITEM statement. In this case the comment would be thought to be part of the arguments to the command itself and executed when the command is executed. A comment is prefaced with a `#' character and then everything from there, up to and including the end of line. Example: # This is a comment is ignored by AMenu as a Comment! COLOR fore back - Text Color ( default is black on white ( 2 1 ) ) TCOLOR fore back - Title Color ( default is black on orange ( 2 3 ) ) These statements define the colors to use in the creation of the MenuItems that follow. COLOR is used for command items while TCOLOR is the coloring of menu titles (Menu Comments). Note:- The Menus use the same general background color as workbench and thus the default colors for TITLE's is really, black text on orange background on a white menu. STYLE COMP - highlight menu items by inverting colors (Default) STYLE BOX - highlight by drawing a box around them. Select the style to use in highlighting menu items that follow. After the STYLE statement either BOX or COMP must be given. This is only used for command items and sub-menu names. Menu titles contain no highlighting as they perform no action when selected. MENUGAP n - Gap between menus (default as per workbench menus ) This command defines the amount of space (in characters) to add when creating a new menu. The value is only used when a new menu name is given in the MENU command intailing the creation of another menu. To have the menus as close togetter as possible use a value of 1. If the value is too big, menus may overflow the screen which AMenu will warn you about but will continue regardless. DIRECTORY full-dir-path ( Default "Sys:" ) This statement defines the default current directory to use to find and execute commands. If this command is not given the current directory defaults to the assigned "Sys:" directory (Not the Boot device (DF0:) as MyMenu does). It should be defined only once in a file and if multiply defined only the last will be used. The DIR command-modifier works from this directory path, so you need not give a full pathname to individual commands (using less memory to store). CONSOLE console-name ( Default "CON:100/11/200/20/AMenu Command" ) This sets the name of the console to use for commands with the execution-mode CLI. This can be changed on an individual basis using the CON command modifier. As with DIRECTORY only one of these should be given if at all. If more than one is fould only the last will be used. MENU [COLUMNS n] menu-name ENDMENU SUBMENU [COLUMNS n] submenu-name ENDSUBMENU These statements define the overall menu structure. The COLUMNS option is a new feature which allows the user to define the number of columns the menu is to spread its element over. If COLUMNS is not given it defaults to the normal value of one column. Items in a menu are arranged in column order as showen in the figure below. A SUBMENU command must occur within a MENU structure and under the current scheme of intuition, you are not allowed a "SUBSUBMENU" within a SUBMENU. The ENDMENU statement is actually not needed as another MENU statement (or end of file) following implys the end of the previous menu. The same is true for ENDSUBMENU but is required if more items follow in the surrounding MENU structure (as in the figure below). _________________________________________________________ ________|_Menu_|_________________________________________ | Title Item 5 | | Item 1 Item 6 _|___________________ | Item 2 SubMenu| Sub 1 Sub 3 Sub 4 | | Item 3 Item 7 |_Sub_2_________Sub_5_| |__Item_4____________| ^. Space left by SKIP! Figure: a 2 column menu with 3 column sub-menu. TITLE title-name SKIP ITEM item-name [] | exec-mode [modifiers] command command-args These three elements and any SubMenu names form the contents of any particular menu. They are added to the current menu in the order given in columns. The number of elements stored in each column is decided by AMenu by dividing the number of elements given in a particular menu by the number of columns that menu has and can be adjusted using SKIP statements. (See SKIP below). The TITLE element defines an menu item which is a comment. Selecting this item does nothing. In fact it will not even highlight when the mouse is over it. A collection of these could be used to make a type of menu note about something. The coloring for this element is defined with the TCOLOR statement and is often used to make a title standout from the normal ITEM's. They are most commonly used at the top of the first column but can appear anywhere. SKIP is used to leave gaps in the menu structure, or to insure AMenu correctly arranges the elements in the appropiate columns. It up no memory as it doesn't add any new menu elements to the menu. IE no cost. WARNING: Skip'ed space on the edge or bottom of a menu may be removed automatically by the intuition menu display routines and thus ignored in the final display of the menu. If you really want the space on the edge of the menu use a TITLE element with TColor set to 1 1 (white text on a white background on a white menu) to make it invisible. ITEM define the actual job of AMenu. When such a element is selected the command given is run in background using one of three styles of execution. The optional is used as a menu key shortcut by pressing the Right-Amiga key and that letter. It must be surrounded by <>'s if given. NOTE: This also adds a Amiga-letter symbol to the displayed menu element. The vertical bar `|' is used to seperate the menu definition from the command definition. Following this is one of three exec-modes notifing AMenu the method in with the command is to be run. RB or RUNBACK - the command is executed in "RunBack" or "ARun NOIO" style. This is equivelent (but not same as) the CLI command execution mode used in MyMenu. No console is provided and any output will be lost. CLI - a console is opened for the command to output to or recieve input from. The console will automatically close on the command exit. and can be defined using the CONSOLE command globally or using the CON modifer locally (See below). (New to AMenu) SCR or SCRIPT - This is equivelent to the command `NewCLI' or `AShell'. This starts a new shell window, with the command given being used as a `FROM' script file. If the script does not end in a `EndCLI' command the console will then become an interactive shell window. A good script to use is "S:Shell-Startup" which will start a normal shell window. WB - The command is run as if started from the Workbench As from AMenu v1.3 this command has been fixed so that it works correctly for projects (as if just the project was double-clicked) as well as tools. It does this in a way that also avoids a bug in the lattice C startup code (See WBTests.txt). The following modifiers allow the user to change the way the environment is set up when this command is executed. Zero or more the following can be used :- PRI prioity-number ( All modes ) Sets the prioity to somthing other 0 the default prioity. Eg: -20 will run only if nothing else does. This is to be used with caution as a bad prioity could cause problems on the system. I suggest you only use the range -20 to 5. STK stack-size ( All Modes ) This uses a different stack size for the command other than the default size of 4096. For WB mode the stack is set to this ONLY if the stack setting in the icon executed is less than this or non-existant. IE: the larger of the two is used for the tool. DIR dir-path ( Any Mode but WB ) Use this dir-path as the current directory for the command. This path is from the default directory given with the DIRECTORY command above. The current directory for WB programs is that of the tool executed. CON console-name ( CLI and SCR modes only ) Use a different console window, for this particular command or script than that set with the CONSOLE command above. After these options the command name wust be given. After the command is given the rest of the line is treated as arguments to that command. NOTE:- WB and SCR modes ignores these arguments completely. Examples: Item "JrComm" | WB Sys:Tools/Comms/JrComm Executes the command "JrComm", stored in the directory "Sys:Tools/Comms", using the current defaults, and executed as if started by workbench. SubMenu "AMenu ->" Title " AMenu " Item "Rebuild" | RB Dir Utilities AMenu Item " QUIT " | RB Dir Utilities AMenu quit EndSubMenu Defines a sub-menu with a title to execute the command "AMenu" stored in the directory "Utilities" off the default directory (probably SYS: is not set) with different arguments. NOTE: This is segested way to execute AMenu from itself. It assumes that the "AMenu.Config" file is stored either in the "S:" directory where it should be or in the "Utilities" directory (the current directory for command). Other Notes on Config: The case of all Statements words used in AMenu is ignored. While the case for names is recored literally. Line breaks can occur at any time in any statement and is treated as normal white space. The ITEM command is no different in this respect until the command name is given. After the command name, ALL TEXT until the end of line is treated as the commands argument and as such can't be broken by newline characters, nor should it contain a comment. Line Breaks are ok in the following : ITEM Archologist | RB DIR NetHack: STK 8000 NetHack -A -u Archie Illegal Line break in this menu command : ITEM Archologist | RB DIR NetHack: Stk 8000 NetHack -A -u Archie AMenu uses the "AmigaDOS Replacment Project" or ARP Library. In particular it uses "ASynchRun()" function rather than the AmigaDOS "Execute()" to execute CLI and RB commands. This function will NOT execute scripts directly (reporting an error to that effect). To execute a script use the following method. Note however that the script should end in "EndCLI" to close the window. ITEM ExecuteScript | RB NewCLI con: FROM script-file Re-Compiling: Version 1.1 of AMenu (unreleased) was a complete reprogram of MyMenu v1.0. I added all the new commands above but retained the orignal single "MENU" statement for all menu elements. AMenu v1.2 only reprogramed the files "Parse.c" and "Menu.c" to add structuring statements and remove the named searches of menus already created. This simplified "Menu.c" and allowed the addition of columns, recursive menu positioning, and the ability to change menu style between the declaration of a SubMenu and the first element in the submenu. For "AMenu-Handler", I use a C startup file "_main.c" rather than "lib:c.o". I did this as AMenu-Handler is a Process, but, must not wait for a nonexistant WBStartup message. Also "lib:c.o" is very large, 1136 bytes, while "_main.o" is only 164 bytes. A considerable difference in size (and memory usage). Version 1.3 is a rewrite of the Workbench startup code to stop some annoying bugs and the addition of my "ArpC" Arp library startup code. Limitations, bugs, and other wierd things: The search path for commands is only the current dir (set with DIR or the default DIRECTORY) and the "C:" directory. I do not at this time intend expanding this path. Though I do know how to do so. Acknowledgements: by Darin Johnson Matt Dillon - Ideas for menu building and how to load in the handler were taken from DME and DMouse. Peter da Silva - Ideas taken from wblaunch program. Rob Peck - Some ideas and help. Davide Cervone - LOTS of ideas taken from MonIDCMP. by Anthony Thyssen Darin Johnson - for MyMenu the best command menu program (until now) Doug Walker - C startup methond used in "_main.c" for AMenu-Handler and ArpC startup code for ARP programs. ARP Team - for ARP, Prog. Guild, and ARun as an example Sylvain Rougier & Pierre Carrette - auther of ParM for structured menu style NOTE:- Much of the code from ParM v1.3 was taken from MyMenu but these pirates (no offence) make no mention of this fact, thus claiming it is all their own work. They should have done so. (In a latter release of ParM SR & PC did make small mention in their programs history) Signature: Anthony Thyssen (Dragon Computing), co/ Commodore Computer Users Group (Qld) Inc. P.O. Box 274, Springwood, Qld., Australia, 4127 Beware, The light at the end of the tunnel may be a oncoming dragon!