home *** CD-ROM | disk | FTP | other *** search
/ POINT Software Programming / PPROG1.ISO / basic / mnusys21 / menusys.doc < prev    next >
Encoding:
Text File  |  1993-10-06  |  11.7 KB  |  345 lines
  1. MENUSYS Menuing System
  2. Text-Mode GUI for PowerBASIC
  3. Version 2.1
  4. Sub/Function Reference
  5.  
  6. Total SUBs/FUNCTIONs: 24 (22 SUBs, 2 FUNCTIONs)
  7.  
  8. --------------------------------------------------------------------------------
  9. * function altkey%  
  10.  
  11.  
  12. This function returns the state of the ALT key.  It will return one
  13. if the ALT key is pressed, or zero if it isn't.
  14.  
  15. Example: IF altkey% <> 0 THEN PRINT "ALT Key Pressed!"
  16.  
  17. --------------------------------------------------------------------------------
  18. * sub bottomdehilight (top%, bottom%, menu$(), menutype%())  
  19.  
  20.  
  21. This is an internal routine used by MENUSYS to dehighlight
  22. box menu options.
  23.  
  24. --------------------------------------------------------------------------------
  25. * sub bottomhilight (top%, bottom%, menu$(), menutype%())  
  26.  
  27.  
  28. This is an internal routine used by MENUSYS to highlight
  29. box menu options.
  30.  
  31. --------------------------------------------------------------------------------
  32. * sub dopcopyfrom  
  33.  
  34.  
  35. This routine copies page 0 of screen memory to
  36. a memory buffer, turning off the mouse cursor
  37. first if necessary.  It can be used for a quick,
  38. temporary, mouse-aware save of the text screen.
  39.  
  40. Example: CALL dopcopyfrom
  41.  
  42. --------------------------------------------------------------------------------
  43. * sub dopcopyto  
  44.  
  45.  
  46. This routine copies the contents of a memory buffer
  47. to page 0 of screen memory, turning off the mouse cursor
  48. first if necessary.  It can be used to restore a text
  49. screen saved with dopcopyfrom.
  50.  
  51. Example: CALL dopcopyto
  52.  
  53. --------------------------------------------------------------------------------
  54. * sub drawbox (yd%, xd%, tpe%, shadow%, title$)  
  55.  
  56.  
  57. Draws a box or window, with the upper left corner at the
  58. current cursor position.  It's used to draw most of the
  59. boxes in Menusys and Menulib.  Set global variable explode% 
  60. to >0 for "exploding" boxes (>1 = longer delay).
  61.  
  62. yd% / xd% = Y and X dimensions of the box desired
  63.  
  64. tpe% = border type:
  65.  
  66. 0 = no border
  67. 1 = single border
  68. 2 = double border
  69.  
  70. shadow% = shadow type:
  71.  
  72. 0 = no shadow
  73. 1 = left shadow
  74. 2 = right shadow
  75.  
  76. title$ = title for box (set to "" for none)
  77.  
  78. Example: LOCATE 1,1
  79.      CALL drawbox(10, 10, 1, 2, "This is a box")
  80.  
  81. --------------------------------------------------------------------------------
  82. * sub findfile (fi$, yn%)  
  83.  
  84.  
  85. Searches for the specified path\file in fi$.  If not
  86. found, yn% = 0, else yn% = 1.
  87.  
  88. example: INPUT "Filename ";fi$
  89.      call findfile(fi$, yn%)
  90.      if yn% = 0 then print "File Not Found"
  91.  
  92. --------------------------------------------------------------------------------
  93. * sub mcheck  
  94.  
  95.  
  96. Checks current position of mouse cursor and state of buttons
  97. and updates the corresponding global variables msy%, msx%, lb%
  98. and rb% (for lb% and rb%, 1 = pressed, 0 = not pressed).
  99.  
  100. msy% = y coordinates of mouse cursor (1-25)
  101. msx% = x coordinates of mouse cursor (1-80)
  102. lb% = left button
  103. rb% = right button
  104.  
  105. Example: CALL mcheck
  106.  
  107. --------------------------------------------------------------------------------
  108. * sub menusys (menu$(), help$(), menucount%(), menutype%(), topchoice%, bottomchoice%)  
  109.  
  110.  
  111. Displays a pull-down menu at the top of the screen.  DIM menu$
  112. (topcount%, bottomcount%), help$(topcount%, bottomcount%),
  113. menutype%(topcount%, bottomcount%).  Topcount% should correspond
  114. to the number of top (bar) menu choices available, and bottomcount%
  115. to the MAXIMUM number of bottom menu choices available.
  116.  
  117. topchoice% and bottomchoice% will be returned, corresponding to the top
  118. (bar) and bottom (box) menu choices selected by the user.  If the user
  119. presses ESC, bottomchoice% will equal zero.  Set global variable flash%
  120. to 1 before calling for "flashing" menu selection when selected with
  121. mouse or ENTER.
  122.  
  123. * This is the "main" routine in the MENUSYS Library,
  124. * and the one routine that calls most of the others.
  125.  
  126. Menu Types (for menutype%):
  127.  
  128. 0 = Available (normal)
  129. 1 = Unavailable (cannot be selected)
  130. 2 = Bullet On
  131. 3 = Bullet Off
  132.  
  133. Use Function ALTKEY in a separate program to determine if the ALT key
  134. is pressed (to call this routine) and/or use the mouse routines to
  135. determine if the mouse cursor is in the top row and proper column
  136. to call this routine.  If not using ALTKEY or mouse cursor to call
  137. MENUSYS, you can set topchoice% to the starting choice number for
  138. the top menu before calling (defaults to menu option one).
  139.  
  140. Menu Selection Columns (for each top item):
  141.  
  142. 1 = 1-10       2 = 11-20       3 = 21-30       4 = 31-40
  143. 5 = 41-50      6 = 51-60       7 = 61-70       8 = 71-80
  144.  
  145. Example: CALL menusys(menu$(), help$(), menucount%(), menutype%(), topch%, botch%)
  146.      PRINT "You Chose ";topch%; botch%
  147.  
  148. --------------------------------------------------------------------------------
  149. * sub mhardreset (ms%, nb%)  
  150.  
  151.  
  152. Checks status of mouse and resets if present.  Use this routine
  153. at the beginning of a program to check for the presence of a mouse
  154. and to reset it if present.
  155. Returns ms% = -1 and nb% = number of buttons if mouse driver present
  156. and reset, otherwise ms% = 0.
  157.  
  158. Example: CALL mhardreset(mouse%, nb%)
  159.      IF mouse%<>0 then print "Mouse Found, with ";nb%;" buttons."
  160.  
  161. --------------------------------------------------------------------------------
  162. * sub mhide  
  163.  
  164.  
  165. Makes the mouse cursor invisible, and decrements the internal
  166. mouse cursor flag by one.
  167.  
  168. Example: IF mouse% <> 0 THEN CALL mhide
  169.  
  170. --------------------------------------------------------------------------------
  171. * sub mscrolldown (nls%, uly%, ulx%, lry%, lrx%, atrb%)  
  172.  
  173.  
  174. Scrolls a portion of the text screen down, turning the mouse
  175. cursor off first if necessary.  Set uly% and ulx% to the
  176. coordinates for the upper left corner of the area to scroll,
  177. and lry% and lrx% to the lower right corner of the area to
  178. scroll.  Set atrb% to the attribute to scroll into the blank
  179. area.  nls% = number of lines to scroll down (if 0, the entire
  180. area is blanked).
  181.  
  182. Example: CALL mscrolldown(1, 1, 1, 25, 80, 7)
  183.  
  184. --------------------------------------------------------------------------------
  185. * sub mscrollup (nls%, uly%, ulx%, lry%, lrx%, atrb%)  
  186.  
  187.  
  188. Scrolls a portion of the text screen up, turning the mouse
  189. cursor off first if necessary.  Set uly% and ulx% to the
  190. coordinates for the upper left corner of the area to scroll,
  191. and lry% and lrx% to the lower right corner of the area to
  192. scroll.  Set atrb% to the attribute to scroll into the blank
  193. area.  nls% = number of lines to scroll up (if 0, the entire
  194. area is blanked).
  195.  
  196. Example: CALL mscrollup(1, 1, 1, 25, 80, 7)
  197.  
  198. --------------------------------------------------------------------------------
  199. * sub mshow  
  200.  
  201.  
  202. Increments the internal mouse cursor flag, and if flag = 0, makes
  203. the mouse cursor visible.  Flag defaults to -1 when driver is reset,
  204. so this function will usually make the cursor visible on the screen.
  205.  
  206. Example: CALL mshow
  207.  
  208. --------------------------------------------------------------------------------
  209. * sub mwaitrelease  
  210.  
  211.  
  212. Waits for Left/Right Mouse Button to be Released.
  213.  
  214. Example: CALL mwaitrelease
  215.  
  216. --------------------------------------------------------------------------------
  217. * sub pagecopy(source%, dest%)  
  218.  
  219.  
  220. New and improved for V2.0 - "Shadows" the contents of the current
  221. text screen into a buffer array you set up at the start of your
  222. Menusys/Menulib programs.  Works the same as QuickBASIC's PCOPY
  223. command, but does not use any screen pages except page zero,
  224. making Menusys compatible with the Monochrome Display Adapter.
  225.  
  226. Example: CALL pagecopy(source%, dest%)
  227.  
  228. --------------------------------------------------------------------------------
  229. * sub printbottomhelp (hlp$)  
  230.  
  231.  
  232. Internal routine used by Menusys, but can be used externally as well.
  233. Displays the line of help text in hlp$ on the bottom of the screen.
  234. Blanks the bottom screen line if hlp$ = "-". To skip print, set hlp$
  235. to "".
  236.  
  237. Example: hlp$="Press F1 for Help"
  238.      CALL printbottomhelp(hlp$)
  239.  
  240. --------------------------------------------------------------------------------
  241. * sub printbottommenu (top%, menu$(), menucount%(), menutype%(), bcheck$)  
  242.  
  243.  
  244. An internal routine used by MENUSYS to display the bottom (box) menus.
  245.  
  246. --------------------------------------------------------------------------------
  247. * sub printtopmenu (menu$(), hilight%)  
  248.  
  249.  
  250. An internal routine used by MENUSYS to display the top (bar) menu.
  251. This can also be called from your main program to display just the
  252. top (bar) menu so the user knows it's there before the MENUSYS routine
  253. is called.  See MNSDEMO.BAS for an example of how this is done.
  254.  
  255. Example: CALL printtopmenu(menu$(), hilight%)
  256.  
  257. --------------------------------------------------------------------------------
  258. * sub readhelp (topchoice%, bottomchoice%)  
  259.  
  260.  
  261. A routine to display context-sensitive help.  Utilized by MENUSYS but can
  262. also be called externally.  The global variable HELPFN$ should be set to
  263. the path\filename of the help file, and PROGNAME$ to the name of the program
  264. that the help is for.  The format of the help files in MENUSYS is:
  265.  
  266. [1/1]
  267.  
  268. HELP TEXT
  269.  
  270. ~~~
  271. [1/2]
  272.  
  273. HELP TEXT
  274.  
  275. ~~~
  276. [1/3]
  277.  
  278. HELP TEXT
  279.  
  280. ~~~
  281.  
  282. The top and bottom menu entries for the help item desired should be in
  283. topchoice% and bottomchoice% before calling.  Notice that each help entry
  284. in the help file has the top/bottom menu entries defined in square brackets,
  285. followed immediately by the help text.  At the end of the help text for each
  286. menu item, there are three tildes in a row.  There can be an unlimited
  287. number of help items in each help file, as long as they follow the above
  288. format (see the example help file included with MENUSYS).  If you use
  289. [0/0] or any other numbers that don't fall in the area of the top/bottom
  290. menu entries, you can call readhelp from the main program to display help
  291. on other program options.  For example, you could CALL READHELP(0,0) and
  292. have a [0/0] entry in your help file.
  293.  
  294. If you don't want MENUSYS to display help for the various pulldown menu
  295. items, just set HELPFN$ to "" before calling.  Also, if READHELP doesn't
  296. find the help file indicated in HELPFN$, it won't crash but it won't
  297. display any help either.  If it finds the help file but not the entry
  298. specified in topchoice%/bottomchoice%, it will display "NO HELP AVAILABLE
  299. FOR THIS MENU ENTRY."
  300.  
  301. Example: PRINT "You Pressed F1!"
  302.      CALL readhelp(0, 0)
  303.  
  304.  
  305. --------------------------------------------------------------------------------
  306. * sub readscreen (y%, x%, ch%, atr%, fgd%, bkg%)  
  307.  
  308.  
  309. A routine to read the contents of the screen at the Y (1-25) and X
  310. (1-80) coordinates specified in y% and x%.  The character at the screen
  311. position specified will be returned in ch%, the attribute value in atr%,
  312. the foreground color in fgd%, and the background color in bkg%.
  313. '
  314. Example: CALL readscreen(1, 1, ch%, atr%, fgd%, bkg%)
  315.  
  316. --------------------------------------------------------------------------------
  317. * sub tophilight (top%, hilight%, menu$())  
  318.  
  319.  
  320. An internal routine used by MENUSYS to highlight entries on the top
  321. (bar) menu.
  322.  
  323. --------------------------------------------------------------------------------
  324. * function vidseg&  
  325.  
  326.  
  327. Returns the current segment of the video
  328. buffer.  Returns &hb000 for monochrome
  329. or &hb800 if a color display.
  330.  
  331. Example: PRINT vidseg&
  332.  
  333. --------------------------------------------------------------------------------
  334. * sub writescreen (y%, x%, ch%, atr%, fgd%, bkg%)  
  335.  
  336.  
  337. A routine to store a certain value at a specified screen location.  Set y%
  338. and x% to the Y and X screen coordinates desired, ch% to the character to
  339. store.  Then either set atr% to 0 and fgd% and bkg% to the desired
  340. foreground/background colors, or set atr% to the desired attribute and
  341. ignore the values of fgd% and bkg%, and call this routine.
  342.  
  343. Example: CALL writescreen(1, 1, 32, 0, 7, 1)
  344.  
  345.