!		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 ( [1;7m-->[m ).

/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.
!
