.ap .lm 5 .rm 70 .hl1 MENU MENU is a program that reads "menu files", and creates menus which the user can then use to select items and cause things to be done. MENU provides the menu builder with a fairly simple, yet fairly robust set of options to create menus. The current implementation is geared towards single column menus, with the standard up _& down arrow or item name selection generally found in simple menus. A second "free flow" type of menu is also supported, although there isn't support for selecting items via arrow key manipulation. Menus are composed of instructions that create title lines (text lines), item lines (which describe an item that can be selected with the arrow keys), and command lines (lines that define "hidden" items, or otherwise affect menus). .hl2 Menu command procedure The command procedure MENU.COM can be used to start up MENU, it can be modified to suit site/application specific needs. You should probably just start using menu by defining a symbol such as: .literal $ MENU :== "@dev[dir]MENU MAIN dev:[dir].MENU .end literal The command procedure uses the first argument (P1) to determine the name of the menu file, and the second (P2) as the default filespec to use when opening the menu. P3 determines which (sub)menu is the current menu to display. P4 determines where the arrow will be displayed. P5 contains any pending commands. The above symbol definition therefore starts up menu using the menu file MAIN.MENU. .hl2 (Sub)Menu name The Menu name (or submenu name) is declared on a line starting with a percent sign. This is the name used to reference the (sub)menu from within a different menu. In general, it is a good practice to set the first menu name to be the same as the file name, so for instance, if you were to create MAIN.MENU, you would want the first menu in the menu file to be started with: .literal %MAIN .end literal Note that you can have default options which will be applied to all menus in the menu file by placing them before the first menu occurs in the file. These include such things as hidden menu items, wait prompt, selection prompt, and the separator character. .hl2 Title (text) lines A title line is one that simply describes a line and how it will appear on the screen. This is handy for title lines, and for "free flow" menus. What I describe as a "free flow" menu is one in which you simply present a page of text, with "item" keywords displayed in bold. For every "item" you declare a hidden item using the same name as the bolded word in the text. The format of a title line is: .literal % text justification .end literal The line must begin with a percent sign, be followed by some text, followed by some separator character (by default a comma), followed by a justification keyword, one of CENTER, LEFT, or RIGHT. An unrecognized justification keyword will be treated as LEFT. As with all text that can be displayed, you may enter formatting options, as follows: .list "o";Formatting options: .le;_^b = bolded video rendition .le;_^f = flashing video rendition .le;_^n = normal video rendition .le;_^r = reverse video rendition .le;_^u = underline video rendition .end list A caret, followed by any other character, will be replaced by that character. Note that video renditions are accumulative. For example, to display a line of text with a bolded word in it, center justified, you could use: .literal %the word ^bbold^n is ^bbold^ned,center .end literal The separator character doesn't have to be a comma. You can change it with the following menu command: .literal !>SEPARATOR=character .end literal See the section on 'command lines' for more information on the !>SEPARATOR command. .hl2 Item lines An item line describes a selectable item. There are hidden items and displayable items. A hidden item start with "!>HIDE=" and lacks a description but is similar to a displayable item in all other respects. Furthermore, a hidden item can occur before the first menu has been started, in which case the item is available to all menus in the menu file in which it occurs. The format of a displayable item is as follows: .literal item-nameitem-descriptioncommand[optional...] .end literal The item name is a keyword that can be entered to select the item and cause the command associated with that item to be executed. The item description is simply text that gets displayed. Note that you can use the formatting options as described in the 'Title Lines' section on both the item name and the item description. .list "o";The command must be one of the following: .le;$ command Do the command 'command'. Also, sets the MNU$WAIT symbol, according to the value given by a preceding !>WAIT command. After the command completes the arrow will return to this item, unless instructed to do otherwise. The arrow can be forced to return to a different item by using the DEFAULT option. The FORCE option can be used to force other items to be selected and executed exactly as if the user had typed in the option, in which case the arrow will move accordingly. .le;_^ menu-name Try loading an internal menu (by the name of 'menu-name'). If an internal menu isn't found, then try loading an external menu. This allows you to build a complex menu system that can get treated differently depending on how you set it up, so that, for instance, when you are interpreting it the menu loads only a little bit at a time, and when you wish to compile it, all the menus get loaded at once (by having different main menus). .le;< menu-file Load an external menu file (by the name of 'menu-file'). The first menu in the external menu file will be the menu displayed. .le;> menu-name Load an internal menu (by the name of 'menu-name') .le;* internal-command Performs an internal command - currently EXIT, SPAWN, COMPILE, and DTR are allowed. SPAWN can be followed by a command to be spawned via lib$spawn. COMPILE causes an interpreted menu to be compiled. An already compiled menu will just exit the image. EXIT will exit the image and force the command procedure to exit,by performing a "$GOTO END__OF__COMFILE" command. DTR can be used to send a command to Datatrieve. This option exists to demonstrates how/why you might want to add your own internal commands. There isn't an automatic method provided for doing this, however, if you edit LOOP.C, and search for DTR, you should be able to figure out how to change it or add another. In any case, the DTR option currently starts a Datatrieve backend process (if it needs to), which it sends commands to via a mailbox. This saves a lot of Datatrieve initialization time (except of course the first time it gets called). For an example of a menu that uses this, check out MAIN__4.MENU. Note that you need Datatrieve to use this command! .end list .list "o";The optional parameters are keyword parameters and are: .le;DEFAULT=default Determines where the arrow will be placed after the command is executed .le;FORCE=item Forces the item(s) to execute as though user typed them in. Note that you specify the item names in the same way as the user would. You can specify multiple items by separating them with a dash. .le;HELP=helpfile|helptopic This is used when the help key is pressed, this overrides the current menu default. Note the "|" between the helpfile and helptopic. The helpfile or helptopic can be left blank, in which case the menu wide default is applied. The menu default can be used to set the helpfile, and this option can be used to then set a help topic. Of course, this could be used to override the current help file as well. .le;PARAMS=numparams Currently not implemented, force user to enter this many parameters .le;PROMPT=prompt If no parameters were passed, user will be prompted with this string. Parameters are indicated by a leading space, or a slash. The parameter will be concatenated with the command string and the new command string will then be executed. This works for external commands, and for the internal spawn command. If you wish to make it impossible to pass excess parameters with a command, you could end the command with an exclamation point "!", causing the parameters to be ignored. .le;WAIT=string Set the MNU$WAIT symbol to this string, this overrides the current menu default. The MNU$WAIT symbol is used in the MENU.COM file, if it is not empty then the string is used as a prompt causing a wait in the menu loop. Waiting will also occur for the internal spawn command if requested. .end list .hl2 Comment lines A line beginning with an exclamation point is a comment line. Comments aren't allowed to be just anywhere, you must waste a whole line on them. A comment line can not start with "!>" as that is reserved for special commands. .hl2 Command lines A line beginning with "!>" is a command line. There are several commands. If these commands occur before the first menu in a file, they are taken to be menu-wide defaults. So, for example, if you want a hidden command EXIT in all your menus, you could define a menu-wide EXIT command by putting a hidden menu item before the first menu. .list "o";Commands .le;!>INCLUDE=includefile Includes data from a separate file, this is usefull for menu file initialization. Include files can be nested as deeply as you have quota for (i.e. Authorize parameter FILLM). .le;!>ALIGN All menu item descriptions get lined up, according to the size of the largest displayable item name. .le;!>NOALIGN Menu item descriptions don't get lined up. .le;!>ARROW=arrow This defines the pointer. It can be formatted (see 'Text Lines'). .le;!>NUMBERS Menu item names are to be preceded by a line number (which can be used to choose an item). .le;!>NONUMBERS Menu item names are not to be preceded by a line number. .le;!>KEY=key-definition A key definition looks like .literal Key-name "Definition"[qualifiers] .end literal where the allowable qualifiers are /[NO]ECHO, /[NO]TERMINATE This is similar to the DCL command DEFINE/KEY. .le;!>SEPARATOR=character This determines the character to use as a separator in commands where a separator is required. .le;!>WIDTH=width (decimal) This determines the width at which to display the menu. Note that the terminal width is returned to its original value whenever the menu program exits. .le;!>HELP=helpfile|helptopic This sets the help file and help topic to be used when the help key is pressed. Generally this is used to point at the help file to be used for the menu, and the items themselves declare a help topic to be used. .le;!>PROMPT=prompt This is the menu selection prompt, which appears towards the bottom of the screen (actually, currently hard-coded to line 22). .le;!>WAIT=string This is a string to set the MNU$WAIT symbol. This string is displayed as a prompt after execution of the item, causing a wait to occur until the user types return. This symbol is used in MENU.COM. If the symbol is set to nothing then no prompting (thus no waiting) will occur. This is also used for the internal spawn command. .le;!>DEFAULT=default Default item for arrow to appear on, when menu is displayed. .le;!>HIDE=itemname,command,optional_parameters This looks just like a displayable item line, except it's missing the description, since it will never be displayed. See description above. This allows you to have hidden commands, this is usefull for example, for defining an EXIT command, and other commands that you don't want to waste menu space on, or that you simply don't want the casual user to know about (i.e. SPAWN), or for creating a "free flow" or "in-text" type of menu. .end list .hl2 Default Settings .list "o" .le;ALIGN Item alignment is enabled. .le;ARROW=-> (With a trailing space) .le;HELP=| No help library or topic. .le;NONUMBER Line numbers are not displayed. .le;SEPARATOR=, .le;PROMPT=Enter selection (With a trailing space) .le;WAIT=Press return to continue (With a trailing space) .le;WIDTH=80 .end list .hl2 Editing keys .list "o" .le;prev__screen (not currently implemented) .le;_^b, up Move the selection arrow up one line. If at top it loops to the bottom. .le;next__screen (not currently implemented) .le;down Move the selection arrow down one line. If at bottom it loops to the top. .le;help Display help, as defined by the menu _& item helpfile|helptopic setting. .le;_^z Causes the internal exit command to be executed. .le;f10 "EXIT" is returned for this. .le;do, _^m, Process the command that the arrow is on .end list Note that the function keys can be redefined via !>KEY statements. (Control keys can't be redefined though, i.e. _^Z) .hl2 Compiling Menus can be "compiled". To do so, you need to create a menu item that executes the internal command "compile". For example, you could use lines similar to: .literal !>HIDE=!@#COMPILE,*compile !>HIDE=!@#COMPILE!,*compile .end literal Then, to compile the menu, load it up and type in "!@_#COMPILE". This will force the compile to begin. This is a very slow process. Several files will be created, using the name of the menu file as a prefix. A C main program (quite minimal), and four macro files will be created, as well as a command procedure to compile and link the mess. This command procedure is then executed. The reason I use two lines above is to force the command to have to be written out in full, otherwise it would be easy to accidentally cause a compile to happen. By using "!@_#COMPILE" and "!@_#COMPILE!" you are forced to enter all of "!@_#COMPILE" since anything less would be ambiguous. .hl2 Example Menus .rm 132 .keep .nofill .no flags all MAIN_1.MENU .require "main_1.menu" MAIN_2.MENU .require "main_2.menu" MAIN_3.MENU .require "main_3.menu" MAIN_4.MENU .require "main_4.menu"