/*------------------------ 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. 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. 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. 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. 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. 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.