Category : Dbase (Clipper, FoxBase, etc) Languages Source Code
Archive   : MENUMA1.ZIP
Filename : MENUS.DOC
Note: If you are upgrading from an earlier version, follow the
instructions in the Upgrading to New Version section at the end of
this document.
Menu Maker (MM) is a set of FoxBase programs and data files which
provide an organized method for creating the user interface for
any custom system. MM allows you to quickly and easily create the
menu system for your program. In addition, with MM the creation
of the menu interface automatically provides an outline of your
system, as the commands executed by each menu option are an
integral part of the menu system.
The menus created by MM are 3-D, pop-up menus with full
functionality. You have complete control over size, colors,
position, and help information. Each menu features:
- Full light bar control with cursor movement keys
-
- Brief one line help message for highlighted option
- Detailed help via F1 key for highlighted option
- Quick Keys to access procedures from any menu
MM consists of a complete set of procedures for creating,
modifying, and operating these menus. No programming is required
to set up the menus. Menus are created and modified quickly and
easily. Providing help information via the F1 key is just a
matter of typing in help text. In addition, the special Quick
Keys option allows the developer to activate procedures via any
key combination from any menu. The Quick Keys provide system
users with convenient options from every menu, and give the
developer tremendous flexibility. Lastly, MM creates a report
which displays clearly and concisely the outline of the system at
the menu level.
MM is shareware. If you use MM and feel that it is worthwhile,
please send $50 to:
Peter Wagner
11 Monroe Rd.
Wellesley, MA 02181
I also appreciate any and all comments, suggestions, and/or
criticisms.
What's on the Diskette
The diskette contains five files: DEMO.ARC, LOOSE.ARC,
PROCEDURE.ARC, PKXA.COM, and
DOCUMENT.TXT.
DOCUMENT.TXT is this document. The three .ARC files are sets of
archived files. In order to use them, you must un-archive them
using the PKXA.COM utility. LOOSE.ARC, PROCEDURE.ARC, and
DEMO.ARC must be un-archived in their own subdirectories as they
contain files with the same names. Create a directory for each of
these that you think you may use.
To un-archive a set of files using PKXA do the following:
1) Copy the desired .ARC file and the PKXA.COM file to the
directory where you wish to store the un-archived files.
2) Type "PKXA
the .ARC file that you wish to un-archive.
DEMO.ARC contains a sample menu system complete with help and
Quick Key functions. This is a mock system - executing an option
on these menus does not do anything except display a message.
LOOSE.ARC is the collection of data files, index files, and
program files necessary for running MM in non-procedure mode. The
program files in LOOSE.ARC are not compiled.
PROCEDUR.ARC is the collection of data files, index files, and
program files necessary for running MM in procedure mode. The
source code file for the procedure file, MENUS.PRG, does not
contain headers for the procedures. For header information on
each procedure and a brief description, see the individual program
files in LOOSE.ARC.
The difference between LOOSE.ARC and PROCEDURE.ARC is in the
structure of the program files. The former contains individual
program files, while the latter contains a procedure file and the
two user modifiable programs - ENVIRON.PRG and BACK.PRG.
If the Procedure version of MM is used, the procedure file can
never be closed, therefore no other procedure files can be used.
If you use other procedure files, use the files in LOOSE.
There are two procedures that are not contained in the procedure
file MENUS.PRG. These procedures, ENVIRON.PRG and BACK.PRG, can
be modified by the developer to customize the background screen
and to set up the environment for procedures that are run off the
menus.
You will also find a Fox program, TOOLS.FOX, that has some handy
reference utilities for developers.
USING MENU MAKER
The Structure
In order to understand the workings of MM, the structure of the
system is outlined below in some detail.
MM uses four data files:
1> MENUS.DBF index file: MENUS.IDX
2> HELP.DBF index file: HELP.IDX
3> QUICKEYS.DBF index file: QUICKEYS.IDX
4> MENUPARS.DBF
These files must be contained in the active directory.
MENUS.DBF contains the parameters for each menu including:
- Menu Name
- Menu ID
- Number of Menu Options
- Menu Width
- Upper Left Corner
- Initialization String
- Level Above Background
- 10 Menu Option fields
- 10 Menu Brief Help text fields
- 10 Command fields
- Assorted internal flags
Menu Name is the name of the menu which will appear at the
upper right corner of the screen when the menu is active.
Menu ID is the internal ID for the menu. The top level menu
of the system always has ID 1. The menus below the top are
numbered according to the number of the option that calls the
menu; the number of the option that calls a menu is added to
the ID of the calling menu to create the called menu's ID.
For example, a menu called by option 6 on menu 1 has ID 16.
Further, a menu called by option 3 on menu 16 has ID 163 and
so on.
Number of Menu Options is the number of items on the menu.
Menu Width is the width in characters of the menu.
The Upper Left Corner is the row and column coordinates for
the placement of the upper left corner of the menu.
Initialization String is the set of characters which activate
the options on the menu. Normally this is the first letter
from each option, however, MM provides the flexibility to use
any letter in an option as the initialization character.
Level Above Background determines the offset of the shadow
under the menu box.
The 10 Menu Option fields contain the options which will
appear on the menu.
The 10 Brief Help text fields contain the one line help
messages for each option.
The 10 Command fields contain the commands that will be
executed when the corresponding option is selected.
The assorted internal flags are for MM internal use.
HELP.DBF contains the detailed context sensitive help text which
is called by the F1 key.
QUICKEYS.DBF contains the inkey() value of each Quick Key and the
command to be executed when that inkey() value is received at any
menu.
MENUPARS.DBF contains all the general menu variables including
colors, border type, menu titles, speed option, help option, and
bottom line label.
Getting Started
Look at the DEMO to get a feel for the menu system. To use the
DEMO, either make the DEMO directory on the floppy disk the active
FoxBase directory, or copy the entire contents of the DEMO
directory to a directory on your hard drive and make that
directory the active Foxbase directory. Load the menus by typing
"do menus" at the dot prompt (the CONFIG.FX file in the demo
directory contains the line "command=do menus" so the menus system
will automatically be booted if Foxbase is loaded from the demo
directory). Execute the Alt-C, Alt-A, Alt-H, Alt-K, and Alt-R
parameters to see what a completed system looks like from the
inside.
When you are ready to actually create and modify menus, copy the
contents of either the LOOSE or PROCEDURE directory to a directory
on your hard drive. Which directory you use will depend on the
procedure file limitations outlined above in "What's on the
Diskette." Make the directory the active Foxbase directory. Type
"do menus" at the dot prompt. The menu system will load; the only
option that appears on the menu system is the QUIT option on
Menu 1.
With the features of MM outlined in the next section, "stretch"
the menu system to provide all the options you need. Add new
options, move options, attach submenus, move menus, add Quick Key
features, and so on. MM will save a great deal of programming
time, provide a slick, consistent user interface, and provide an
outline for your entire system.
How to Create and Modify the Menus
Menu creation and modification is controlled by five procedures:
- CHANGVAR.PRG (Alt-C) Change Menu Attributes
- MENUCHNG.PRG (Alt-A) Modify Menus
- QUICKEYS.PRG (Alt-K) Add/Change/Delete Quick Keys
- HELPADD.PRG (Alt-H) Add/Change/Delete Help
- MENURPT.PRG (Alt-R) Print Menu Structure
The system comes set up so that these procedures are easily
accessible from any menu via Quick Keys. Quick Key access allows
for the modification of the menu system from within the system
itself.
NOTE: A menu change will not take effect until the
system is reinitialized. After making a menu
change, return to the dot prompt and type "do
menus."
Alt-C / CHANGVAR.PRG
This procedure enables modification of all the global menu
attributes - colors, border type, menu titles, help placement,
etc. Most of these attributes are self-explanatory. Below are
some notes on various menu parameters.
Menu titles can be displayed anywhere on the screen by adjusting
the titles parameters. Borders, shadows, and colors can all be
changed. There is one special case for titles. This special case
occurs when the Title line is the same as the Small Help line,
column is 60, length is 1, width is 20, and there is no shadow.
In this case, the Menu Title is part of the help line and a double
line character is added by MM to separate the two.
The menu borders option can take a value from 0 to 3. The
following list describes the border options:
0 - No Border
1 - Single Border
2 - Double Border
3 - Corners
The Corners option, #3, is a special border case. The Corners
option displays a right angle bracket in each corner of the Main
Menu only. For contrast, all submenus are displayed with single
line borders.
The MISC attributes require some explanation:
Set Speed to 1 to speed up the drawing of the menus. When Speed
is 1, the key letters for the Menu Options are not highlighted by
a different color.
The menu system requires that Escape be set off at certain times.
Indicate via the Set Escape option how Escape should be set by the
system when MM does not require that it be set off. Note that a
"set escape on/off" command in the ENVIRON.PRG procedure will be
overridden by this parameter.
It is not desirable to let the users of a system have access to
the procedures which modify the menu system, i.e. Alt-C, Alt-A,
Alt-K, and Alt-H. Set the Password parameter to "Y" to activate
password protection of these routines.
Set the Reset Function Keys attribute to "N" to instruct MM not to
redefine function keys 2,3,4,10. If the function keys are not
redefined by MM, use the following keystrokes instead of the
function keys when MM indicates that a certain function key be
pressed:
F2
F3
F4
F10
The Show Time? field sets the clock at the lower right on or off.
If the system is run on a non-dedicated file server it is recom-
mended that the clock be set off. Otherwise, the continuous
looping of the program on the network server can slow down the
entire network.
Alt-K / QUICKEYS.PRG
Adding and modifying Quick Keys is surprisingly simple. When
Alt-K is issued, MM displays a list of all Quick Keys currently
recognized by the system. Add a Quick Key by striking the
Quick Key by positioning the highlight bar on the appropriate
record and striking
When adding a Quick Key it is necessary to enter three items: (1)
the keystroke which will activate the Quick Key procedure; (2) the
description of that keystroke, i.e. Alt-A, Ctrl-X, etc.; and (3)
the command to be executed when the Quick Key is issued.
Note that the ascii character for the inkey() value is displayed
just to the right of the inkey() value. Be very careful when
choosing inkey() values for Quick Keys! The inkey() values should
not coincide with keystrokes that have other functions within the
menus. For example, consider the keystroke Ctrl-M. Ctrl-M has an
inkey() value of 13, and is equivalent to
assigned to Ctrl-M will never work. When the system receives a
Ctrl-M, it perceives it as a
highlighted Menu Option will be executed, not the Quick Key. Also
avoid Quick Keys that are equivalent to letters or numbers that
execute Menu Options. Remember that Quick Keys will be recognized
from any and all menus.
Alt-H / HELPADD.PRG
Adding detailed help for menu selections is very easy with MM.
Use the PgUp and PgDn keys to find the menu with the option for
which you would like to enter detailed help. Once you have found
the correct menu, choose the option you wish to document by
entering its number in the prompt box. A help page will open for
that option. Each help page has 10 lines. Add additional help
pages with the PgDn key. There is no limit to the number of help
pages you can enter.
Alt-R / MENURPT.PRG
The Menu Documentation Report prints one page for every menu in
the system, outlining each menu option, its brief help message,
and the command that is executed when the option is selected.
This report provides a concise outline of the top level of your
system.
Alt-A / MENUCHNG.PRG
All modifications to the menu options are accomplished with this
procedure. Adding options, deleting options, changing options,
repositioning menus on the screen, and re-attaching menus to other
menu options are all controlled by this program.
Striking Alt-A brings a list of the currently defined menus to the
screen. The listing displays the Menu ID and the Menu Name (see
Using MM - The Structure for a description of the Menu ID). Add a
new Menu by striking the
the appropriate record and striking
Delete a Menu
Position the highlight bar on the record to be deleted and strike
will ask for verification of the deletion. If the deletion is
verified, the menu is deleted and the MENUS.DBF file is packed.
The Menu Option which called the deleted menu will be replaced by
"XXXXX" and the Brief Help message will be changed to read "Menu
called here has been deleted."
Add a Menu
Strike
necessary to indicate the information which identifies the new
menu. In order to add a menu, the system needs to know three
things; (1) the Menu Name of the new menu, (2) the Menu ID of the
menu which calls the new menu, and (3) the option on the calling
menu which calls the new menu. Enter the Menu Name - up to 20
characters. Enter the Menu ID of the calling menu next; striking
F4 will list the menus and their ID's for reference. Once the
calling menu has been selected, it will be drawn on the upper
right portion of the screen. Select the number of the option on
this menu that is to call the new menu. The selected option will
be highlighted. The system will then ask for verification of the
new menu addition. Once the menu addition has been verified, the
system will proceed to Menu Edit mode (see below).
Edit a Menu
Position the highlight bar on the Menu record which is to be
modified and strike
This screen has three divisions. The upper left portion of the
screen (Zone 1) contains the menu parameters for Menu Name, Menu
ID, Upper Left Row, Upper Left Column, Width, Number of Items, and
Initialization String. The upper right portion of the screen
labeled "Menu Peek" displays the menu that is being edited. The
"Menu Peek" is dynamic and thus changes as the menu is altered.
Finally, the bottom of the screen (Zone 2) is where the Menu
Options are edited. Only one Menu Option is displayed at any
time.
Zone 1
The Name and ID fields are filled in by the Add Menu procedure.
The Name can be changed on this screen, however, the Menu ID
cannot. The Menu ID can only be changed by the Re-attach
procedure which is described below.
The Upper Left Row and Upper Left Column parameters determine the
placement of the menu on the screen. To help determine the best
placement for the menu, the coordinates of the Calling Menu, CM
are shown to the right.
The Width parameter determines the width of the menu. Be sure to
make the width at least as wide as the length of the longest
option on the menu.
The Number of Items parameter determines how many options are
displayed on the menu. Increasing the number of options adds new
menu options to the bottom of the menu. Note that the Insert and
Delete Options described in Zone 2 will change the Number of Items
parameter.
The Initialization String parameter is the set of key letters that
call the menu options. For example, if the menu had the following
options;
(A)dd
(E)dit
(D)elete
the Initialization String would be "AED" where "A" invokes the
(A)dd option, "E" invokes the (E)dit option, and "D" invokes the
(D)elete option. Note that the Insert and Delete Options
described in Zone 2 will change the Initialization String;
however, these procedures assume that the key letter of a menu
option is the first letter of the menu option and that might not
always be the case. In fact, in the example above, the first
letter of each menu option is "(". Review the Initialization
String before saving the menu to ensure that it consists of the
correct letters.
The Shadow Level parameter determines the offset of the shadow
underneath a menu box. Increasing the level makes the menu appear
to be further off the background by increasing the distance of the
shadow from the menu box. By default, the Shadow Level is set to
1.
While editing in Zone 1,
without saving changes,
F2 - Re-attach Menu. It is not possible to manually change the
Menu ID. To change the calling menu or calling menu option, the
Re-attach procedure must be used. Press F2 to execute the
Re-attach procedure. The Re-attach Menu screen is identical to
the Add Menu screen. Specify the calling menu and the calling
menu option. The system will automatically change the Menu ID and
the calling option. Note that the system will not allow a menu to
be re-attached to an option that contains a command. Delete the
existing command in the calling option before re-attaching a menu.
Zone 2
Zone 2 is where the menu options are edited. One menu option is
displayed at a time. Move from one option to another with the
changes,
return to Zone 1. The
described in detail below.
There are three parameters for each menu option; Menu Text, Brief
Help Text, and Execute Instruction.
Menu Text is the text which will appear on the menu for the
option.
Brief Help Text is the help message which will appear on the help
bar when the option is highlighted on the menu. This message can
be suppressed by the Show Help global menu parameter.
Execute Instruction is the Foxbase command that will be executed
when the menu option is selected. For example, if the option is
to execute the Foxbase program "edit.prg" the Execute Instruction
would be "do edit.prg"; to format a diskette in drive A, enter the
instruction "run format a:". Any valid Foxbase command can be
entered for the Execute Instruction.
F1 Swap is used to exchange the positions of two menu items. The
two items to be swapped are (1) the highlighted option when F1 is
pressed and (2) any other option on the current menu to be
indicated by the user after F1 is pressed. The Initialization
String parameter will be appropriately modified.
F3 Insert is used to insert a new menu option immediately
preceding the currently highlighted menu option. Pressing F2 will
automatically update the Number of Menu Items and Initialization
String parameters (see note on Initialization String above). To
add a menu option to the bottom of a menu, increase the Number of
Menu Items parameter in Zone 1.
F4 Delete is used to delete a menu option. Pressing F4 will
delete the currently highlighted menu option after verification.
The number of Menu Items and Initialization String parameters will
be appropriately modified.
Note that due to the Menu ID convention employed by MM, menu
insertions and deletions may require other Menu ID's be updated to
reflect the current status of the system. The renumbering will be
done automatically when the menu update screen is exited.
Programming with Menu Maker
Memory Variables: The MM system uses a quite a few memory
variables. In order to avoid conflict, it is recommended that
variables be saved to a memory file before executing an involved
procedure from the menu. These variables must be restored upon
exiting the program.
Example: Menu calls program INVOICE.PRG
* INVOICE.PRG
save memory to menumem
clear memory
* invoice program...
restore from menumem
return
Open Data Files: MM opens data files upon initialization and when
Help and Quick Key functions are used. Data files are opened
after "select 0" is issued. There is never more than one data
file open at any time. Data files are closed immediately after
use. No MM data files will be open when a Menu Option is
selected. If changes might be written to the file, the file is
opened exclusively. There is no error checking here. Your error
trapping routine must be able to trap file conflict for MM to work
correctly on a network.
Restricting Access to Users: When the system is finished,
password protect the menus system by turning password protection
on. See notes on CHANGVARS.PRG.
Function Keys: The MM modification programs reset Function keys
2,3,4,10 for use in the menu modification procedures. If you need
to set these keys, set the Function Keys parameter to "No Reset"
when the system is finished. See notes on CHANGVARS.PRG.
Re-indexing Files: MM has three index files, HELP.IDX, MENUS.IDX,
and QUICKEYS.IDX. The program MENU_NDX.PRG, accessible via Quick
Key Alt-I, re-indexes these files.
Custom Backgrounds: When modifying the program BACK.PRG to change
the appearance of the background, be sure to make changes after
the section of the program that checks to see if any changes have
been made to the menu parameters file. Note that customization of
the BACK.PRG program will only take effect after the menu
parameters screen has been called (Alt-C) and saved via F10.
ENVIRON.PRG: Variables that are initialized in ENVIRON.PRG will
retain their initialized values only after the menus parameters
screen has been called (Alt-C) and saved via F10.
Tips
While the
to explicitly see a "Return to Previous Menu" option on a submenu.
This is easily accomplished by setting up an option with an
Execute Instruction that is simply "RETURN".
A Quick Key that executes the "cancel" or "suspend" command drops
the user to the dot prompt from any menu. This is particularly
helpful during development.
After pressing
message is displayed. Striking
will drop the user to the dot prompt.
DOS access can be provided via a Quick Key that executes the
command "run COMMAND.COM".
Take notes on development with a Quick Key that executes the
command "modify command NOTES.TXT"
Alt-T has been set up to run the program TOOLS.PRG, a handy
reference for inkey() values, readkey() values, and ascii codes.
Careful use of Shadow Levels and menu placement can give a real
3-D feel to the user interface.
Don't forget that bold black, "n+", is a very elegant, dark grey.
Backgrounds of n+/n look excellent.
Limitations
- 10 options per menu
- 7 levels of nested menus
Note: System functions (Alt-C, Alt-A, etc.) are programmed for
color monitors. Monochrome monitors may not provide
sufficient contrast.
Note: MM uses a lot of variables. You may have to allocate more
memory for string variables by initializing MVARSIZE in your
CONFIG.FX. See the Fine Tuning Foxbase section of your
Foxbase manual.
Upgrading to New Version 1.10
The changes in version 1.10 address some important technical
issues. These are mainly internal changes and will not affect the
way your system functions. It will only be necessary to replace
your program files. Databases, indices, and memory files need not
be altered with ONE EXCEPTION. MENUPARS.DBF has one new field:
SHOWTIME Logical
This field must be the last field in the file. You can either add
this field to your existing file, or copy the file from the new
disk.
---> Copy all of the new program files into your system.
Before running the system, you must reinitialize the system. Every
variable name has been changed! The variables stored in the .MEM
files must be updated. You can tell MENU MAKER to reinitialize
these variables by making the following two changes to the data
files:
1> Change the CHANGED field in MENUPARS.DBF to .T.
2> Change the CHANGED field in the first record in MENUS.DBF to
.T.
The next time you start the system the variables will be
reinitialized.
What are the Changes?
The upgrade addresses two significant issues:
There is a new option to turn off the clock. Turning the clock off
(set Show Time? to N on the Menu Parameters screen) causes MM not
to read keystrokes by inkey() in a continuous loop. The clock
should be set off if you are running the system on a nondedicated
file server. Continuous looping on a nondedicated file server can
slow the entire system down to a crawl.
All variable names have been changed so that they have common
prefixes and MM can save them to disk discriminately with a mask.
Before this change MM system variables were getting confused with
user defined variables. The names of system parameter variables
all start with PM*. Menu variables all start with MV*. You may
want to avoid defining your own variables with these prefixes.
Conflict will only occur if four conditions are satisfied:
1> Variables that start with PM* or MV*.
2> These variables are saved to .MEM files
3> These .MEM files are restored to memory in ENVIRON.PRG
4> These variables are changed and saved to their .MEM files
by functions within the system (i.e. not at the dot).
The above are the main changes. Some other small bugs have also
been addressed in the new version.
Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!
This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.
But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/