home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #1 / monster.zip / monster / PROG_BAS / MNUSYS22.ZIP / MENULIB.DOC < prev    next >
Text File  |  1994-01-13  |  18KB  |  561 lines
  1. Menulib for Menusys-PB
  2. Add-On Library Routines V2.2
  3. (C) Copyright 1993, 1994 by Tim Gerchmez
  4. All Rights Reserved.
  5.  
  6. --------------------------------------------------------------------------------
  7. * sub alertbox (msg$)
  8.  
  9.  
  10. Prints a one-line alert message on the screen and
  11. waits for user to select OK with mouse or ENTER.
  12.  
  13. msg$: Set to alert message to be displayed (one line).
  14.  
  15. Example: CALL alertbox("File not Found")
  16.  
  17. --------------------------------------------------------------------------------
  18. * sub background (ch%)
  19.  
  20.  
  21. Fills the screen with a special character, creating a
  22. background.  Uses colors in clr%, bckg%.
  23. Set chr% = 0 for black background, 1 for dark background, 2 for medium,
  24. 3 for light, 4 for pure
  25.  
  26. Example: CALL background(2)
  27.  
  28. --------------------------------------------------------------------------------
  29. * sub checkbox (title$, optn$(), optn%())
  30.  
  31.  
  32. Lets the user pick from a list of options with the mouse cursor or
  33. the keyboard.  More than one option can be selected.  Set title$
  34. to the title to display on the list and DIM optn$() to the text
  35. for the list of options.  Upon return, optn%(x) will contain either
  36. a zero (user didn't select it) or a one (user selected it).  Subsequent
  37. calls to checkbox will retain the user's choices in optn%() if the array
  38. isn't erased or redimensioned.
  39.  
  40. Note: Use LBOUND of 1 for arrays (DIM 1 : X)
  41.  
  42. Example: title$="Select Options:" : REDIM optn$(1:3), optn%(1:3)
  43. optn$(1)="Option 1":optn$(2)="Option 2":optn$(3)="Option 3"
  44. CALL checkbox(title$, optn$(), optn%())
  45.  
  46. --------------------------------------------------------------------------------
  47. * sub choosebox (msg$(), choice%)
  48.  
  49.  
  50. Prints a multi-line message on the screen in a box,
  51. and waits for user to select OK or CANCEL.
  52. Returns with user's choice in choice%
  53.  
  54. msg$(): Set to message text to be displayed
  55. choice%: User's choice returned in choice% (0=OK, 1=CANCEL)
  56.  
  57. Note: Use LBOUND of 1 for arrays (DIM 1 : X)
  58.  
  59. Example: DIM msg$(1:2)
  60.          msg$(1)="Would you like to"
  61. msg$(2)="continue the current operation?"
  62. CALL choosebox(msg$(), choice%)
  63. if choice% = 1 then print "Nope!" : END
  64.  
  65. --------------------------------------------------------------------------------
  66. * sub choosedir (d$, ch$, rod%)
  67.  
  68.  
  69. Lets a user select from a directory entry in a screen window.
  70. Includes the ability to switch to new drives/subdirectories.
  71.  
  72. d$: Set to directory mask desired (normally "*.*")
  73. ch$: User's choice returned in ch$, or "" if cancelled
  74. rod%: Set to 1 to stay at current directory/drive and return full path, or
  75. 0 to change to directory/drive selected by user and return just
  76. the filename.
  77.  
  78. Example: CALL choosedir("*.*", ch$, 0)
  79.  
  80. --------------------------------------------------------------------------------
  81. * sub getdisk (d%)
  82.  
  83.  
  84. Returns drive code of current or default drive.
  85. 0 = A, 1 = B, 2 = C, Etc.
  86.  
  87. Example: CALL getdisk(d%)
  88.  
  89. --------------------------------------------------------------------------------
  90. * sub hscrollbar (starty%, startx%, length%)
  91.  
  92.  
  93. Displays a horizontal "scroll bar" on the screen starting at position
  94. starty%/startx%, of length length% characters.  See the demo program
  95. for an example of hscrollbar.  This routine displays the scroll bar only-
  96. it does not control scrolling or any other related functions.  A future
  97. version of Menulib may more fully implement the hscrollbar feature.
  98.  
  99. Example: CALL hscrollbar(23, 1, 20)
  100.  
  101. --------------------------------------------------------------------------------
  102. * sub infobox (msg$())
  103.  
  104.  
  105. Prints a multi-line message on the screen in a box,
  106. and waits for user to select OK with mouse or ENTER.
  107. This differs from alertbox in that you can display
  108. more than one line of text in the box.
  109.  
  110. msg$(): Set to message text to be displayed.
  111.  
  112. Note: Use LBOUND of 1 for arrays (DIM 1 : X)
  113.  
  114. Example: DIM msg$(2)
  115.          msg$(1)="Disk Problem-"
  116.          msg$(2)="Select OK"
  117. CALL infobox(msg$())
  118.  
  119. --------------------------------------------------------------------------------
  120. * sub inpbox (msg$, ip$, mx%, mxlen%, ll%, ul%)
  121.  
  122.  
  123. Allows user input in a shadowed screen box.
  124. The string the user enters is returned in ip$.
  125. If the user presses ENTER alone, ip$ will be set
  126. to CHR$(13).  If the user presses ESC or CANCEL,
  127. ip$ will be the null string ("").  ip$ is re-used
  128. as the default for the next user input, so you can
  129. control the "default" input by setting ip$ before
  130. calling this routine.
  131.  
  132. msg$: Set to message prompt for input
  133. ip$:  User's choice returned in ip$
  134. mx%: Set to maximum length of input allowable
  135. mxlen%: Length of Input Field in Box (Scrolls if
  136.         shorter than mx%)
  137. ll%: Set to lowest ASCII value permitted for input
  138. ul%: Set to highest ASCII value permitted for input
  139.  
  140. Example-
  141. To input a 3-digit number
  142. with "100" being the default value:
  143.  
  144. msg$="Enter Number:"
  145. mx% = 3:ip$ = "100"
  146. ll% = 48  :' ASCII value of "0"
  147. ul% = 57  :' ASCII value of "9"
  148. CALL inpbox(msg$, ip$, mx%, mx%, ll%, ul%)
  149. number% = val(ip$)
  150. print "You Entered ";ip%
  151.  
  152. --------------------------------------------------------------------------------
  153. * sub marklist (lst$(), mrk?())
  154.  
  155.  
  156. Similar to picklist, but lets the user "mark off"
  157. multiple options, instead of selecting just one.
  158.  
  159. lst$(): Set to text of items to be listed
  160. mrk?(): User's choices returned in mrk?() (1=marked, 0=not)
  161.  
  162. Example: CALL marklist (lst$(), mrk?())
  163.  
  164. --------------------------------------------------------------------------------
  165. * sub mcls
  166.  
  167.  
  168. New for V2.x.
  169. Clears the screen and turns the mouse cursor
  170. on/off to prevent "mouse droppings."
  171.  
  172. Example: CALL mcls
  173.  
  174. --------------------------------------------------------------------------------
  175. * sub menupick (title$, mb$(), help$(), choice%)
  176.  
  177.  
  178. Allows user to choose from a menu using either
  179. the mouse or the cursor keys.  This is the typical
  180. "vertical" menu displayed in the center of the screen,
  181. with a highlighted bar than can be moved with the
  182. mouse or crsr keys.  Screen is saved upon calling
  183. and automatically restored when done.
  184.  
  185. title$ = title to display on menu
  186. mb$() = text for menu choices
  187. help$() = one-line help message for each menu option
  188. choice% = choice returned by the user (0 if cancelled).
  189.  
  190. Set the cursor position (using LOCATE) to where you want
  191. the upper left corner of the menu before calling this
  192. routine.  help$() must be dimensioned to the same value
  193. as mb$(), but need not be defined.  For ONE helpline for
  194. all menu selections, set help$(1) to the text desired.
  195.  
  196. Example: title$="Select an Option"
  197. redim mb$(2),help$(2)
  198. mb$(1)="Option 1":mb$(2)="Option 2"
  199. help$(1)="Select an option or press ESC to cancel"
  200. CALL menupick(title$, mb$(), help$(), choice%)
  201. print "You Picked ";choice%
  202.  
  203. --------------------------------------------------------------------------------
  204. * sub messagebox (title$, msg$())
  205.  
  206.  
  207. This routine prints a multi-line message in a box and exits
  208. without delay.  Use for messages you want to remain on the
  209. screen.  Title$ is printed at the top of the box, followed by
  210. a horizontal line, followed by the text in msg$().  Upon exit,
  211. the cursor is located at the position corresponding to the upper
  212. left corner of the box.  You can use this to calculate where to
  213. print further messages inside the box.
  214.  
  215. Example: LOCATE 10, 10
  216. redim msg$(1:1)
  217. title$="Loading..."
  218. msg$(1)="Record #:"
  219. call messagebox(title$, msg$())
  220. LOCATE csrlin+3, pos(0)+11
  221. print "5";  'Print Record #
  222.  
  223. --------------------------------------------------------------------------------
  224. * sub mgetpos
  225.  
  226.  
  227. Checks current position of mouse cursor and updates the
  228. corresponding global variables msy% and msx%.
  229.  
  230. Example: CALL mgetpos
  231. PRINT msy%; msx%
  232.  
  233. --------------------------------------------------------------------------------
  234. * sub mgetpress (button%, numpresses&, ycc%, xcc%)
  235.  
  236.  
  237. Checks button indicated in button% (1 = left, 2 = right)
  238. and returns status of buttons in globals lb% and rb%, number
  239. of presses of specified button since last call (in numpresses&),
  240. and Y and X coordinates of mouse cursor the last time the specified
  241. button was pressed (in ycc% and xcc%).
  242.  
  243. Example: CALL mgetpress(button%, numpresses&, ycc%, xcc%)
  244.  
  245. --------------------------------------------------------------------------------
  246. * sub mgetrelease (button%, numreleases&, ycc%, xcc%)
  247.  
  248.  
  249. Checks button indicated in button% (1 = left, 2 = right)
  250. and returns status of buttons in globals lb% and rb%, number
  251. of releases of specified button since last call (in numreleases&),
  252. and Y and X coordinates of mouse cursor the last time the specified
  253. button was released (in ycc% and xcc%).
  254.  
  255. Example: CALL mgetrelease(1, numreleases&, ycc%, xcc%)
  256.  
  257. --------------------------------------------------------------------------------
  258. * sub mousepick (ypos%(), xmin%(), xmax%(), pick%)
  259.  
  260.  
  261. Checks arrays to see if mouse cursor is at positions specified
  262. in: ypos%(x) = line, xmin%(x) = minimum x pos. on line ypos%(x)
  263. and xmax%(x) = maximum x pos. on line ypos%(x).  If mouse cursor is
  264. at any of these locations (inclusive) AND left button is pressed,
  265. hilights desired area, waits til left button released, then returns
  266. with position number in pick%.
  267.  
  268. This routine requires quite a bit of setting up to use effectively,
  269. but essentially simulates a number of "buttons" on the screen that
  270. can be "pressed" with the mouse.  This routine does not utilize the
  271. keyboard at all, just the mouse, and you must draw the "buttons" on
  272. the screen first before calling the routine.  DIM the arrays to the
  273. number of "buttons" desired, Specify the Y position of each "button"
  274. in ypos%(), the minimum (lowest) X position of each "button" in
  275. xmin%(), and the maximum (highest) X position of each button in
  276. xmax%().
  277.  
  278. Example: DIM ypos%(1:5), xmin%(1:5), xmax%(1:5): '5 "buttons"
  279. ... draw 5 "buttons" on the screen
  280. ... (set ypos%(1) thru ypos%(5), same with xmin%()
  281. and xmax%()
  282. CALL mousepick(ypos%(), xmin%(), xmax%(), pick%)
  283.  
  284. --------------------------------------------------------------------------------
  285. * sub mprint (mp$)
  286.  
  287.  
  288. New for V2.x
  289. Same as normal PRINT, but turns off mouse cursor first if
  290. necessary.  Only prints strings, and does not work with PRINT
  291. USING.  No carriage return afterwards.
  292.  
  293. Example: mprint a$
  294. or     : call mprint (a$)
  295.  
  296. --------------------------------------------------------------------------------
  297. * sub msetpos
  298.  
  299.  
  300. Uses global variables msy% and msx% to set a new
  301. position for the mouse cursor.  Change msy% and/or
  302. msx% before calling this routine.
  303.  
  304. Example: msy% = 1: msx% = 1: CALL msetpos
  305.  
  306. --------------------------------------------------------------------------------
  307. * sub mwaitpress
  308.  
  309.  
  310. Waits for a Mouse Button to be Pressed.
  311.  
  312. Example: CALL mwaitpress
  313.  
  314. --------------------------------------------------------------------------------
  315. * sub mxbounds(mn%, mx%)
  316.  
  317.  
  318. Sets minimum and maximum x-axis boundaries for mouse cursor
  319. movement.  In other words, confines the mouse cursor to a
  320. certain range of (horizontal) columns on the screen.
  321.  
  322. Example: CALL mxbounds(3, 77)
  323.  
  324. --------------------------------------------------------------------------------
  325. * sub mybounds (mn%, mx%)
  326.  
  327.  
  328. Sets minimum and maximum y-axis boundaries for mouse cursor
  329. movement.  In other words, confines the mouse cursor to a
  330. certain range of (vertical) rows on the screen.
  331.  
  332. Example: CALL mybounds(2, 24)
  333.  
  334. --------------------------------------------------------------------------------
  335. * function pathstring$
  336.  
  337.  
  338. Returns current disk/path in a string of the
  339. form C:\QB\EXE\ ... Trailing backslash included.
  340. Updated for Menusys 2.x using curdir$ function.
  341.  
  342. Example: PRINT pathstring$
  343.  
  344. --------------------------------------------------------------------------------
  345. * sub picklist (lst$(), choice%)
  346.  
  347.  
  348. Lets the user pick from a long list of options in a window, sizing
  349. and scrolling the window as necessary.  Set lst$() to the text for
  350. the list.  User's choice is returned in choice% (0 if cancelled).
  351.  
  352. Example: DIM lst$(100)
  353. ... Read in text file to lst$(x)
  354. CALL picklist(lst$(), choice%)
  355. PRINT "You Picked ";choice%
  356.  
  357. --------------------------------------------------------------------------------
  358. * sub printborder
  359.  
  360.  
  361. Prints a border around the text screen -
  362. See demo program for example usage.
  363.  
  364. Example: CALL printborder
  365.  
  366. --------------------------------------------------------------------------------
  367. * sub printtitle (title$, starty%, hilight%)
  368.  
  369.  
  370. Prints a title on the screen, either highlighted
  371. or not highlighted.  See the demo program (title
  372. is printed one line below the menu bar at the top).
  373.  
  374. Example: CALL printtitle("Program.dat", 20, 1)
  375.  
  376. --------------------------------------------------------------------------------
  377. * sub radiobox (title$, optn$(), choice%)
  378.  
  379.  
  380. Displays a "radio button box" and lets user select one
  381. option from a list of options.  User's choice is returned
  382. in choice%.  Use instead of checkbox if only one option is
  383. possible out of a list of many.  If cancelled with ESC, choice%
  384. will equal 0.
  385.  
  386. title$: Set to title for radio button box
  387. optn$(): Set to text for options
  388. choice%: Returns the user's choice in choice%
  389.  
  390. Example: DIM optn$(3)
  391.          optn$(1) = "Option 1"....
  392.          CALL radiobox("Pick One",optn$(), choice%)
  393.          PRINT "You Chose ";choice%
  394.  
  395. --------------------------------------------------------------------------------
  396. * sub screenedit (x1%, x2%, y1%, y2%, ky$)
  397.  
  398.  
  399. An advanced routine that allows a user to edit a portion of the
  400. screen, using all the normal cursor keys and editing controls.
  401.  
  402. x1%, x2% = Minimum and Maximum X Positions allowed (1-80).
  403. y1%, y2% = Minimum and Maximum Y Positions allowed (1-25).
  404. ky$ = keypress returned (if ESC or a scancode key is
  405. pressed that the routine doesn't recognize).
  406.  
  407. Example: CALL screenedit(1, 80, 1, 25, ky$)
  408.  
  409. See the MNSDEMO.BAS program for an example of how screenedit
  410. can be used.
  411.  
  412. --------------------------------------------------------------------------------
  413. * sub screenrecall(scn%)
  414.  
  415.  
  416. New for V2.x
  417. Recalls a screen previously saved with SCREENSTORE.
  418. See SCREENSTORE for details on how to use.
  419.  
  420. scn%: Set to 1 to 7 (cannot recall from current page, normally 0)
  421.  
  422. Example: CALL screenrecall(4)
  423.  
  424. --------------------------------------------------------------------------------
  425. * sub screenstore(scn%)
  426.  
  427.  
  428. New for V2.x
  429.  
  430. Uses PAGECOPY in Menusys to store a screen in the
  431. variable SCRNBUF?().
  432.  
  433. Set the second dimension of SCRNBUF? in PAGECOPY
  434. to the highest value desired (depending on how many
  435. screens you want to store).  It's recommended you
  436. don't store to screens 0-3, as these are reserved by
  437. Menusys/Menulib.  For example, you could use:
  438. DIM scrnbuf?(1:4096, 0:7)
  439. which would provide storage space for screens 0-7.
  440. You could then CALL SCREENSTORE (4) to store the
  441. current text screen in slot number 4, and
  442. CALL SCREENRECALL(4) to recall it.  In this case, you'd
  443. have set aside 32K (8*4096) bytes for screen storage,
  444. and you could use slots 4-7 for storing your own screens.
  445. This is the default setting.
  446.  
  447. Example: CALL screenstore(4)
  448.  
  449. --------------------------------------------------------------------------------
  450. * sub selectback (ch%)
  451.  
  452.  
  453. Allows a user to select a background color from a menu, and
  454. returns selection in cl% ... -1 if user cancelled.
  455. See MLIBDEMO.BAS for example of use.
  456.  
  457. Example: CALL selectback(ch%)
  458.  
  459. --------------------------------------------------------------------------------
  460. * sub selectfore (ch%)
  461.  
  462.  
  463. Allows a user to select a foreground color from a menu, and
  464. returns selection in cl% ... -1 if user cancelled.
  465. See MLIBDEMO.BAS for example of use.
  466.  
  467. Example: CALL selectfore(cl%)
  468.  
  469. --------------------------------------------------------------------------------
  470. * sub setdisk (d%)
  471.  
  472.  
  473. Sets disk in d% to be default (current drive):
  474. 0 = A, 1 = B, 2 = C, etc.
  475. Returns number of logical drives in system in d%.
  476.  
  477. Example: CALL setdisk(0) :' Set to A:
  478.  
  479. --------------------------------------------------------------------------------
  480. * sub showarray (title$, maxline%, holdit$())
  481.  
  482.  
  483. New to Version 2.x - Displays passed text array.
  484. Called by SHOWTEXTFILE in Menulib V2.x.  Does not
  485. save previous screen or change array in holdit$().
  486. Call with title$ = title to display at bottom
  487. of screen and maxline% maximum element of the
  488. array (line) to display.
  489.  
  490. Example: CALL showarray("DEMO.BAS", 32, holdit$())
  491.  
  492. --------------------------------------------------------------------------------
  493. * sub showtextfile (fi$, clr%)
  494.  
  495.  
  496. An advanced routine that displays a textfile specified in fi$.
  497. Set clr% to the foreground color to display the text file in
  498. before calling this routine.  This routine calls SHOWARRAY after
  499. loading a text file into an array.
  500.  
  501. Example: CALL showtextfile("test.dat", 15)
  502.  
  503. --------------------------------------------------------------------------------
  504. * sub sounds (num%)
  505.  
  506.  
  507. Plays a sound on the PC's speaker.
  508. Set num% to:
  509.  
  510. 1 = popup
  511. 2 = popdown
  512. 3 = klaxon
  513. 4 = siren
  514. 5 = blip
  515. 6 = 2-tone
  516. 7 = 2-tone triple
  517. 8 = 3-tone
  518. 9 = buzz
  519. 10 = chirp
  520. 11-14 = beep1-4
  521. 15 = 60hz
  522.  
  523. Example: CALL sounds(1)
  524.  
  525. --------------------------------------------------------------------------------
  526. * function trimpath$(fi$)
  527.  
  528.  
  529. New to V2.x -
  530. Trims the path off a filename, returning
  531. just the original filename (12 char. max).
  532.  
  533. Example: PRINT trimpath$("C:\TEMP\TEST.BAS")
  534.  
  535. --------------------------------------------------------------------------------
  536. * sub vscrollbar (starty%, startx%, length%)
  537.  
  538.  
  539. Displays a vertical "scroll bar" on the screen starting at position
  540. starty%/startx%, of length% characters (vertically).  See the demo
  541. program for an example of vscrollbar.  This routine displays the
  542. scrollbar only - does not control scrolling or anything else.  A
  543. future version of Menulib may more fully implement the VSCROLLBAR
  544. feature.
  545.  
  546. Example: CALL vscrollbar (1, 78, 15)
  547.  
  548. --------------------------------------------------------------------------------
  549. * sub yesnobox (msg$, choice%)
  550.  
  551.  
  552. Prints a one-line message on the screen in a box,
  553. and waits for user to select YES, NO or CANCEL.
  554. Shortest string in msg$ should be >20.
  555.  
  556. msg$: Set to one-line message to display in box
  557. choice%: Returns user's choice in choice% (1=yes, 0=no, -1=cancel).
  558.  
  559. Example: CALL yesnobox("Are you Sure?", choice%)
  560.  
  561.