home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / window / visions / vis_menu.txt < prev    next >
Encoding:
Text File  |  1990-05-20  |  16.0 KB  |  366 lines
  1. /*------------------------ VIS_MENU.TXT ------------------------*/
  2. /*                                                              */
  3. /*  This file contains the VISIONS Menu Library Manual          */
  4. /*                                                              */
  5. /*         Copyright 1990 Dan Vogel & David Bernazzani          */
  6. /*                                                              */
  7. /*   Date        Initials        Comments                       */
  8. /*                                                              */
  9. /*  03/13/90       DCV       Initial Release 0.00.              */
  10. /*--------------------------------------------------------------*/
  11.  
  12.                         Overview
  13.  
  14.  
  15.    The VISIONS menu library is a simple library, written in C, to 
  16. provide color or monochrome text menus on PC/XT/AT class machines.  The 
  17. library was originally written in Microsoft C 5.1, but an attempt to 
  18. separate compiler specific code into a separate source was made, and 
  19. this file, COMPSPEC.C, is provided with the library.  The VISIONS Menu 
  20. library uses the VISIONS Window and List librarys.
  21.    The menu library, although simple, provides basic menu service that 
  22. is useful for a wide range of applications.  These applications can 
  23. include database interfaces, applications selections programs, and games.  
  24. The features provided by the menu library to support these uses are:
  25.  
  26.  
  27.      MGA, CGA, EGA, VGA, MCGA compatible color text menus.
  28.      Automatic color conversion for monochrome adaptors.
  29.      User selectable screen colors and highlights.
  30.      User selectable menu sizes or automated menu sizing.
  31.      Optional menu titles.
  32.      Optional menu borders and border type.
  33.      Hot key menu execution of menu selections.
  34.      File defined menu execution.
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.                         Theory of Operation
  42.  
  43.  
  44.    The following is a brief overview of the operation of the menu 
  45. library routines.  This is intended to help the user to understand 
  46. the library's operation better, so that it may be used more effectively.
  47.    The VISIONS menu system is intended to execute a list which defines 
  48. a menu.  This list consists of a header structure which defines menu wide 
  49. parameters, such as titles, colors, and position, as well as a pointer 
  50. to a separate list of actual menu items.  The menu item corresponds to a 
  51. single selectable line of the menu.  The information contained in the 
  52. menu item structure includes the text displayed on the screen for this 
  53. selection, an optional 'hot key' value for this item, return values if 
  54. this item is selected, and an optional routine to execute if this item is 
  55. selected.  With this brief description of the internal data structures, we 
  56. can proceed to how the package works.
  57.    In order to use the VISIONS menu library to execute a menu, four steps 
  58. must be taken:
  59.         1) Define the menu structure. - DefineMenu.
  60.         2) Define the menu items.     - AddToMenu.
  61.         3) Execute the menu.          - DisplayMenu, 
  62.                                         AutoDisplayMenu, DoFileMenu.
  63.         4) Release the menu storage.  - DeleteMenu.
  64. Note that while these steps must occur in this order, some variations are 
  65. possible.  For example, the same menu may be needed over and over within a 
  66. program.  In this case the menu may be created at the beginning of the 
  67. program and released at the end, but the execution, step three, may be 
  68. repeated several times within the program.  Another possibility is that a 
  69. menu that has already been defined and executed is needed again, but with 
  70. more items from which to select.  This is possible by defining more menu 
  71. items on the same menu structure and then executing it with an automatic 
  72. sizing option which we will discuss later.  Note however that menu items 
  73. will appear on the screen in the order in which they are defined!
  74.    Two special features that affect the above steps for executing a menu 
  75. are file menu execution and automatic menu sizing.  The file execution of 
  76. a menu is a feature that allows steps one through three to be combined in a 
  77. single call to a routine, DoFileMenu.  This routine defines the complete 
  78. menu structure from a file description of the desired menu, and then 
  79. executes the menu.  The name of the file containing the menu description is 
  80. the only input.  The format of the file is given below with the DoFileMenu 
  81. specification.  One limitation of this routine is that is can not define 
  82. action routines to be executed upon menu item selection.  All that a menu 
  83. defined this way can do is to return a value indicating the selection that 
  84. was made.
  85.    The automatic menu sizing feature is a special case which allows the 
  86. size of a menu to be modified after the menu and its items are defined.  
  87. This is done automatically before displaying the menu by determing the 
  88. length and number of menu items, titles, and borders, and then creating 
  89. a window large enough to contain this display, without shifting the 
  90. upper left border of the initially defined window for the menu.  In other 
  91. words, the menu window grows or shrinks to accommodate the menu defined 
  92. without changing its top left corner position.
  93.  
  94.  
  95.  
  96.                         Routine Definitions
  97.  
  98.    In order to use the below routines you must include the file 
  99. "USERMENU.H" in your source code with the following statement.
  100.  
  101.                 #include "USERMENU.H"
  102.  
  103. This will automatically include the window and list definitions files 
  104. at the same time.  Examples of the use of these routines are available 
  105. in the VISIONS demonstration program, in the file DEMOMENU.C.
  106.  
  107.  
  108. /*------------------------------------------------------------------------*/
  109.                         AddToMenu
  110.  
  111. Purpose:  This routine is used to add a menu item to a defined menu
  112.  base.  This item will then appear and can be acted upon when the 
  113.  menu is displayed.  Menu items are displayed in the order that they 
  114.  are added to the menu.
  115.  
  116. Calling Sequence: 
  117.    status = AddToMenu(menu_ptr, menu_text, hot_key, ret_val, *menu_action);
  118.  
  119. Inputs:
  120.    MENU_HEAD *menu_ptr; - This is a pointer to the menu base.
  121.  
  122.    char *menu_text;    - This is the text string to be displayed in the menu
  123.                         describing this selection.
  124.  
  125.    char hot_key;       - This is the key that will cause the menu cursor 
  126.                         to jump directly to this menu item.  Note that if 
  127.                         this hot key is not unique, the cursor will jump 
  128.                         to the first matching hot key below its current 
  129.                         position (wraps to top off of bottom!).
  130.  
  131.    int menu_action();  - This is the routine to be executed when this 
  132.                         menu item is selected.  If this is NULL, then no 
  133.                         routine is executed and the return value, not the 
  134.                         value of a routine, is returned.  Note that a return 
  135.                         value of zero will not cause the menu to exit.
  136.  
  137.    int ret_val;        - This is the value to be returned by this 
  138.                         item if there is no action routine, otherwise the 
  139.                         value of the action routine is returned.  Note that 
  140.                         a return value of zero will not cause the menu to 
  141.                         exit.
  142.  
  143. Outputs:
  144.    int status;         - This is the result of the function.  
  145.       Possible values are:
  146.             0                  Success.
  147.         MENU_OUT_OF_MEM        Memory allocation, malloc, returned error.
  148.         <Others>               As returned by called action functions.
  149.  
  150. Functions called:
  151.    AppendToList.
  152.  
  153. /*------------------------------------------------------------------------*/
  154.  
  155.  
  156. /*------------------------------------------------------------------------*/
  157.                         AutoDisplayMenu
  158.  
  159. Purpose:  This routine sizes a menu based upon menu contents, and then 
  160.  displays a menu, interacts with user through the keyboard 
  161.  to select a menu item, or ESC, amd if an item is selected, executes the 
  162.  action routine associated with that item.
  163.  
  164. Calling Sequence: 
  165.    status = AutoDisplayMenu(new_menu);
  166.  
  167. Inputs:
  168.    MENU_HEAD *new_menu;  - This is the pointer to the menu to be displayed.
  169.  
  170. Outputs:
  171.    int status;          - This is the result of the selection.  
  172.       Possible values are:
  173.         USER_ABORT        User struck ESC.
  174.         <Other>           As returned by executed action routine.
  175.  
  176. Functions called:
  177.    DisplayMenu.
  178.  
  179. /*------------------------------------------------------------------------*/
  180.  
  181.  
  182. /*------------------------------------------------------------------------*/
  183.                         DefineMenu
  184.  
  185. Purpose:  This routines creates a new menu structure, complete with 
  186.  color, border, and position definitions.
  187.  
  188. Calling Sequence: 
  189.    status = DefineMenu(new_menu, topy, leftx, height, width, border, 
  190.         hotexec, bkcol, txtcol, highbkcol, highcol, title);
  191.  
  192. Inputs:
  193.    BYTE topy, height, leftx, width;  - These are the coordinates of the 
  194.         top left corner of the menu window to be displayed, as well as the 
  195.         height and width of this window.  The coordinates range from 1,1 
  196.         in the top left corner to 25,80 in the bottom right corner 
  197.         on most displays.  The width and height values do not need to be 
  198.         accurate if AutoDisplayMenu is to be used to execute the menu, but 
  199.         these value must be legal.  This means that the height and width 
  200.         must be positive values that do not place the bottom right corner 
  201.         of the proposed menu window off the display screen.
  202.  
  203.    BYTE border;   - This is the type of border desired for the menu.  
  204.         Possibilities are NOBORDER, SINGLEBORDER, and DOUBLEBORDER.
  205.  
  206.    char hotexec;  - This is the execute on hot key struck flag.  Possible 
  207.         values are HOT_EXEC_ON or HOT_EXEC_OFF.  If the hot execution 
  208.         flag is on, then striking a hot key will move the menu cursor to 
  209.         the matching item in the menu and execute that item's routine, or 
  210.         return that item's return value, as is appropriate.  If the hot 
  211.         execution flag is not on, then striking a hot key will only move 
  212.         the menu cursor and not perform any routine execution nor return 
  213.         the item's return value.
  214.  
  215.    long int bkcol, txtcol, highbkcol, highcol;   - These are the colors 
  216.         used for the text and background display of menu items, both 
  217.         when these items are normally displayed, and when they are to 
  218.         be highlighted by the menu cursor.
  219.  
  220.    char *title;   - This is the displayed title of the menu.  It will be 
  221.         automatically center justified.  A null string causes no title to be 
  222.         displayed.
  223.  
  224. Outputs:
  225.    MENU_HEAD **new_menu;   - This is returned as a pointer to the 
  226.         menu structure created.
  227.  
  228.    int status;   - This is the result of the function.  Possible values are:
  229.            0                Success.
  230.         BAD_COORD_DEF       Bad coordinates passed for menu.
  231.         <Others>            As returned by called functions.
  232.  
  233. Functions called:
  234.    AllocateMenu,  DefineList.
  235.  
  236. /*------------------------------------------------------------------------*/
  237.  
  238.  
  239.  
  240. /*------------------------------------------------------------------------*/
  241.                         DeleteMenu
  242.  
  243. Purpose:   This routine releases all memory attached to the menu structure.
  244.  
  245. Calling Sequence: 
  246.    DeleteMenu(menu_ptr);
  247.  
  248. Inputs:
  249.    MENU_HEAD *menu_ptr;  - Pointer to menu structure to be deleted.
  250.  
  251. Outputs:
  252.    None.
  253.  
  254. Functions called:
  255.    DeleteList.
  256.  
  257. /*------------------------------------------------------------------------*/
  258.  
  259.  
  260. /*------------------------------------------------------------------------*/
  261.                         DisplayMenu
  262.  
  263. Purpose:  This routine displays a menu, interacts with user through 
  264.  the keyboard to select a menu item, or ESC.  If an item is selected, 
  265.  it executes the routine associated with that item or returns the 
  266.  item's return value if there is no associated routine.  A return value 
  267.  of zero from any menu item or menu routine will not cause the menu to 
  268.  exit, but instead allow more menu selections to be made.
  269.  
  270. Calling Sequence: 
  271.    status = DisplayMenu(new_menu);
  272.  
  273. Inputs:
  274.    MENU_HEAD *new_menu;  - This is the pointer to the menu structure to be 
  275.         displayed and executed.
  276.  
  277. Outputs:
  278.    int status;  - This is the result of the selection.  Possible values are:
  279.         USER_ABORT        User struck ESC.
  280.         <Other>        As returned by executed action routine.
  281.  
  282. Functions called:
  283.    InitWindow,    PushWindow,      SetWindow,        PopWindow,
  284.    ShowMenuLine,  MoveMenuCursor,  ExecuteMenuItem,  
  285.    MenuHotkey.
  286.  
  287. /*------------------------------------------------------------------------*/
  288.  
  289.  
  290.  
  291. /*------------------------------------------------------------------------*/
  292.                         DoFileMenu
  293.  
  294. Purpose:  This routines creates a new menu structure, complete with color, 
  295.    border, and position definitions, displays it and executes it, based upon 
  296.    a file of descriptions.  Note that action routines can not be defined 
  297.    using this routine!
  298.  
  299. Calling Sequence: 
  300.    status = DoFileMenu(filename);
  301.  
  302. Inputs:
  303.    filename - char * - This is the name of the file containing the menu
  304.         information.  Format is:
  305.           topy,boty,border,hotexec,bkcol,txtcol,highcol,highbkcol,title
  306.           hot key   return value   menu string 
  307.           hot key   return value   menu string 
  308.           hot key   return value   menu string
  309.                          etc
  310.       where:
  311.           topy, boty - integer specifications of top left corner of menu.
  312.           border - integer value indicating border type.  See values for 
  313.              NOBORDER, SINGLEBORDER, DOUBLEBORDER in SHARWIND.H.
  314.           hotexec - is the integer indicating hot key execution enabled or 
  315.              disabled.  See SHARWIND.H for the values of HOT_EXEC_ON 
  316.              and HOT_EXEC_OFF.
  317.           bkcol, txtcol, highcol, highbkcol - These are the long integer 
  318.              values of the colors to be used in this menu.  See SHARWIND.H 
  319.              for the values corresponding to different colors.
  320.           title - This is the string to be used as the title of the menu.
  321.  
  322. Outputs:
  323.    status - int - This is the result of the function.  Possible values are:
  324.         MENU_FILE_NOT_FOUND      File not found.
  325.         MENU_OUT_OF_STRMEM       Unable to allocate storage for menu string.
  326.         <Others>                 Errors as returned by called routines 
  327.                                  (negative values) or menu item return values
  328.                                  (positive values).
  329.  
  330.         Note that errors are generally non-recoverable, as memory and files
  331.         are left in undefined states!
  332.  
  333. Functions called:
  334.    AllocateMenu,  DefineList.
  335.  
  336. /*------------------------------------------------------------------------*/
  337.  
  338.  
  339.  
  340.  
  341.  
  342.                         Error Codes
  343.  
  344.    The following is the list of error codes that can be returned from the 
  345. VISIONS menu library.  Errors from calls to the windows or list librarys 
  346. will be passed back unchanged.  These error values can be found in the 
  347. window and list manuals.
  348.  
  349. Error Name              Value       Description.
  350.  
  351. USER_ABORT                -1        User aborted out of a menu.
  352.  
  353. BAD_MENU_HEAD_PTR       -101        Menu header pointer parameter does not 
  354.                                     point to a menu structure.
  355. BAD_MENU_ITEM_PTR       -102        Menu item pointer parameter does not 
  356.                                     point to a menu item.
  357. BAD_COORD_DEF           -103        Illegal window coordinates used.
  358. MENU_FILE_NOT_FOUND     -104        Unable to open menu description file.
  359. MENU_OUT_OF_STRMEM      -105        Allocation error, no heap available.
  360. MENU_OUT_OF_MEM         -106        Allocation error, no heap available.
  361. UNABLE_TO_ALLOC_MENU    -107        Allocation error, no heap available.
  362. NO_MENU_LINK            -108        Error in traversing menu list structure.
  363. NO_MENU_LIST            -109        Menu list description empty.
  364.  
  365.  
  366.