Multics Technical Bulletin MTB 654
To: MTB Distribution
From: N.S.Davids
Date: 04/23/84
Subject: Extensions to menu_
Comments may be made:
Via forum (method of choice):
>site>forum>menus
Via electronic mail:
Davids.Multics
Via telephone:
862-6643
HVN: 356-6643
_________________________________________________________________
Multics Project internal working documentation. Not to be
reproduced outside the Multics Project.
Multics Technical Bulletin MTB 654
CONTENTS
INTRODUCTION. . . . . . . . . . . . . . . . 1
PROBLEMS TO BE ADDRESSED. . . . . . . . . . 1
No prompt line, no default option. . . . . 1
Fixed sized of menus. . . . . . . . . . . . 1
Display of menus already responded to. . . 1
SOLUTIONS. . . . . . . . . . . . . . . . . 2
Add prompt line and default. . . . . . . . 2
Create dynamically sized menus. . . . . . . 2
Example of dynamically sized menu, prompt
line, and a default. . . . . . . . . . 4
Suppress menu display on valid type ahead. 5
IMPLEMENTATION OF SOLUTIONS. . . . . . . . 6
Changes to the menu_format structure. . . . 6
Changes to menu_$create. . . . . . . . . . 8
Changes to menu_$display. . . . . . . . . . 8
Changes to menu_$get_choice. . . . . . . . 9
A new entry: menu_$display_and_get_choice. 9
MENU_ DOCUMENTATION CHANGES. . . . . . . . 10
menu_$create. . . . . . . . . . . . . . . .10
menu_$display_and_get_choice. . . . . . . .10
menu format structure. . . . . . . . . . . 11
menu requirements structure. . . . . . . . 13
Notes on Dynamic Sizing. . . . . . . . . . 14
COMMAND DOCUMENTATION CHANGES. . . . . . . 15
menu_create (new control arguments). . . . 15
menu_create (changes to existing control
arguments). . . . . . . . . . . . . . 16
menu_display_and_get_choice. . . . . . . . 16
Notes on Dynamic Sizing. . . . . . . . . . 17
FT_MENU_ DOCUMENTATION CHANGES. . . . . . 19
ft_menu_$create. . . . . . . . . . . . . . 19
ft_menu_$describe. . . . . . . . . . . . . 20
ft_menu_$set_prompt. . . . . . . . . . . . 20
ft_menu_$set_default. . . . . . . . . . . 21
ft_menu_$display_and_get_choice. . . . . . 22
Notes on Dynamic Sizing. . . . . . . . . . 24
CB_MENU_ DOCUMENTATION CHANGES. . . . . . 26
cb_menu_$create. . . . . . . . . . . . . . 26
cb_menu_$describe. . . . . . . . . . . . . 27
cb_menu_$set_prompt. . . . . . . . . . . . 27
cb_menu_$set_default. . . . . . . . . . . 28
cb_menu_$display_and_get_choice. . . . . . 29
Notes on Dynamic Sizing. . . . . . . . . . 31
Multics Technical Bulletin MTB 654
INTRODUCTION
The development and investigation of menu oriented
applications has made it apparent that the menu_ interface must
move toward a menu_manager_ interface. This is needed to:
o eliminate the need for essentially duplicate code in each
application
o allow functionality that cannot be provided with the
current menu_ interface
o guarantee a uniform display to the user
The migration path from menu_ to menu_manager_ will span
several releases. This MTB presents the steps for MR11.0
PROBLEMS TO BE ADDRESSED
No prompt line, no default option
human factors guidelines(1) for presenting menus indicate that
a prompt should appear under the menu. This prompt indicates
how the user should make a selection and a default value (if
appropriate).
Fixed size of menus
Currently menus are a fixed sized which must be no larger than
the window they are to be displayed in. This requires that
the applications determine the size of the display window and
break up large menus into multiple sub-menus. It also
requires that the applications give the user the capability of
moving through these multiple sub-menus (usually by way of
function keys). An application's function menus are usually
small enough that a minimum window size can be determined for
running the application. However a minimum window size
approach is not possible for "data" menus, i.e. lists of
segments in a directory, mail in a mail box, components in an
archive. Currently an application that presents "data" menus
to the user must implement its own special handling of these
menus.
Display of menus already responded to
When a user becomes familiar with the menus he/she can select
the desired choices before the menu is displayed. There may
be no point in then displaying the menu and making the user
wait for the display to complete.
_________________________________________________________________
(1) Human Factors Guidelines for Terminal Interface Design, CACM
Vol 26 #7 July 1983
MTB 654 Multics Technical Bulletin
SOLUTIONS
The following solutions must be implemented in a manner that
allows the current menu_ behavior to be maintained. Any changes
in behavior will be accomplished via changes in versions and/or
new entry points.
Add prompt line and default
add to the definition of a menu a prompt line and a default
option. The prompt line will appear below the menu (right
above the first trailer) separated from the menu by a blank
line. Prompting will be optional. A default prompt of:
Press number or letter indicating choice
may be used. The default option will be flaged by the ">"
character to the left of the option key in the menu, it will
also appear on the prompt line and will be selected by
pressing the return key.
Press number or letter indicating choice (default X)
The default option is also optional.
The prompt line should only appear when the user must enter a
menu option, i.e. a call to get_choice. Until that time the
line containing the prompt text should be blank. Also after
the user enters a valid option the prompt line should be
blanked, the option the user selected will be indicated via an
* as is currently done.
The inclusion of the default in the menu definition means that
it cannot be dynamically changed, i.e. it cannot be updated
to the users last response to the menu. However, it is
thought that the easier to remember static definition makes
the default more useful.
Create dynamically sized menus
a dynamically sized menu would be automatically fragmented
into sections that could fit in the display window. The
original menu is fragmented when a call is made to display it
and the first sub-menu is actually placed on the screen. A
call to get a choice then internally processes the options
that call for the next or previous sub-menu to be displayed.
When the user finally makes a selection the selection index is
translated back into an index corresponding to the original
large menu.
The last option on the first sub-menu will be:
(>) MENU X+1
The first option on the last sub-menu will be:
(<) MENU X-1
All other sub-menus will have both of the above options
listed.
Multics Technical Bulletin MTB 654
The sub-menus will have the same headers, trailers, pad
characters, and prompt line as the original menu with the
following 2 exceptions. The string:
menu X of Y
will be appended to the first header of all the sub-menus.
The character X will contain the index of the current menu
while Y will contain the total number of menus the original
menu was divided into. If no header is defined one will be
created. All sub-menus which do not contain the original
menu's default option will have as their default either > or <
depending on whether they are before or after the sub-menu
containing the default option. If the original menu does not
have a default defined then none of the sub-menus will have a
default defined.
MTB 654 Multics Technical Bulletin
Example of dynamic menu display, use of a prompt and a default(1)
-----------------------------------------------------------------
Choices (menu 1 of 3)
(1) Abel (5) Carson
(2) Anderson (6) Crawford
(3) Baker (7) Dunn
(4) Brown >(>) MENU 2
Select a name by entering its index (default >)
-----------------------------------------------------------------
-----------------------------------------------------------------
Choices (menu 2 of 3)
(<) MENU 1 (4) Lynch
(1) Fisher >(5) Pace
(2) Gordon (6) Schmidt
(3) Harvey (>) MENU 3
Select a name by entering its index (default 5)
-----------------------------------------------------------------
-----------------------------------------------------------------
Choices (menu 3 of 3)
>(<) MENU 2 (2) Zinn
(1) Tang
Select a name by entering its index (default <)
-----------------------------------------------------------------
_________________________________________________________________
(1) Dashes indicate the extent of the display window.
Multics Technical Bulletin MTB 654
Suppress menu display on valid type ahead
The display mechanism can determine if there is any input
pending before it starts to display the menu. If there is and
the input is valid, i.e. it corresponds to a valid option or
function key then the menu display can be suppressed. Also
since the input has already been checked for and validated, it
makes sense to return it immediately instead of having to call
menu_$get_choice. The menu_$display routine does not include
arguments for function_key definition or for returning the
users selection. A new entry is therefore indicated.
There are two ways to handle the menu display suppression.
The first is to always or never suppress the display for any
valid input, the second is to allow a decision to be made for
each valid input. The first is simpler; the second more
powerful. I think in this case that the extra power is not
called for and therefore the simpler approach is best. Note
that it is user interface simplicity that is of concern - not
implementation simplicity. The relative complexity of the
second approach stems from where to put the suppress flags.
The flags associated with the menu options can be placed in
the menu definition. However, there would still need to be
flags associated with the function keys. These function key
flags could be a separate array or part of the function key
definition structure that is passed in. However, if they are
part of the structure then a translation from the function key
structure returned by the ttt_info_ call would be needed. A
simpler approach might be to keep all the suppress flags in a
separate array that is passed in. The problem with this
approach is the maintenance of keeping the array in sync with
the current menu or maintaining a set of arrays each matched
to one menu.
MTB 654 Multics Technical Bulletin
IMPLEMENTATION OF SOLUTIONS
Changes to the menu format structure
The current structure of menu_format is:
01 menu_format
02 version fixed bin,
02 constraints,
03 max_width fixed bin,
03 max_height fixed bin,
02 n_columns fixed bin,
02 flags,
03 center_headers bit (1) unal,
03 center_trailers bit (1) unal,
03 pad bit (34) unal,
02 pad_char char (1);
where
1. version
must be menu_format_version_1
2. max_width
is the width of the window the menu will be
displayed on. This value is used for centering
headers and aligning columns.
3. max_height
is the maximum height of the window, in lines.
4. n_columns
is the number of columns to be used in displaying
options.
5. center_headers
if set, header lines will be centered using the
window width supplied above. If not set they are
flush left with the left edge of the window.
6. center_trailers
same as center_headers, but for trailers.
7. pad
must be "0"b;
8. pad_char
is the character used for centering headers and/or
trailers.
The addition of a new field is needed to define the default
option.
Multics Technical Bulletin MTB 654
02 default_option fixed bin;
where
9. default_option
is the option index identifying the default option.
A default option is selected by pressing the return
key. The option index corresponds to the default
option's INDEX in the choice array not to the key
used to select the option. The default option will
be flaged by the ">" character to the left of the
option key in the menu, it will also be indicated in
the prompt line by the string:
(default X)
where X corresponds to the KEY that must be pressed
to select the default option. Note that defining a
default option does not require the use of a prompt.
A value of 0 indictes that no default option is
defined.
The addition of a new substructure is needed for defining the
prompt text.
02 prompt,
03 use prompt bit (1) unal,
03 center_prompt bit (1) unal,
03 pad2 bit (34) unal,
03 prompt_text char (80) var,
10. use_prompt
if set to "1"b it indicates that the menu is to have
a prompt string. If set to "0"b it indicates that
the menu will not have a prompt string. If the menu
does not have a prompt string the two extra lines
which the prompt requires will not be included in
the menu.
11. center_prompt
same as center_headers but for prompt. This field
is ignored if the value of use_prompt is set to
"0"b.
12. pad2
must be "0"b
13. prompt_text
is a prompt that will be output after the last line
of the menu. It will be separated from the last
menu line by a blank line. The prompt line will
remain blank until a call which requires the user to
select a menu option is made. At that time the
prompt text will be written on the prompt line.
MTB 654 Multics Technical Bulletin
After the user makes a selection the prompt text is
deleted. The selected option's key is replaced by
an *. This field is ignored if the value of
use_prompt is set to "0"b; If use_prompt is set to
"1"b and this field is blank a default prompt text
of:
Press number or letter indicating choice
will be used.
The OK to dynamically size a menu will be flagged by slightly
changing the meaning of the max_height element. This was done
instead on creating a new flag because it was a reasonable
extension.
3. max_height
is the maximum height of the window, in lines. If
the value of max_height is zero it means that the
menu should be dynamically sized to the height of
the window it is being displayed in.
Finally the version of the structure would be changed to
version 2.
Changes to menu_$create
It will be modified to create a new version menu which will
incorporate the new attributes in the version 2 menu format
structure. It will continue to support version 1 format
structures for compatibility. There will be no limit to the
number of options in a dynamically sized menu. In addition,
the keys argument will be ignored for a dynamically sized
menu.
Ignoring the keys argument for a dynamically sized menu is not
ideal. However, the alternative is to create a special entry
for dynamically sized menus. This new entry would have to
ignore the max_height element of the menu_format structure.
Of course, a new dynamic_menu_format structure could be
defined which does not have the max_height element. This
gives us two entries and 2 structures for doing almost exactly
the same thing. This is less ideal than having 1 entry, 1
structure, and ignoring one of the arguments to that entry in
certain circumstances.
Changes to menu_$display
It will continue to display old version menus and display new
version menus as in the above example. It will fragment
dynamically sized menus into sub-menus whose size depends on
the display window and put the first sub-menu in the window.
A sub-menu will not have more than 61 options in it, (keys 1-9
A-Z a-z). A "window too small" error will occur only if the
Multics Technical Bulletin MTB 654
window is so small that each sub-menu cannot contain at least
1 option from the original menu.
Changes to menu_$get_choice
It will continue to support old version menus and will also
support the new version menu. It will cause the prompt text
to be displayed in the menu and allow the selection of the
default (provided one is defined) by pressing the return key.
In addition, the user will be able to display the various
pages of a dynamically sized menu.
A new entry: menu_$display_and_get_choice
This entry will both display the menu and return the user's
selection. Its calling sequence will look exactly like
menu_$get_choice except for the addition of a suppress_flag
following the function_key_info argument. If the suppress
flag is set, a check is made before the menu is displayed for
pending input. If the input is valid the menu is not
displayed and the selection is return to the user. If the
input is invalid the bell is rung, all other pending input is
purged, the menu is displayed, the prompt (if there is one)
output, and the system waits for the user to enter a new
selection. If the flag is not set the menu will be displayed
and the prompt (again, only if there is one) output, and the
system will wait for the user to enter a selection.
MTB 654 Multics Technical Bulletin
MENU_ DOCUMENTATION CHANGES
Where possible, only changes from existing documentation are
listed.
menu_$create
1. choices (Input)
is an array of the names of the options. Menus may
be dynamically sized or fixed at creation time (see
Dynamic Sizing below). There is no limit to the
number of options of a dynamically sized menu.
Fixed sized menus have a limit of 61 options. The
error code menu_et_$too_many_options will be
returned if a fixed size menu has more than 61
options.
5. keys (Input)
is ignored if the menu is to be dynamically sized.
<rest of existing documentation>
menu_$display_and_get_choice
Entry: menu_$display_and_get_choice
This entry displays a menu and returns the users choice.
If a menu is to be dynamically sized, the first sub-menu is
displayed.
Usage
declare menu_$display_and_get_choice entry (ptr, ptr,
ptr, bit (1) aligned, bit (1) aligned, fixed bin,
fixed bin (35));
call menu_$display_and_get_choice (window, menu,
function_key_info, suppress, fkey, selection, code);
where:
1. window (Input)
is a pointer to the IOCB for the I/O switch used to
display the menu.
2. menu (Input)
is the menu object to be displayed and responded to.
Multics Technical Bulletin MTB 654
3. function_key_info (Input)
is a pointer to a data structure describing the
function keys available on the terminal. This data
structure is obtained by the caller from the
ttt_info_$function_key_data subroutine. If this
pointer is null no function keys are used.
4. suppress (Input)
if set a check is made before the menu is displayed
for pending input. If input is pending and it is
valid the display of the menu is suppressed and the
input is returned. If the input is not valid then
all pending input is purged, the bell is rung, the
menu is displayed, the prompt (if there is one)
output, and the system waits for the user to enter a
new selection. If suppress is not set this routine
functions like the sequence of calls:
menu_$display, menu_$get_choice.
5. fkey (Output)
returns a value of "1"b if a function key was hit
instead of a menu selection.
6. selection (Output)
gives the option number or function_key number
chosen by the user. For an option, it is a number
between 1 and the highest defined option, inclusive.
For a function key, it is the number of the function
key.
7. code (Output)
is a standard error code.
The menu format structure
A menu is described by the "menu_format" structure. It is
declared in menu_dcls.incl.pl1
dcl 1 menu_format aligned based (menu_format_ptr),
2 version fixed bin,
2 constraints,
3 max_width fixed bin,
3 max_height fixed bin,
2 n_columns fixed bin,
2 flags,
3 center_headers bit (1) unal,
3 center_trailers bit (1) unal,
3 pad bit (34) unal,
2 pad_char char (1);
2 default_option fixed bin,
MTB 654 Multics Technical Bulletin
2 prompt,
3 use_prompt bit (1) unal,
3 center_prompt bit (1) unal,
3 pad2 bit (34) unal,
3 prompt_text char (80) var;
where
1. version
may be either menu_format_version_1 or
menu_format_version_2
2. max_width
is the width of the window the menu will be
displayed on. This value is used for centering
headers and aligning columns.
3. max_height
is the maximum height of the window, in lines. If
the value of version is menu_format_version_2 then
the value of max_height may be 0 which means that
the menu should be dynamically sized to the height
of the window it is being displayed in. If the
value of version is menu_format_version_1 and the
value of max_height is 0 an error will be returned.
4. n_columns
is the number of columns to be used in displaying
options.
5. center_headers
if set, header lines will be centered using the
window width supplied above. If not set they are
flush left with the left edge of the window.
6. center_trailers
same as center_headers, but for trailers.
7. pad
must be "0"b;
8. pad_char
is the character used for centering headers and/or
trailers.
9. default_option
Is used only if version is set to
menu_format_version_2. It is the option index
identifying the default option. A default option is
selected by pressing the return key. The option
index corresponds to the default option's INDEX in
the choice array not to the key used to select the
Multics Technical Bulletin MTB 654
option. The default option will be flaged by the
">" character to the left of the option key in the
menu, it will also be indicated in the prompt line
by the string:
(default X)
where X corresponds to the KEY that must be pressed
to select the default option. It is legal to have a
default option defined without defining a prompt
string. Also a value of 0 indictes that no default
option is defined.
10. use_prompt
if set to "1"b it indicates that the menu is to have
a prompt string. If set to "0"b it indicates that
the menu will not have a prompt string. If the menu
does not have a prompt string the two extra lines
which the prompt requires will not be included in
the menu.
11. center_prompt
same as center_headers but for prompt. This field
is ignored if the value of use_prompt is set to
"0"b.
12. pad2
must be "0"b
13. prompt_text
is a prompt that will be output after the last line
of the menu. It will be separated from the last
menu line by a blank line. The prompt line will
remain blank until a call which requires the user to
select a menu option is made. At that time the
prompt text will be written on the prompt line.
After the user makes a selection the prompt text is
deleted. The selected option's key is replaced by
an *. This field is ignored if the value of
use_prompt is set to "0"b. If use_prompt is set to
"1"b and this field is blank a default prompt text
of:
Press number or letter indicating choice
will be used.
The menu requirements structure
2. lines_needed (Output)
is the number of lines required. A value of 0
indicates that the menu is to be dynamically sized.
If non-zero and the window does not have this number
of lines, menu display will fail.
MTB 654 Multics Technical Bulletin
Notes on Dynamic Sizing
A dynamically sized menu is automatically fragmented into
sub-menus that will fit in the display window. The original
menu is fragmented when a call is made to display it and the
first sub-menu is actually placed on the screen. A call to
get a choice then internally processes the options that call
for the next or previous sub-menu to be displayed. When the
user finally makes a selection, the selection index is
translated back into an index corresponding to the original
large menu.
The last option on the first sub-menu will be:
(>) MENU X+1
The first option on the last sub-menu will be:
(<) MENU X-1
All other sub-menus will have both of the above options
listed.
The sub-menus will have the same headers, trailers, pad
characters, and prompt line as the original menu with the
following 2 exceptions. The string:
menu X of Y
will be appended to the first header of all the sub-menus,
where X is the index of the current menu and Y is the total
number of sub-menus the original menu was divided into. If no
header is defined one will be created. All sub-menus which do
not contain the original menu's default option will have as
their default either > or < depending on whether they are
before or after the sub-menu containing the default option.
If the original menu does not have a default defined then none
of the sub-menus will have a default defined.
Multics Technical Bulletin MTB 654
COMMAND DOCUMENTATION CHANGES
Where possible, only changes from existing documentation are
listed.
menu_create (new control arguments)
-prompt STR, -pmt STR
specifies a prompt line that will be displayed after the
last line of the menu. It will be separated from the
last menu line by a blank line. A default prompt of:
Press number or letter indicating choice
will be used if STR is a null string. The prompt will be
displayed only when a call is made that requires the user
to select a menu option. After the user makes a
selection the prompt text is deleted. The selected
option's key is replaced by an *.
-no_prompt, -npmt
indicates that there should be no prompt line. This is
the default.
-default_option STR, -dopt STR
specifies the default option which is selected by
pressing the return key. If STR contains blanks or
special characters it must be quoted. If multiple
default_options are specified the last one becomes the
default, the others are just regular options. The
default option will be flaged by the ">" character to the
left of the option key in the menu, it is also indicated
to the user by the string
(default X)
appended to the prompt. X corresponds to the KEY that
must be pressed to select that default option. It is
legal to have a default option defined without defining a
prompt string.
-no_default_option, -ndopt
indicates that there should be no default option. This
is the default.
-center_prompt, -cep
causes the prompt to be centered.
-no_center_prompt, -ncep
causes the prompt to be flush left. This is the default
-dynamic, -dyn
causes the menu to be dynamically sized when it is
displayed. This means that if the display window is
MTB 654 Multics Technical Bulletin
smaller than the menu the menu will be fragmented into
several sub-menus for display purposes. See "Notes on
Dynamic Sizing".
-no_dynamic, -ndyn
requires that the menu be displayed as one unit. This is
the default.
menu_create (changes to existing control arguments)
-option_keys STR, -okeys STR
specifies the keystrokes to be used with each option.
Each character in STR is associated with the
corresponding option, so that if it is typed, the
corresponding option is selected. There must be at least
as many characters in STR as there are options. If this
control argument is not given, the string
"123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ" is used. This
control argument is ignored if the menu is to be
dynamically sized.
menu_display_and_get_choice
Name: menu_display_and_get_choice
The menu_display_and_get_choice command, given a menu
name, will display that menu and gets the user choice.
Usage
menu_display_and_get_choice menu_name {-control_args}
Syntax as an Active Function
[menu_display_and_get_choice menu_name {control_args}]
where:
1. menu_name
is the name assigned that was assigned to the menu
to be displayed when it was stored. If the menu is
to be dynamically sized the first sub-menu is
displayed.
2. control_args
Multics Technical Bulletin MTB 654
may be chosen from
-pathname PATH, -pn PATH
is the name of the value segment in which the
menu has been stored. The value suffix is
assumed. If this control argument is omitted,
the user's default value segment is searched
for the menu.
-io_switch STR, -is STR
where STR is the name of an I/O switch for a
window. The default is user_i/o.
-default_fkeys STR, -dfkeys STR
specifies the keys to be used if the terminal
does not have function keys or if the terminal
does not have 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"
below.
-suppress, -sup
indicates that a check is to be made before the
menu is displayed for any pending input. If
input is pending and it is valid the display of
the menu is suppressed and the input is
returned. If the input is not valid then all
pending input is purged, the bell is rung, the
menu is displayed, the prompt (if there is one)
output, and the system waits for the user to
enter a new user selection.
-no_suppress, -nsup
indicates that this command will function like
the sequence of commands: menu_display,
menu_get_choice. This is the default.
Notes on Dynamic Sizing
A dynamically sized menu is automatically fragmented into
sub-menus that will fit in the display window. The original
menu is fragmented when a call is made to display it and the
first sub-menu is actually placed on the screen. A call to
get a choice then internally processes the options that call
for the next or previous sub-menu to be displayed. When the
MTB 654 Multics Technical Bulletin
user finally makes a selection the selection index is
translated back into an index corresponding to the original
large menu.
The last option on the first sub-menu will be:
(>) MENU X+1
The first option on the last sub-menu will be:
(<) MENU X-1
All other sub-menus will have both of the above options
listed.
The sub-menus will have the same headers, trailers, pad
characters, and prompt line as the original menu with the
following 2 exceptions. The string:
menu X of Y
will be appended to the first header of all the sub-menus.
The character X will contain the index of the current menu
while Y will contain the total number of menus the original
menu was divided into. If no header is defined one will be
created. All sub-menus which do not contain the original
menu's default option will have as their default either > or <
depending on whether they are before or after the sub-menu
containing the default option. If the original menu does not
have a default defined then none of the sub-menus will have a
default defined.
Multics Technical Bulletin MTB 654
FT_MENU_ DOCUMENTATION CHANGES
Where possible, only changes from exiting documentation are
listed.
ft_menu_$create
1. choices (Input)
is an array of character variables which are the
text of the options that the user wishes to display
in the menu. n1 is the length in characters, of the
longest character string comprising the text of an
option. m1 is the extent of the array, i.e. the
number of options in the menu being described. This
array must be at least extent 1. If
menu_format(max_height) (see item 4 below) has a
value of 0 there is no limit to the number of
options that the menu may have. If the value is
non-zero there may be at most 61 menu options.
4. menu_format (Input)
is an array, which specifies the format of the menu
being created. Prior to calling this entry point,
the FORTRAN programmer is responsible for setting
the following variables:
menu_format(menu_version) = version number of menu
format. May be 1 or 2. If 2 the menu may
have a prompt text and a default option
defined. See ft_menu_$set_prompt, and
ft_menu_$set_default.
menu_format(max_width) = maximum width of the window
on which the menu will be displayed.
menu_format(max_height) = maximum height of window
on which menu will be displayed. If
menu_format(menu_version) is equal to 2
then this may be equal to 0 which will
indicate that the menu is to be
dynamically sized. See "Notes on Dynamic
Sizing" below.
menu_format(no_of_columns) = number of columns to be
used by the menu manager to display the
options.
menu_format(center_headers) = 0 or 1; 0 = no, 1 =
yes.
menu_format(center_trailers) = 0 or 1; 0 = no, 1 =
yes.
6. keys (Input)
is an array that identifies the keystroke to be
associated with each choice. This array must be at
MTB 654 Multics Technical Bulletin
least as long as the number of choices in the menu.
Each element in the array must be unique. If
menu_format(max_height) is is zero then this
argument is ignored.
7. menu_needs (Output)
an array that contains menu related information on
successful execution of call.
Returned information:
menu_needs(lines_needed) the number of lines
required to display the menu. A value of
0 indicates that the menu is to be
dynamically sized.
menu_needs(width_needed) the number of columns
required to display the menu.
menu_needs(no_of_options) the number of options
defined in the menu.
ft_menu_$describe
2. menu_needs (Output)
an array into which menu related information is
returned.
Returned information:
menu_needs(lines_needed) the number of lines
required to display the menu. A value of
0 indicates that the menu is to be
dynamically sized.
menu_needs(width_needed) the number of columns
required to display the menu.
menu_needs(no_of_options) the number of options
defined in the menu.
ft_menu_$set_prompt
Entry: ft_menu_$set_prompt
Sets the prompt line for a menu created with a menu
format version equal to 2. An error will be returned if the
indicated menu was created with a menu format version equal to
1. The prompt line will be output after the last line of the
menu and be separated from that line by a blank line.
Multics Technical Bulletin MTB 654
Usage
declarations:
integer menu_id
character*80 prompt_string
integer no_prompt
integer center_prompt
integer code
call ft_menu_$set_prompt (menu_id, prompt_string,
no_prompt, center_prompt, code)
where:
1. menu_id (Input)
the menu identifier returned by ft_menu_$create or
ft_menu_$retrieve
2. prompt_string (Input)
a new prompt string. A null string will cause the
default prompt:
Press number or letter indicating choice
to be used. The prompt line will remain blank until
a call which requires the user to select a menu
option is made. At that time the prompt text will
be written on the prompt line. After the user makes
a selection the prompt text is deleted. The
selected option's key is replaced by an *.
3. no_prompt (Input)
a non-zero value indicates that the menu should not
have a prompt text defined. The prompt_string and
center_prompt arguments are ignored. If 0 it
indicates that the menu's prompt text and the
prompts centering attribute are to be defined by
this call.
4. center_prompt (Input)
a value of 0 indicates that the prompt should start
at the menu's left margin. A non-zero value
indicates that the prompt should be centered.
5. code (Output)
return code (see Appendix B.)
ft_menu_$set_default
Entry: ft_menu_$set_default
MTB 654 Multics Technical Bulletin
Sets the default option for a menu created with a menu
format version equal to 2. An error will be returned if the
indicated menu was created with a menu format version equal to
1. The default option is selected by pressing the return key.
It is flaged by the ">" character to the left of the option
key in the menu, and is also indicated to the user by the
string "(default X)" on the prompt line. X is the key that
would be pressed to select the default option. It is legal to
have a default option defined without defining a prompt
string. Also a default option of 0 indicates that no default
option is to be definded for the menu.
Usage
declarations:
integer menu_id
integer default_option
integer code
call ft_menu_$set_default (menu_id, default_option, code)
where:
1. menu_id (Input)
the menu identifier returned by ft_menu_$create or
ft_menu_$retrieve
2. default_option (Input)
The index of the default option in the choices array
that was used to create the menu. A value of 0
indicates that no default option is to be defined.
3. code (Output)
return code (see Appendix B.)
ft_menu_$display_and_get_choice
Entry: ft_menu_$display_and_get_choice
This entry displays a menu and returns the users choice.
If a menu is to be dynamically sized the first sub-menu is
displayed.
Usage
Multics Technical Bulletin MTB 654
declarations:
character*n1 function_key_info
integer window_id
integer menu_id
integer suppress
integer fkeys
integer selection
integer code
call ft_menu_$display_and_get_choice (window_id, menu_id,
function_key_info, suppress, fkeys, selection, code)
where:
1. window_id (Input)
a window identifier returned by ft_window_$create.
If usage_mode = 0 this argument will be ignored.
(see ft_menu_$init2).
2. menu_id (Input)
the menu identifier returned by ft_menu_$create or
ft_menu_$retrieve
3. function_key_info (Input)
a character variable (n1 as required) used to
specify the role of function keys (if they exist for
the terminal being used) or an equivalent set of
escape sequences if the terminal does not have
function keys or not the function keys required by
the application. The objective is to let the
application use the terminal's function keys if
possible, else specify key sequences to be used to
simulate function keys. Each character in the
string corresponds to one function key. If the
character is a space, then it is not relevant if the
corresponding function key exists or not. If the
character is not a space, that character will be
used to simulate a function key if the terminal does
not have function keys. If the terminal does not
have a function key for every non-space character in
the string, then the function keys will be
simulated. Thus, the string " ?p q" means that the
caller does not care whether the terminal has
function keys 0 or 3 but the caller does wish to use
function keys 1, 2, and 4. If any of these 3
function keys is not present on the terminal, then
esc-? will substitute for F1, esc-p will substitute
for F2 and esc-q will substitute for F4.
4. suppress (Input)
MTB 654 Multics Technical Bulletin
if non-zero a check is made before the menu is
displayed for pending input. If input is pending
and it is valid input the display of the menu is
suppressed and the input is returned. If the input
is not valid then all pending input is purged, the
bell is rung, the menu is displayed, the prompt (if
one is defined) is output, and the system waits for
the user to enter a new selection. If suppress is
set to 0 then this routine functions like the
sequence of calls: ft_menu_$display,
ft_menu_$get_choice.
5. fkeys (Output)
if fkeys = 1 user entered a function key or escape
sequence if fkeys = 0 user selected an option.
6. selection (Output)
is an integer representing the choice made by the
user. If the user has chosen an option, it is the
number between 1 and the highest defined option. If
the user has entered a function key, or escape
sequence simulating a function key, it is the number
associated with the function key.
7. code (Output)
return code (see Appendix B.)
Notes on Dynamic Sizing
A dynamically sized menu is automatically fragmented into
sub-menus that will fit in the display window. The original
menu is fragmented when a call is made to display it and the
first sub-menu is actually placed on the screen. A call to
get a choice then internally processes the options that call
for the next or previous sub-menu to be displayed. When the
user finally makes a selection, the selection index is
translated back into an index corresponding to the original
large menu.
The last option on the first sub-menu will be:
(>) MENU X+1
The first option on the last sub-menu will be:
(<) MENU X-1
All other sub-menus will have both of the above options
listed.
The sub-menus will have the same headers, trailers, pad
characters, and prompt line as the original menu with the
following 2 exceptions. The string:
menu X of Y
Multics Technical Bulletin MTB 654
will be appended to the first header of all the sub-menus,
where X is the index of the current menu and Y is the total
number of sub-menus the original menu was divided into. If no
header is defined one will be created. All sub-menus which do
not contain the original menu's default option will have as
their default either > or < depending on whether they are
before or after the sub-menu containing the default option.
If the original menu does not have a default defined then none
of the sub-menus will have a default defined.
MTB 654 Multics Technical Bulletin
CB_MENU_ DOCUMENTATION CHANGES
Where possible, only changes from exiting documentation are
listed.
cb_menu_$create
1. choices_table (Input)
is a table of elementary data items which are the
text of the options that the user wishes to display
in the menu. n1 is the length, in characters, of
the longest character string comprising the text of
an option. m1 is the extent of the table, i.e. the
number of options in the menu being described. This
table must be at least of extent 1. If max_height
(see item 4 below) has a value of 0 there is no
limit to the number of options that the menu may
have. If the value is non-zero there may be at most
61 menu options.
4. menu_format (Input)
is a group item defining the format of the menu
being created.
In the COBOL program the caller is responsible for
setting the following elementary data items:
menu_version The version of the menu format.
May be 1 or 2. If 2 the menu may have a
prompt text and a default optioned
defined. See cb_menu_$set_prompt and
cb_menu_$set_default.
max_width maximum width of the window on
which the menu is to be displayed.
max_height maximum height of the window on
which the menu is to be displayed. If
menu_version is equal to 2 then this may
be equal to 0 which will indicate that the
menu is to be dynamically sized. See
"Notes on Dynamic Sizing" below.
no_of_columns number of columns to be used to
display the options.
center_headers 0 or 1; 0 = no, 1 = yes
center_trailers 0 or 1; (same as center_headers)
5. keys_table (Input)
is a table that identifies the keystroke to be
associated with each choice. This table must be at
least as long as the number of choices in the menu.
Each element in the table must be unique. If
max_height is 0 this argument is ignored.
Multics Technical Bulletin MTB 654
6. menu_needs (Output)
a group item that contains menu related information
on successful execution of call.
Returned information:
lines_needed the number of lines required to
display the menu. A value of 0 indicates
that the menu is to be dynamically sized.
width_needed the number of columns needed to
display the menu.
no_of_options the number of options defined in the
menu.
cb_menu_$describe
2. menu_needs (Output) a group item that contains menu
related information on successful execution of call.
Returned information:
lines_needed the number of lines required to
display the menu. A value of 0 indicates
that the menu is to be dynamically sized.
width_needed the number of columns needed to
display the menu.
no_of_options the number of options defined in the
menu.
cb_menu_$set_prompt
Entry: cb_menu_$set_prompt
Sets the prompt line for a menu created with a menu
format version equal to 2. An error will be returned if the
indicated menu was created with a menu format version equal to
1. The prompt line will be output after the last line of the
menu and be separated from that line by a blank line.
Usage
declarations:
77 menu_id USAGE IS COMP-6
77 prompt_string PIC X(80)
MTB 654 Multics Technical Bulletin
77 no_prompt PIC 9(1)
77 center_prompt PIC 9(1)
77 ret_code USAGE IS COMP-6
call "cb_menu_$set_prompt" USING menu_id, prompt_string,
no_prompt, center_prompt, ret_code.
where:
1. menu_id (Input)
the menu identifier returned by cb_menu_$create or
cb_menu_$retrieve
2. prompt_string (Input)
a new prompt string. A null string will cause the
default prompt:
Press number or letter indicating choice
to be used. The prompt line will remain blank until
a call which requires the user to select a menu
option is made. At that time the prompt text will
be written on the prompt line. After the user makes
a selection the prompt text is deleted. The
selected option's key is replaced by an *.
3. no_prompt (Input)
a non-zero value indicates that the menu should not
have a prompt text defined. The prompt_string and
center_prompt arguments are ignored. If 0 it
indicates that the menu's prompt text and the
prompts centering attribute are to be defined by
this call.
4. center_prompt (Input)
a value of 0 indicates that the prompt should start
at the menu's left margin. A non-zero value
indicates that the prompt should be centered.
5. ret_code (Output)
return code (see Appendix B.)
cb_menu_$set_default
Entry: cb_menu_$set_default
Sets the default option for a menu created with a menu
format version equal to 2. An error will be returned if the
indicated menu was created with a menu format version equal to
1. The default option is selected by pressing the return key.
It is flaged by the ">" character to the left of the option
Multics Technical Bulletin MTB 654
key in the menu, and is also indicated to the user by the
string "(default X)" on the prompt line. X is the key that
would be pressed to select the default option. It is legal to
have a default option defined without defining a prompt
string. Also a default option of 0 indicates that no default
option is to be definded for the menu.
Usage
declarations:
77 menu_id USAGE IS COMP-6
77 default_option USAGE IS COMP-6
77 ret_code USAGE IS COMP-6
call "cb_menu_$set_default" USING menu_id,
default_option, ret_code
where:
1. menu_id (Input)
the menu identifier returned by cb_menu_$create or
cb_menu_$retrieve
2. default_option (Input)
The index of the default option in the choices array
that was used to create the menu. A value of 0
indicates that no default option is to be defined.
3. ret_code (Output)
return code (see Appendix B.)
cb_menu_$display_and_get_choice
Entry: cb_menu_$display_and_get_choice
Returns the choice made by the user, i.e., a number
representing either the menu item chosen or the function key
(or its equivalent escape sequence) entered. If a menu is to
be dynamically sized the first sub-menu is displayed.
Usage
declarations:
MTB 654 Multics Technical Bulletin
77 function_key_info PIC X(n1)
77 window_id USAGE IS COMP-6
77 menu_id USAGE IS COMP-6
77 suppress USAGE IS COMP-6
77 fkeys USAGE IS COMP-6
77 selection USAGE IS COMP-6
77 ret_code USAGE IS COMP-6
call "cb_menu_$display_and_get_choice" USING window_id,
menu_id, function_key_info, suppress, fkeys, selection,
ret_code.
where:
1. window_id (Input)
a window identifier returned by cb_window_$create.
If usage_mode = 0 this argument will be ignored.
(see cb_menu_$init2).
2. menu_id (Input)
the menu identifier returned by cb_menu_$create or
cb_menu_$retrieve
3. function_key_info (Input)
a character variable (n1 as required) used to
specify the role of function keys (if they exist for
the terminal being used) or an equivalent set of
escape sequences if the terminal does not have
function keys or not the function keys required by
the application. The objective is to let the
application use the terminal's function keys if
possible, else specify key sequences to be used to
simulate function keys. Each character in the
string corresponds to one function key. If the
character is a space, then it is not relevant if the
corresponding function key exists or not. If the
character is not a space, that character will be
used to simulate a function key if the terminal does
not have function keys. If the terminal does not
have a function key for every non-space character in
the string, then the function keys will be
simulated. Thus, the string " ?p q" means that the
caller does not care whether the terminal has
function keys 0 or 3 but the caller does wish to use
function keys 1, 2, and 4. If any of these 3
function keys is not present on the terminal, then
esc-? will substitute for F1, esc-p will substitute
for F2 and esc-q will substitute for F4.
4. suppress (Input)
Multics Technical Bulletin MTB 654
if non-zero a check is made before the menu is
displayed for pending input. If input is pending
and it is valid input the display of the menu is
suppressed and the input is returned. If the input
is not valid then all pending input is purged, the
bell is rung, the menu is displayed, the prompt (if
one is defined) is output, and the system waits for
the user to enter a new selection. If suppress is
set to 0 then this routine functions like the
sequence of calls: cb_menu_$display,
cb_menu_$get_choice.
5. fkeys (Output)
if fkeys = 1 user entered a function key or escape
sequence if fkeys = 0 user selected an option.
6. selection (Output)
is an integer representing the choice made by the
user. If the user has chosen an option, it is the
number between 1 and the highest defined option. If
the user has entered a function key, or escape
sequence simulating a function key, it is the number
associated with the function key.
7. code (Output)
return code (see Appendix B.)
Notes on Dynamic Sizing
A dynamically sized menu is automatically fragmented into
sub-menus that will fit in the display window. The original
menu is fragmented when a call is made to display it and the
first sub-menu is actually placed on the screen. A call to
get a choice then internally processes the options that call
for the next or previous sub-menu to be displayed. When the
user finally makes a selection, the selection index is
translated back into an index corresponding to the original
large menu.
The last option on the first sub-menu will be:
(>) MENU X+1
The first option on the last sub-menu will be:
(<) MENU X-1
All other sub-menus will have both of the above options
listed.
The sub-menus will have the same headers, trailers, pad
characters, and prompt line as the original menu with the
following 2 exceptions. The string:
menu X of Y
MTB 654 Multics Technical Bulletin
will be appended to the first header of all the sub-menus,
where X is the index of the current menu and Y is the total
number of sub-menus the original menu was divided into. If no
header is defined one will be created. All sub-menus which do
not contain the original menu's default option will have as
their default either > or < depending on whether they are
before or after the sub-menu containing the default option.
If the original menu does not have a default defined then none
of the sub-menus will have a default defined.