/*------------------------ VIS_MENU.TXT ------------------------*/
/*                                                              */
/*  This file contains the VISIONS Menu Library Manual          */
/*                                                              */
/*         Copyright 1990 Dan Vogel & David Bernazzani          */
/*                                                              */
/*   Date        Initials        Comments                       */
/*                                                              */
/*  03/13/90       DCV       Initial Release 0.00.              */
/*--------------------------------------------------------------*/

                        Overview


   The VISIONS menu library is a simple library, written in C, to 
provide color or monochrome text menus on PC/XT/AT class machines.  The 
library was originally written in Microsoft C 5.1, but an attempt to 
separate compiler specific code into a separate source was made, and 
this file, COMPSPEC.C, is provided with the library.  The VISIONS Menu 
library uses the VISIONS Window and List librarys.
   The menu library, although simple, provides basic menu service that 
is useful for a wide range of applications.  These applications can 
include database interfaces, applications selections programs, and games.  
The features provided by the menu library to support these uses are:


     MGA, CGA, EGA, VGA, MCGA compatible color text menus.
     Automatic color conversion for monochrome adaptors.
     User selectable screen colors and highlights.
     User selectable menu sizes or automated menu sizing.
     Optional menu titles.
     Optional menu borders and border type.
     Hot key menu execution of menu selections.
     File defined menu execution.






                        Theory of Operation


   The following is a brief overview of the operation of the menu 
library routines.  This is intended to help the user to understand 
the library's operation better, so that it may be used more effectively.
   The VISIONS menu system is intended to execute a list which defines 
a menu.  This list consists of a header structure which defines menu wide 
parameters, such as titles, colors, and position, as well as a pointer 
to a separate list of actual menu items.  The menu item corresponds to a 
single selectable line of the menu.  The information contained in the 
menu item structure includes the text displayed on the screen for this 
selection, an optional 'hot key' value for this item, return values if 
this item is selected, and an optional routine to execute if this item is 
selected.  With this brief description of the internal data structures, we 
can proceed to how the package works.
   In order to use the VISIONS menu library to execute a menu, four steps 
must be taken:
        1) Define the menu structure. - DefineMenu.
        2) Define the menu items.     - AddToMenu.
        3) Execute the menu.          - DisplayMenu, 
                                        AutoDisplayMenu, DoFileMenu.
        4) Release the menu storage.  - DeleteMenu.
Note that while these steps must occur in this order, some variations are 
possible.  For example, the same menu may be needed over and over within a 
program.  In this case the menu may be created at the beginning of the 
program and released at the end, but the execution, step three, may be 
repeated several times within the program.  Another possibility is that a 
menu that has already been defined and executed is needed again, but with 
more items from which to select.  This is possible by defining more menu 
items on the same menu structure and then executing it with an automatic 
sizing option which we will discuss later.  Note however that menu items 
will appear on the screen in the order in which they are defined!
   Two special features that affect the above steps for executing a menu 
are file menu execution and automatic menu sizing.  The file execution of 
a menu is a feature that allows steps one through three to be combined in a 
single call to a routine, DoFileMenu.  This routine defines the complete 
menu structure from a file description of the desired menu, and then 
executes the menu.  The name of the file containing the menu description is 
the only input.  The format of the file is given below with the DoFileMenu 
specification.  One limitation of this routine is that is can not define 
action routines to be executed upon menu item selection.  All that a menu 
defined this way can do is to return a value indicating the selection that 
was made.
   The automatic menu sizing feature is a special case which allows the 
size of a menu to be modified after the menu and its items are defined.  
This is done automatically before displaying the menu by determing the 
length and number of menu items, titles, and borders, and then creating 
a window large enough to contain this display, without shifting the 
upper left border of the initially defined window for the menu.  In other 
words, the menu window grows or shrinks to accommodate the menu defined 
without changing its top left corner position.



                        Routine Definitions

   In order to use the below routines you must include the file 
"USERMENU.H" in your source code with the following statement.

                #include "USERMENU.H"

This will automatically include the window and list definitions files 
at the same time.  Examples of the use of these routines are available 
in the VISIONS demonstration program, in the file DEMOMENU.C.


/*------------------------------------------------------------------------*/
                        AddToMenu

Purpose:  This routine is used to add a menu item to a defined menu
 base.  This item will then appear and can be acted upon when the 
 menu is displayed.  Menu items are displayed in the order that they 
 are added to the menu.

Calling Sequence: 
   status = AddToMenu(menu_ptr, menu_text, hot_key, ret_val, *menu_action);

Inputs:
   MENU_HEAD *menu_ptr; - This is a pointer to the menu base.

   char *menu_text;    - This is the text string to be displayed in the menu
                        describing this selection.

   char hot_key;       - This is the key that will cause the menu cursor 
                        to jump directly to this menu item.  Note that if 
                        this hot key is not unique, the cursor will jump 
                        to the first matching hot key below its current 
                        position (wraps to top off of bottom!).

   int menu_action();  - This is the routine to be executed when this 
                        menu item is selected.  If this is NULL, then no 
                        routine is executed and the return value, not the 
                        value of a routine, is returned.  Note that a return 
                        value of zero will not cause the menu to exit.

   int ret_val;        - This is the value to be returned by this 
                        item if there is no action routine, otherwise the 
                        value of the action routine is returned.  Note that 
                        a return value of zero will not cause the menu to 
                        exit.

Outputs:
   int status;         - This is the result of the function.  
      Possible values are:
            0                  Success.
        MENU_OUT_OF_MEM        Memory allocation, malloc, returned error.
        <Others>               As returned by called action functions.

Functions called:
   AppendToList.

/*------------------------------------------------------------------------*/


/*------------------------------------------------------------------------*/
                        AutoDisplayMenu

Purpose:  This routine sizes a menu based upon menu contents, and then 
 displays a menu, interacts with user through the keyboard 
 to select a menu item, or ESC, amd if an item is selected, executes the 
 action routine associated with that item.

Calling Sequence: 
   status = AutoDisplayMenu(new_menu);

Inputs:
   MENU_HEAD *new_menu;  - This is the pointer to the menu to be displayed.

Outputs:
   int status;          - This is the result of the selection.  
      Possible values are:
        USER_ABORT        User struck ESC.
        <Other>           As returned by executed action routine.

Functions called:
   DisplayMenu.

/*------------------------------------------------------------------------*/


/*------------------------------------------------------------------------*/
                        DefineMenu

Purpose:  This routines creates a new menu structure, complete with 
 color, border, and position definitions.

Calling Sequence: 
   status = DefineMenu(new_menu, topy, leftx, height, width, border, 
        hotexec, bkcol, txtcol, highbkcol, highcol, title);

Inputs:
   BYTE topy, height, leftx, width;  - These are the coordinates of the 
        top left corner of the menu window to be displayed, as well as the 
        height and width of this window.  The coordinates range from 1,1 
        in the top left corner to 25,80 in the bottom right corner 
        on most displays.  The width and height values do not need to be 
        accurate if AutoDisplayMenu is to be used to execute the menu, but 
        these value must be legal.  This means that the height and width 
        must be positive values that do not place the bottom right corner 
        of the proposed menu window off the display screen.

   BYTE border;   - This is the type of border desired for the menu.  
        Possibilities are NOBORDER, SINGLEBORDER, and DOUBLEBORDER.

   char hotexec;  - This is the execute on hot key struck flag.  Possible 
        values are HOT_EXEC_ON or HOT_EXEC_OFF.  If the hot execution 
        flag is on, then striking a hot key will move the menu cursor to 
        the matching item in the menu and execute that item's routine, or 
        return that item's return value, as is appropriate.  If the hot 
        execution flag is not on, then striking a hot key will only move 
        the menu cursor and not perform any routine execution nor return 
        the item's return value.

   long int bkcol, txtcol, highbkcol, highcol;   - These are the colors 
        used for the text and background display of menu items, both 
        when these items are normally displayed, and when they are to 
        be highlighted by the menu cursor.

   char *title;   - This is the displayed title of the menu.  It will be 
        automatically center justified.  A null string causes no title to be 
        displayed.

Outputs:
   MENU_HEAD **new_menu;   - This is returned as a pointer to the 
        menu structure created.

   int status;   - This is the result of the function.  Possible values are:
           0                Success.
        BAD_COORD_DEF       Bad coordinates passed for menu.
        <Others>            As returned by called functions.

Functions called:
   AllocateMenu,  DefineList.

/*------------------------------------------------------------------------*/



/*------------------------------------------------------------------------*/
                        DeleteMenu

Purpose:   This routine releases all memory attached to the menu structure.

Calling Sequence: 
   DeleteMenu(menu_ptr);

Inputs:
   MENU_HEAD *menu_ptr;  - Pointer to menu structure to be deleted.

Outputs:
   None.

Functions called:
   DeleteList.

/*------------------------------------------------------------------------*/


/*------------------------------------------------------------------------*/
                        DisplayMenu

Purpose:  This routine displays a menu, interacts with user through 
 the keyboard to select a menu item, or ESC.  If an item is selected, 
 it executes the routine associated with that item or returns the 
 item's return value if there is no associated routine.  A return value 
 of zero from any menu item or menu routine will not cause the menu to 
 exit, but instead allow more menu selections to be made.

Calling Sequence: 
   status = DisplayMenu(new_menu);

Inputs:
   MENU_HEAD *new_menu;  - This is the pointer to the menu structure to be 
        displayed and executed.

Outputs:
   int status;  - This is the result of the selection.  Possible values are:
        USER_ABORT        User struck ESC.
        <Other>        As returned by executed action routine.

Functions called:
   InitWindow,    PushWindow,      SetWindow,        PopWindow,
   ShowMenuLine,  MoveMenuCursor,  ExecuteMenuItem,  
   MenuHotkey.

/*------------------------------------------------------------------------*/



/*------------------------------------------------------------------------*/
                        DoFileMenu

Purpose:  This routines creates a new menu structure, complete with color, 
   border, and position definitions, displays it and executes it, based upon 
   a file of descriptions.  Note that action routines can not be defined 
   using this routine!

Calling Sequence: 
   status = DoFileMenu(filename);

Inputs:
   filename - char * - This is the name of the file containing the menu
        information.  Format is:
          topy,boty,border,hotexec,bkcol,txtcol,highcol,highbkcol,title
          hot key   return value   menu string 
          hot key   return value   menu string 
          hot key   return value   menu string
                         etc
      where:
          topy, boty - integer specifications of top left corner of menu.
          border - integer value indicating border type.  See values for 
             NOBORDER, SINGLEBORDER, DOUBLEBORDER in SHARWIND.H.
          hotexec - is the integer indicating hot key execution enabled or 
             disabled.  See SHARWIND.H for the values of HOT_EXEC_ON 
             and HOT_EXEC_OFF.
          bkcol, txtcol, highcol, highbkcol - These are the long integer 
             values of the colors to be used in this menu.  See SHARWIND.H 
             for the values corresponding to different colors.
          title - This is the string to be used as the title of the menu.

Outputs:
   status - int - This is the result of the function.  Possible values are:
        MENU_FILE_NOT_FOUND      File not found.
        MENU_OUT_OF_STRMEM       Unable to allocate storage for menu string.
        <Others>                 Errors as returned by called routines 
                                 (negative values) or menu item return values
                                 (positive values).

        Note that errors are generally non-recoverable, as memory and files
        are left in undefined states!

Functions called:
   AllocateMenu,  DefineList.

/*------------------------------------------------------------------------*/





                        Error Codes

   The following is the list of error codes that can be returned from the 
VISIONS menu library.  Errors from calls to the windows or list librarys 
will be passed back unchanged.  These error values can be found in the 
window and list manuals.

Error Name              Value       Description.

USER_ABORT                -1        User aborted out of a menu.

BAD_MENU_HEAD_PTR       -101        Menu header pointer parameter does not 
                                    point to a menu structure.
BAD_MENU_ITEM_PTR       -102        Menu item pointer parameter does not 
                                    point to a menu item.
BAD_COORD_DEF           -103        Illegal window coordinates used.
MENU_FILE_NOT_FOUND     -104        Unable to open menu description file.
MENU_OUT_OF_STRMEM      -105        Allocation error, no heap available.
MENU_OUT_OF_MEM         -106        Allocation error, no heap available.
UNABLE_TO_ALLOC_MENU    -107        Allocation error, no heap available.
NO_MENU_LINK            -108        Error in traversing menu list structure.
NO_MENU_LIST            -109        Menu list description empty.


                   