05/02/90  menu_get_choice

Syntax as a command:  menu_get_choice menu_name {-control_args}


Syntax as an active function:  [menu_get_choice menu_name {-control_args}]


Function:  gets a menu choice, given the menu called "menu_name" on
display in a window, from the user and prints or returns it.


Arguments:
menu_name
   is the name that was assigned to the menu when it was stored.


Control arguments:
-default_fkeys STR, -dfkeys STR
   specifies the keys to be used if the terminal does not have function
   keys or the proper set of function keys.  See "Notes on Function
   Keys" below.
-function_keys STR, -fkeys STR
   specifies the keys to be used to simulate function keys.  This
   control overrides any function key definitions already established
   for the terminal.  See "Notes on Function Keys."
-io_switch STR, -is STR
   specifies the name of an I/O switch for a window, where STR is the
   name of an I/O switch for a window.  The default is user_i/o.


-pathname PATH, -pn PATH
   is the pathname of the value segment (of which the value suffix is
   assumed) in which the menu is stored.  If not given, the user's
   default value segment (>udd>Project_id>Person_id>Person_id.value) is
   searched for the menu.


Notes on function keys:  Many terminals have function keys.  On many of
these terminals (such as the Honeywell VIP7801), they are labeled "F1",
"F2", etc.  If you type one of these function keys, menu_get_choice
returns the string "F*", where * is a one- or two-digit number
signifying which function key was pressed.  It is possible to specify
your own set of keystrokes to be used in lieu of the terminal's
function keys, or to specify a set of keystrokes to be used if the
terminal does not have enough function keys.  These are done by using
-dfkeys and -fkeys, which are followed by a string.  Each character in
this string is used to simulate a function key.  The first character is
used to simulate function key 0, the next to simulate function key 1,
etc.  To simulate a given function key, type esc-C, where C is the
character corresponding to the function key.  Thus, if the string is
"0123456789", typing esc-2 returns F2.


The -fkeys control argument is used to designate keystrokes to be used
instead of any that might be defined for the terminal; if given, then
the simulation of function keys always takes place.


The -dfkeys control argument is given if you want to use the
terminal-defined function keys if possible, but wish to specify key
sequences to be used to simulate function keys if necessary.  Each
character in the string following -dfkeys corresponds to one function
key.  If the character is a space, it means it makes no difference if
the terminal has a function key corresponding to that position.  If the
character is not a space, that character is employed to simulate a
function key if necessary.  If the terminal does not have a function
key for every nonspace character in the string, then the -dfkeys string
is used to simulate function keys.


For example, if the string " ?p q" is specified with the -dfkeys
argument, it means that you do not care whether the terminal has a
function key 0, or a function key 3, but you wish to use function keys
1, 2, and 4.  If any one or more of these three function keys is not
defined for the terminal type then the -dfkeys string is used to create
the function key definitions.  IE., esc-?  substitutes for F1, esc-p
substitutes for F2, esc-q substitutes for F4, and no other function
keys are available.  However, if all three of these function keys are
available then no substitution is made and all the function keys
defined for the terminal type are available.


If neither the -fkeys nor the -dfkeys control arguments are used, and
the terminal has no function keys then the default function key string
used is "0123456789".

