! Alan L. Zirkle ! Naval Surface Warfare Center, Dahlgren Division ! Code K55 ! Dahlgren, Virginia 22448 ! 1 ZMENU ! ZMENU is a utility which displays a menu from within a command procedure, allows a user to choose an item from the menu, and notifies the procedure which item was selected so that it can proceed based on this information. To invoke ZMENU, execute: $ ZMENU [menu_text] [qualifiers...] If ZMENU is called from a non-interactive process, or if the menu contains fewer than two selectable items, it exits with a diagnostic. ! 2 Menu_text ! If no parameter is specified on the ZMENU command line, the text of the menu is assumed to be in data lines immediately following the command line in the command procedure (i.e. in the file SYS$INPUT). If a file name is specified, the text of the menu is taken from that file. If no file type is specified, .MENU is assumed. ZMENU first reads in and stores the lines of the menu. Any lines with "!" in column 1 are assumed to be comments and are discarded. Only the first 24 menu lines are used. If the first non-comment line contains "/" in column 1, then it contains ZMENU qualifiers (except /DEBUG and /VERSION). Qualifiers can be placed either on the ZMENU command line, or here. DCL Symbol names in apostro- phes are processed on the qualifier input line. Qualifier values speci- fied on this line override qualifiers on the command line. ZMENU clears the screen, then displays the menu text (with the item markers removed), and a pointer ("-->") which the user can move with the arrow keys. The menu text may include Escape Sequences, and the SI and SO characters, to control the screen appearance. If desired, an upside down question mark "¿" can be used everywhere an ESCAPE character is needed. Use of escape sequences makes screen layout design harder, since the sequences take up columns in the file, but not on the screen. The numbering of items is done by screen column, not file column (i.e. escape sequences are assumed to be absent). On lines with an escape sequence, tabs must not be used after the sequence. Each line must be independent (i.e. if two adjacent lines are to be bolded, both lines must contain the sequen- ces to start and end bolding). ! 2 Input ! When the user enters an ARROW key, the pointer is moved to the next menu item in the direction the arrow key specifies. Any of the four arrow keys (left, right, up, down) can be used. The up and down arrows are circular (i.e. if the down arrow is entered with the pointer already on the last menu item in a column, the pointer moves up to the first menu item in the next column, or to the first column if there are no more columns). When the user enters CTRL/W, the screen is refreshed. When the user enters RETURN, SELECT, DO, or ENTER, then DCL Symbol CHOICE is set to the number of the item at which the pointer currently points, and ZMENU exits. The items are numbered as follows: the upper-left-most item is numbered 1; the search for the next item goes down that screen column, then down the next screen column, etc. A sample numbering of items would be: 1 6 2 7 3 5 4 8 If the user enters "H" or "h" or "?" or PF2 or F15 (HELP), a HELP display appears on the bottom five lines of the screen; it goes away when the user enters a blank. If the /TEXT qualifier is used with option A or K, then "H", "h", or "?" are assumed to be text, not a request for help; PF2 or F15 still work. When no screen I/O is being done, the cursor is left parked near the lower right-hand corner of the screen (line 22, column 80 or column 132) where it is less conspicuous. ! 2 Examples ! To see examples of ZMENU, execute: $ @NSWC$ROOT:[DAT]ZMENU.TEST you may examine the example procedure NSWC$ROOT:[DAT]ZMENU.TEST and the example menu file NSWC$ROOT:[DAT]ZMENU.MENU. ! 2 Clock ! If the string "00:00:00" exists in the menu text, the current time is displayed at that location every five seconds. If this string appears more than once in the file, only the first occurrence is used. ! 2 Qualifiers /BOUND If /BOUND is specified, then the movement of the pointer in response to the up- and down-arrow keys is "bounded"; for example, if the pointer is at the bottom item in a row of items, and the down-arrow is used, the pointer will not move. By default, the movement is unbounded; for example, in the situation described above, the pointer would move to the top of the next row of items, or to the top of the leftmost row of items if it was in the rightmost row. Repeated use of the up- or down-arrow key would cause a circular traversal of all menu items. The movement caused by the left- and right-arrow keys is always bounded. /DEBUG If /DEBUG is specified, then the menu is displayed with the item markers visible, and the number of the item currently being pointed to is shown in the lower righthand corner. Normally blanks are displayed where item markers were located. This option can be used if it is hard to correlate the menu items with the item number output in DCL Symbol CHOICE. /INITIAL If /INITIAL=n is specified, then when the menu is initially displayed, the pointer is positioned at the Nth item, instead of the first item, which is the default. If there is no Nth item, this qualifier is ignored. /ITEM The menu text must contain at least two "item markers". The default item marker is the character "^". You can choose a different item marker by specifying /ITEM="x", where x is the single character you wish to use. Each menu item must be marked in the menu text with this item marker. The markers are not normally displayed; they are replaced with blanks. The menu pointer (usually "-->") is moved between item marker locations with the terminal's arrow keys. The rightmost character of the pointer is placed over the item marker column. Item markers must not be placed so close to the left margin, or to text appearing to the left, so that the pointer will not fit. /NOINTERRUPT If you use the /NOINTERRUPT qualifier, then if the user CONTROL-Ys out of ZMENU, DCL Symbol CHOICE will be set to 0 and no other effects of the interrupt will be visible to the procedure. Otherwise a CONTROL-Y in ZMENU interrupts it normally. /POINTER /POINTER="string" By default, ZMENU uses the pointer "-->". You may specify a different pointer. The pointer may be up to 24 characters long. It may include escape sequences. For example: $ ZMENU /POINTER="¿[1;7m-->¿[m" produces a bold reverse video pointer ( --> ). /START0 If /START0 is specified, then the menu items are numbered (0,1,2,...), not the default (1,2,3,...). The first menu item (number 0) cannot be selected (i.e. if the pointer is on menu item 0, the RETURN, ENTER, SELECT, and DO keys do nothing). Normally, when /START0 is used, menu item 0 has no text associated with it. This is used to help prevent an accidental hit of the RETURN key from exiting the menu before a valid selection is made. (DEC's VMSCAI product uses this in some places.) If /START0 is used with /TEXT options C or K, then when all text is deleted or when invalid text is entered, the pointer will jump to menu item 0 instead of its previous location. /SYMBOLS If /SYMBOLS is specified, then occurences of DCL Symbol names (in apostro- phes) in the menu file are replaced by the current value of the symbols. This allows the displayed text to vary based on the state of the command procedure. Entire lines in the menu can be variable, by substituting in text with "!" in column 1. /TEXT The /TEXT options enable the entry of text in addition to the arrow keys. If you use this, then somewhere in your menu display you must designate an area for the display of the entered text. You do this by using a special character; the default is "\". An example is: ^ Item 1 ^ Item 3 ^ Item 2 ^ Item 4 Text: \\\\\ This example allows up to five characters of text to be entered. The text display area must not extend past column 80. Text is always displayed in bold reverse video. By default, when no text has been entered, ZMENU will display blanks, not "\\\\\", in the text display area. You can choose a different character (such as an underscore), or you can specify a character plus a prefix and a postfix escape sequence. Three text entry options are available: A, C, and K. The /TEXT qualifier must be specified with a character string value, as in the example: $ ZMENU /TEXT="A|_" The first character must be the option. The second character must be the special character used in the menu display to designate the text entry area. The third and subsequent character(s) must be the desired character [plus optional escape sequence(s)] to display in blank text entry columns. For example, to display boldface minus signs in empty columns, specify: $ ZMENU /TEXT="A\¿[1m-¿[m" and have a line in the menu display: Enter text: ¿[1m\\\\\\\\\\\\\¿[m Note that the escape sequences controlling the text entry area must be in both the menu display file and in the /TEXT qualifier. ----- Option A ----- The A option allows the input of arbitrary text, up to 80 characters. The entered text is displayed in the text entry area. The text is cleared out whenever the pointer is moved to another menu item. When ZMENU exits, DCL Symbol ZMENU_TEXT contains the text, or a null string. ----- Option C ----- The C option allows the input of an item number, giving the user the choice of using the arrow keys or entering a number. When a number is entered, the pointer immediately jumps to the specified item; no carriage return is required. If an illegal input is entered, the pointer moves back to where it previously was. ----- Option K ----- The K option allows the input of an item "keyword", giving the user the choice of using the arrow keys or entering a keyword. The text the user enters is uppercased. Keywords are the character strings beginning two columns past the item characters. For example, in the menu: ^ PROCESS ^ Delete ^ EXIT NOW The keywords are "PROCESS", "DELETE" (uppercase), and "EXIT NOW". When a text entry matches a keyword or even the initial part of a keyword, the pointer immediately jumps to the first item with a match; no carriage return is required. If non-matching text is entered, the pointer moves back to where it previously was. /WIDE /WIDE If the /WIDE qualifier is used, the screen is set to 132 columns while the menu is displayed; it is set back to 80 when ZMENU exits if it was 80 before. Note that 132-column menus may be hard to read on some terminals, and if text entry is used (see the /TEXT qualifier), it must not go past column 80. /VERSION If the /VERSION qualifier is specified, ZMENU displays its current version number and creation date, and exits without processing any menu. !