home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_300 / 315_01 / menu.txt < prev    next >
Text File  |  1990-05-16  |  12KB  |  242 lines
  1.  
  2. DOCUMENTATION FOR MENU.C
  3.  
  4. Documentation dated 8/89.
  5. Program and documentation Copyright (c) 1989, E.R.I.  All rights reserved.
  6.  
  7. INTRODUCTION
  8.      MENU.C is a source file for supporting text-based menus.  This document
  9. presents an overview of the MENU functions and explains each externally-visible
  10. function individually.
  11.      MENU.C requires ANSI.SYS, which should be installed as a device on boot-up
  12. by including a line like: DEVICE=ANSI.SYS in your CONFIG.SYS file.  See the DOS
  13. manual for details.  In addition, if you are using the mouse for menu selection,
  14. MENU.C requires MOUSE.SYS, which is distributed with the mouse hardware.  The
  15. mouse must be Microsoft mouse-compatible.  To install MOUSE.SYS, you should have
  16. a line like: DEVICE=MOUSE.SYS in your CONFIG.SYS file.
  17.      MENU.C supports a minimal menuing system.  Typically, a menu will be
  18. created by calling two functions: print_headline(), which prints an underlined
  19. title at the top of the menu, and menu(), which displays the menu options.  The
  20. options are presented as strings.  One option is highlighted.  The user can
  21. change what option is highlighted, and select the highlighted option.  The menu
  22. routine returns an integer from 0 to (number of options - 1), which is used to
  23. determine which selection was made.  Typically, the value returned by menu()
  24. will be used in a switch statement to take the appropriate action.  Note well:
  25. the menu functions do not automatically clear the screen when invoked, as there
  26. are times when one wants to use a split-screen style of menu, with non-menu data
  27. or entry areas displayed on another part of the screen.  Thus, you must clear
  28. the screen before calling menu() if the menu is the only thing that you want to
  29. be visible on the screen.
  30.      A second kind of menu is available for selecting a file from a highlighted
  31. list of choices (get_file()).  This routine returns a structure containing the
  32. selected filespec and an error flag.  The basic similarity with menu() is that
  33. both functions work from a list of strings by highlighting a particular option
  34. and providing standard ways for navigating through the list of options.
  35. get_file() automatically clears the screen for you, and so is not compatible
  36. with split-screen operation.
  37.      MENU.C provides for selection by keyboard and/or Microsoft-compatible
  38. mouse.  There are functions for enabling and disabling the different input
  39. devices (mouse_flag_toggle()) and for adjusting the sensitivity of the mouse, if
  40. used (menu_mouse_config()).  By default, input is from the keyboard only.  This
  41. maintains compatibility with versions of MENU.C that antedate mouse support.
  42. When the mouse is used, pressing the RIGHT mouse button registers a selection.
  43. That is, the RIGHT button is the mouse equivalent of the carriage-return key.
  44.      The use of MENU.C function calls is demonstrated in the file, MENU_DEM.C.
  45. Note that MENU_DEM.C assumes that the mouse is being supported.  If you do not
  46. have a mouse installed, you should not run this sample program.
  47.  
  48. DATA STRUCTURES USED IN MENU.C
  49.      The only MENU.C-specific data structure is string_struc, defined as
  50. follows:
  51. typedef struct
  52. {
  53.      char string[80];
  54.      int error_flag;
  55. }string_struc;
  56. The structure is defined in menu.h.
  57.      string_struc is used by get_file() to return the file specification (file
  58. name plus path) for the selected file.  and an error code for whether the file
  59. specification is a valid filename or not.  string_struc.string is the filespec
  60. string, and string_struc.error_flag is the error code associated with it.
  61.  
  62. EXTERNALLY-VISIBLE FUNCTIONS IN MENU.C
  63.      The MENU.C external functions and #defines are declared in the header file
  64. menu.h.  You should #include that header in any program that utilizes the MENU.C
  65. routines.
  66.  
  67.  
  68.  
  69. FUNCTION: clear_input_devices()
  70. TYPE: void
  71. ARGUMENTS: none.
  72.  
  73.      clear_input_devices() flushes the keyboard buffer and, if the mouse is 
  74. active, makes sure that the buttons are not being pressed and clears the mouse
  75. counter registers.            
  76.  
  77.  
  78.  
  79. FUNCTION: get_file()
  80. TYPE: struct of type string_struc
  81. ARGUMENTS: none.
  82.  
  83.      get_file() selects a file from a highlighting menu.  The user is prompted
  84. for a filename template a al DOS (e.g., *.C), and a pathname for the directory.
  85. The routine then displays all matching files, plus an entry, "Quit".  The user
  86. moves the highlight with cursor keys or (if enabled by mouse_flag_toggle()) the
  87. mouse.  If there are more than MAX_FILES (defined in menu.h, as of 8/89 =100)
  88. matching files, get_file() returns the value -1 in the error_flag element of
  89. string_struc.  If the user selects "Quit", get_file() returns the value 1 in the
  90. error_flag element.  If the user selects a valid file, get_file() returns that
  91. file name and the path associated with it in the string element of string_struc
  92. and a value of 0 for the error_flag element.  A valid filespec in the string
  93. element can be used directly in an fopen() call ( e.g.,
  94. f=fopen(foo.string,"r");).
  95.  
  96.  
  97.  
  98. FUNCTION: get_mouse_flag()
  99. TYPE: int
  100. ARGUMENTS: none.
  101.  
  102.      get_mouse_flag() returns the current status of the mouse status flag in the
  103. menu routines.  If the value returned is -1, menu selection is possible only by
  104. mouse; if the value returned is 0, keyboard-only selection is active; if the
  105. value returned is 1, selection by mouse or keyboard is possible.  The reason for
  106. this function's existence is that I assume that MENU.C will be the main
  107. repositor of input device style for a program.  In programs that are
  108. configurable by the user, this call will tell the programmer what kinds of input
  109. devices he should support.  If the mouse is enabled for input in MENU, you
  110. should support mouse input in other parts of the program as well.
  111.  
  112.  
  113.  
  114. FUNCTION: menu()
  115. TYPE: int
  116. ARGUMENTS: seven ints and an array of string pointers.
  117.  
  118.      menu(top,left,tab,columns,lf,entries,label,options) is the main menu
  119. function of MENU.C.  It creates a menu of options as follows: top is an integer
  120. specifying the number of spaces down from the top of the screen for the menu to
  121. begin (0 to 24); left is an integer telling how many spaces in from the left
  122. margin of the screen for the menu to begin (0 to 79); tab is an integer
  123. specifying how many spaces between the beginning of one column and the next in
  124. the menu (i.e., total number of spaces per column); columns is the number of
  125. columns in the menu; lf is the number of spaces between rows in the menu (>=1);
  126. entries is the total number of options in the menu; label is a flag variable, as
  127. follows: if it is less than -1, the menu options will automatically be assigned
  128. letters from 'A' up, and the user may select a menu item by pressing the
  129. associated letter; if the value is -1, the menu options will be automatically
  130. assigned a letter, but the user cannot select the item by pressing the
  131. associated letter key; if the value is 0, the options are not automatically
  132. labeled at all; if the value is +1, the options are automatically numbered from
  133. 1 (0 is used as the number above 9 if necessary), but the user cannot select by
  134. number; if the value is above 1, the options are auto-numbered and the user may
  135. select by numeral.  In all cases of auto numbering or lettering, the programmer
  136. is responsible for ensuring that there are no more menu items than 26 for
  137. letters or 10 for numerals.  The options field is an array of string pointers
  138. that are used for the menu option strings.  The programmer is responsible for
  139. ensuring that the string (plus auto-labeling, if used) fits in the field that he
  140. has allocated for it.  The function returns the subscript of the string of the
  141. selected option (i.e., the first menu item =0, last item = entries-1, etc.).  If
  142. the keyboard is not disabled by mouse_flag_toggle() (q.v.), users may move the
  143. menu highlight by cursor key.  The item is selected by pressing the carriage
  144. return.  If selection by letter or number is enabled with the appropriate
  145. argument of label, users may select by pressing the associated key.  Note that
  146. this form of selection does NOT wait for a carriage return.  If the  mouse is
  147. enabled by mouse_flag_toggle(), the user may select by moving the mouse to
  148. highlight the desired option, then pressing the RIGHT mouse button.
  149.  
  150.  
  151.  
  152. FUNCTION: menu_mouse_config()
  153. TYPE: void
  154. ARGUMENTS: one int and two doubles
  155.  
  156.      menu_mouse_config(sensitivity, on_time, off_time) configures the mouse
  157. sensitivity for use with the menu selection.  sensitivity sets the number of
  158. mickeys that the mouse must move in the x or y direction during a mouse-polling
  159. interval in order for the movement to be accepted.  This argument cuts down on
  160. "jitter" from digitizing errors or small motions by users.  The mouse is read in
  161. gated intervals.  on_time is the time in seconds of the gate, and off_time is
  162. the time in seconds between gates.  That is, if on_time is 0.05 seconds and
  163. off_time is 0.15 seconds, the mouse would be read every 0.2 seconds, with an 25%
  164. duty cycle.  The use of off_time is to give a positive feel to menu item
  165. selection.  It provides a pause, rather like the delay in key "repeat" features
  166. when you hold down a keyboard key.  The default settings for the mouse are:
  167. sensitivity=3, on_time=0.05 sec, and off_time=0.15 sec.  It should be noted that
  168. the granularity of the timer is approximately 0.05 sec.  Thus, 0,05 sec is the
  169. same as 0.06 sec, for example.
  170.  
  171.  
  172.  
  173. FUNCTION: mgetch()
  174. TYPE: int
  175. ARGUMENTS: none.
  176.  
  177.     mgetch() is a substitute for getch() that supports the mouse if it
  178. is currently active (if mouse_flag_toggle() is set for mouse support).  It
  179. returns the key that was pressed if keyboard input, or the mouse button that
  180. was pressed if the mouse is active and one of its buttons was pressed.  The 
  181. mouse button values are: CARRIAGE RETURN for the RIGHT mouse button, and ascii
  182. 127 for either the LEFT mouse button or BOTH buttons.
  183.  
  184.  
  185.  
  186. FUNCTION: mgets()
  187. TYPE: char *
  188. ARGUMENTS: one character array.
  189.  
  190.     mgets() is a substitute for gets() that supports the mouse if it is
  191. currently active (if mouse_flag_toggle() is set for mouse support). It returns
  192. the string that was entered.  The RIGHT mouse button is treated as the same
  193. as CARRIAGE RETURN.  The reason for this is to allow default values to be 
  194. selected by either CARRIAGE RETURN or the RIGHT mouse button.
  195.  
  196.  
  197.  
  198. FUNCTION: mouse_flag_toggle()
  199. TYPE: void
  200. ARGUMENTS: one int
  201.  
  202.      mouse_flag_toggle(val) sets the menu input device option variable as
  203. follows: if val == 0, input is accepted from the keyboard only; if val > 0,
  204. input is accepted from either the keyboard or the mouse; if val < 0, input is
  205. accepted from the mouse only.  The default is keyboard-only input.
  206.  
  207.  
  208.  
  209. FUNCTION: pathprint()
  210. TYPE: void
  211. ARGUMENTS: one string
  212.  
  213.      pathprint(string) prints the user's position in the heirarchical menu on
  214. the bottom of the menu.  For example, if the user is in submenu FOO of menu BAR,
  215. the menu will show on line 24:
  216. You are here: BAR->FOO.
  217.      In order to use pathprint() properly, you must call it from every menu or
  218. from none.  You provide a string that designates the menu of the current level,
  219. and pass THAT NAME ONLY.  pathprint() automatically updates the path for you.
  220. Note that each menu must have a unique pathprint() name.
  221.  
  222.  
  223.  
  224. FUNCTION: print_headline()
  225. TYPE: void
  226. ARGUMENTS: one string and two ints.
  227. J
  228.      print_headline(string, x, y) prints string, starting at x, y on the screen.
  229. Its intended use is for printing titles on menus.  string will be underlined if
  230. you are using a monochrome screen, or in a different color (by default, blue) if
  231. you are using a color screen.  The reange of x is 1 to 80.  The range of y is 1
  232. to 25.
  233.  
  234.  
  235.  
  236. FUNCTION: reset_menu()
  237. TYPE: void
  238. ARGUMENTS: one int
  239.  
  240.      reset_menu(choice) sets the menu highlight to choice.  It is used to keep
  241. the current selection highlighted on a menu as you move up and down the
  242. heirarchical menu structure.