Subroutine MENU - Documentation
------------------------------

Note: Even though this subroutine was specifically written and tested in
MS QUICKBASIC 3.0 and 4.0, it could probably be used in TURBO BASIC
as well with little or no modifications. To use it in BASICA, however,
extensive modifications would have to be done.

1) Overview
--------

This subroutine lets you create professional menus similar to LOTUS (tm),
SIDEKICK (tm) and other professional software. When this subroutine is
invoked from a QUICKBASIC program, it displays a 2 dimensional menu on the
screen, consisting of various items. You define those items in the calling
program, and pass it to the subroutine as a 2 dimensional array parameter.
The top left item is initially highlighted, and subsequently the highlight
moves left, right up or down as the left, right, up or down arrow key is
pressed. When the left arrow key is pressed while the highlight is on the
left, the highlight goes to the right. When the right arrow key is pressed
while the highlight is on the right, the highlight goes to the left. When
the up arrow key is pressed while the highlight is on the top, the
highlight goes to the bottom. When the down arrow key is pressed while
the highlight is on the bottom, the highlight goes to the top. When
the first letter of a menu item is pressed, the highlight goes to
that item. If there are several items with the same first letter, the
first menu item matching the letter is highlighted. When an item
is highlighted, an optional help line corresponding to that item is
displayed. The calling program may define those help lines, and pass
them to this subroutine as a parameter array.
When the ENTER key is pressed, the subroutine returns control to the
calling program, and sets the parameters VMENU% and HMENU% to the row
and column of the menu item that was highlighted when the ENTER key was
pressed. If Esc was pressed, VMENU% and HMENU% are both set to 0. The
calling program may then decide what to do based on the values returned.

2) Description of parameters: See actual coding example in next section.

Notes: a) All parameters ending with a % must be passed as integer type
variables or constants.
b) All values for foreground and background colors must conform
to the rules specified in the description of the COLOR
statement for text mode in your BASIC manual for the type of
monitor you are using. If you have a monochrome monitor, or
if you are not familiar with the various color codes, then
the following is the safest to use: 7 (white) for foreground
colors, and 0 (black) for background colors. Use the opposite
for highlighting foreground and background colors (0, 7).
Incorrect color values may yield unpredictable results.
c) All values for row and column must be within the limits of the
number of rows and columns of your monitor. Most monitors have
80 columns and 24 rows. You also have to make sure that all
menu rows and help lines, if any, should fit on the same
line, otherwise unpredictable results may occur.
VMENU%,HMENU% - See last paragraph of overview section.

ROW%, COL% - Row and column of the screen, where leftmost top item
will be displayed.
VAR$() - An 2 dimensional array defining all menu items. If the
1st dimension is 1, a one row menu will be displayed. If
the 2nd dimension is 1, a one column menu will be
displayed.

VSPACING% - Number of line spacing between menu rows.

HSPACING% - Number of spaces between menu columns.

FG%, BG% - Foreground and background colors of the menu items.

HLFG%, HLBG% - Foreground and background color of the highlighted item.

HELP$() - A 2 dimensional array defining all help lines. If not
used, it must still be dimensioned to (1,1) in the
calling program by a statement DIM HELP$(1,1) for
consistency, but the array elements don't have to be
defined in that case.

HROW%, HCOL% - Row and column of the screen, where help line will be
displayed. Must be supplied, even if not used.

HFG%, HBG% - Foreground and background colors of the help lines.
Must be supplied, even if not used.

3) Coding example:

DECLARE SUB MENU (VMENU%, HMENU%, ROW%, COL%, VAR$(), VSPACING%, _
HSPACING%, FG%, BG%, HLFG%, HLBG%, HELP$(), HROW%, HCOL%, HFG%, HBG%)

DIM VAR$(2, 3), HELP$(2, 3)

VAR$(1, 1) = "HELP "
VAR$(1, 2) = "ADD "
VAR$(1, 3) = "UPDATE"
VAR$(2, 1) = "DELETE"
VAR$(2, 2) = "INFO "
VAR$(2, 3) = "BROWSE"

HELP$(1, 1) = "DISPLAY HELP INFO"
HELP$(1, 2) = "ADD RECORD "
HELP$(1, 3) = "UPDATE RECORD "
HELP$(2, 1) = "DELETE RECORD "
HELP$(2, 2) = "INFO ON RECORD "
HELP$(2, 3) = "BROWSE DATABASE "
CLS

CALL MENU(VMENU%, HMENU%, 2, 3, VAR$(), 3, 2, 7, 0, 0, 7, HELP$(), 15, 1, _
7, 0)

IF VMENU% = 1 AND HMENU% = 1 THEN CALL HELP
IF VMENU% = 1 AND HMENU% = 2 THEN CALL ADD
IF VMENU% = 1 AND HMENU% = 3 THEN CALL UPDATE
IF VMENU% = 2 AND HMENU% = 1 THEN CALL DELETE
IF VMENU% = 2 AND HMENU% = 2 THEN CALL INFO
IF VMENU% = 2 AND HMENU% = 3 THEN CALL BROWSE

To use this subroutine from your program, you must do one of the following:
a) Merge the source MENU.BAS to your program.
b) Compile the source separately, and put it on a Library (.LIB) or
Quicklibrary (.QLB). In QUICKBASIC 3.0 put it on a Userlibrary.
See your QUICKBASIC manual for details.

If you are satisfied with this software, please send a check or money
order for $20.- (U.S. funds drawn on a U.S. bank only) to the following
address:

Hermann Edelstein
4 Albert Drive
Monsey, N.Y. 10952

This registration fee also entitles you to the following:

a) BOX - A couple of QUICKBASIC subroutines that let you draw boxes on
the screen while in text mode.
b) You may get future releases of MENU at a nominal fee.