home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / BASIC / MNUSYS11 / MENULIB.TXT < prev    next >
Text File  |  1993-09-23  |  20KB  |  572 lines
  1. Menulib for Menusys
  2. Add-On Library Routines
  3. for PowerBASIC 3.0
  4.  
  5. (C) Copyright 1993 by Tim Gerchmez
  6. ----------------------------------
  7.  
  8.  
  9.             ** SUB/Function Reference **
  10.  
  11.  
  12. Note: Especially powerful/high-level routines
  13.       are marked with "*P*" to distinguish
  14.       them from the rest.
  15.  
  16. Total Routines: 41
  17. ------------------------------------------------------------------------------
  18. * SUB about
  19.  
  20. Displays the title and author of the current program
  21. in a window and waits for the user to press ENTER or
  22. click "OK" with the mouse.  Source code version is
  23. required to modify this routine.
  24.  
  25. Example: CALL about
  26.  
  27. -----------------------------------------------------------------------------
  28. * SUB alertbox (msg$)
  29.  
  30. Prints a one-line alert message on the screen and
  31. waits for user to select OK with mouse or ENTER.
  32.  
  33. Example: CALL alertbox("File Not Found")
  34.  
  35. -----------------------------------------------------------------------------
  36. * SUB background (ch%)
  37.  
  38. Fills the screen with a special character, creating a
  39. background.  Uses colors in global variables clr% and bckg%.
  40. Set ch% = 0 for black background, 1 for dark background, 2 for medium,
  41. 3 for light, 4 for pure.
  42.  
  43. Example: CALL background(2)
  44.  
  45. -----------------------------------------------------------------------------
  46. * SUB bigprint (ch$, u$)
  47.  
  48. Prints a giant representation of the ASCII value in ch$.
  49. Uses the character in u$ to represent the "dots" for the big
  50. character.  Cursor Position is restored afterward.
  51.  
  52. Example: CALL bigprint ("A",chr$(219))
  53.  
  54. ------------------------------------------------------------------------------
  55. * SUB bigprintline (ln$, u$)
  56.  
  57. *P*
  58.  
  59. Print an entire line of characters in ln$ in giant size print.
  60. Uses the character in u$ to print the giant "pixels."
  61. Maximum: 10 characters in ln$ (80-col. screen).
  62. Ready to print another line after routine is called .. begins
  63. on the line the cursor is currently on.  Add 8 to the current
  64. Y position for the next "screen line".  One screen will hold
  65. about 3 lines of 10 giant characters.
  66.  
  67. Example:  LOCATE 1, 1
  68.       CALL bigprintline("Testing123",chr$(219))
  69.  
  70. -----------------------------------------------------------------------------
  71. * SUB checkbox (title$, optn$(), optn%())
  72.  
  73. Lets the user pick from a list of options with the mouse cursor or
  74. the keyboard.  More than one option can be selected.  Set title$
  75. to the title to display on the list, and DIM optn$() to the text
  76. for the list of options.  Upon return, optn%(x) will contain either
  77. a zero (user didn't select it) or a one (user selected it).  Subsequent
  78. calls to checkbox will retain the user's choices in optn% if the array
  79. isn't erased or redimensioned.
  80.  
  81. Example: title$="Select Options:":REDIM optn$(1:3), optn%(1:3)
  82.      optn$(1)="Option 1":optn$(2)="Option 2":optn$(3)="Option 3"
  83.      CALL checkbox(title$, optn$(), optn%())
  84.  
  85. -----------------------------------------------------------------------------
  86. * SUB choosebox (msg$(), choice%)
  87.  
  88. Prints a multi-line message on the screen in a box,
  89. and waits for user to select OK or CANCEL.
  90. Returns 0 (OK) or 1 (Cancel)
  91. Shortest string in msg$(x) should be >20.
  92. Returns with user's choice in choice%:
  93.  
  94. 0 = OK
  95. 1 = Cancel
  96.  
  97. Example: DIM msg$(1:2)
  98.      msg$(1)="Would you like to"
  99.      msg$(2)="Continue the current operation?"
  100.      CALL choosebox(msg$(), choice%)
  101.      IF choice% = 1 then print "Nope!" : end
  102.  
  103. -----------------------------------------------------------------------------
  104. * SUB choosedir (d$, ch$)
  105.  
  106. *P*
  107.  
  108. Lets a user select from a directory entry on the screen.  Includes
  109. ability to switch to new drives/subdirectories.  Call with d$ =
  110. directory mask (normally "*.*").  Routine returns with user's choice
  111. of filename in ch$ (or null string if cancelled).
  112.  
  113. Example: CALL choosedir("*.*",ch$)
  114.  
  115. -----------------------------------------------------------------------------
  116. * SUB clearline (ln%)
  117.  
  118. Clears a selected screenline, including position 80, without
  119. scrolling the screen.  Also preserves the current cursor position
  120. and turns off the mouse cursor if necessary.
  121.  
  122. Example: CALL clearline (25)
  123.  
  124. -----------------------------------------------------------------------------
  125. * FUNCTION endofline% (ln%)
  126.  
  127. Finds the position of the END OF TEXT on a specified screen line.
  128. For example, if line 20 of the screen had the line
  129.  
  130.  
  131. This is a test
  132.  
  133.           ^
  134.           15
  135.  
  136. on it, PRINT endofline%(20) would return 15 (the last character
  137. plus one, indicating the blank space following the line of text).
  138. If there is no text on the specified screen line, a value of 80
  139. will be returned.
  140.  
  141. Example: a% = endofline%(2)
  142.  
  143. -----------------------------------------------------------------------------
  144. * SUB getdisk (d%)
  145.  
  146. Returns drive code of current or default drive.
  147. 0 = A, 1 = B, 2 = C, Etc. in d%.
  148.  
  149. Example: CALL getdisk(d%)
  150.  
  151. -----------------------------------------------------------------------------
  152. * SUB getfontinfo (code%, points%, rows%, sg&, offset&)
  153.  
  154. EGA, MCGA, VGA
  155. Returns a pointer to a font's character definition table, and
  156. the points (bytes per character) and rows for that font.
  157. Call with code% set to one of the following values:
  158. 0 = INT 1fh contents, 1 = INT 43h contents, 2 = ROM 8x14
  159. font, 3 = ROM 8x8 font (chars 00h-7fh), 4 = ROM 8x8
  160. font (chars 80h-ffh), 5 = ROM alternate 9x14 font, 6 =
  161. ROM 8x16 font, 7 = ROM alternate 9x16 font.  Returns
  162. points%, rows%(char. rows on screen - 1), sg% (segment of
  163. char def table), offset% (offset of char. def table).
  164. Used internally by BIGPRINT and BIGPRINTLINE to define
  165. the shape of their giant character representations.
  166.  
  167. Example: CALL getfontinfo(3, points%, rows%, sg&, offset&)
  168.  
  169. -----------------------------------------------------------------------------
  170. * SUB getpath (dv%, pth$)
  171.  
  172. Gets the current path from the root directory to the
  173. current directory for the drive specified in dv%
  174. (0 = Default, 1 = A, Etc).
  175. Returns path in pth$ (including leading backslash).
  176. If error, pth$ will = "".
  177. Example: if current path was C:\PB\SLAM\, pth$
  178. would return \PB\SLAM\.  If path was C:\ then
  179. pth$ would return \.
  180.  
  181. Used internally by choosedir.
  182.  
  183. Example: CALL getpath(0, pth$)
  184.      print "Current Path: "; pth$
  185.  
  186. -----------------------------------------------------------------------------
  187. * SUB hscrollbar (starty%, startx%, length%)
  188.  
  189. Displays a horizontal "scroll bar" on the screen starting at position
  190. starty%/startx%m, of length% characters.  See the demo program for an
  191. example of hscrollbar.  This routine displays the scrollbar only - does
  192. not control scrolling or anything else.  You will have to write the
  193. routines yourself to display the scroll indicator, or wait for a future
  194. version of menulib <grin>.
  195.  
  196. Example: CALL hscrollbar (23, 1, 20)
  197.  
  198. -----------------------------------------------------------------------------
  199. * SUB infobox (msg$())
  200.  
  201. Prints a multi-line message on the screen in a box,
  202. and waits for user to select OK with mouse or ENTER.
  203. This differs from alertbox in that you can display
  204. more than one line of text in the box.
  205.  
  206. Example: DIM msg$(2)
  207.      msg$(1) = "Disk Problem -"
  208.      msg$(2) = "Select OK"
  209.      call infobox(msg$())
  210.  
  211. -----------------------------------------------------------------------------
  212. * SUB inpbox (msg$, ip$, mx%, ll%, ul%)
  213.  
  214. *P*
  215.  
  216. Allows user input in a shadowed screen box.
  217.  
  218. Set msg$ to message, mx% to max length of user input,
  219. ll% = lowest ASCII value permitted for input,
  220. ul% = highest ASCII value permitted for input.
  221.  
  222. The string the user enters is returned in ip$.
  223.  
  224. For example, to input a 3-digit number:
  225.  
  226. msg$="Enter Number:"
  227. mx% = 3
  228. ll% = 48  :' ASCII value of "0"
  229. ul% = 57  :' ASCII value of "9"
  230. CALL inpbox(msg$, ip$, mx%, ll%, ul%)
  231. number% = val(ip$)
  232. print "You Entered ";ip%
  233.  
  234. -----------------------------------------------------------------------------
  235. * SUB menupick (title$, mb$(), help$(), choice%)
  236.  
  237. Allows user to choose from a menu using either
  238. the mouse or the cursor keys.  This is the typical
  239. "vertical" menu displayed in the center of the screen,
  240. with a highlighted bar than can be moved with the
  241. mouse or crsr keys.  Screen is saved upon calling
  242. and automatically restored when done.
  243.  
  244. title$ = title to display on menu
  245. mb$() = text for menu choices
  246. help$() = one-line help message for each menu option
  247. choice% = choice returned by the user (0 if cancelled).
  248.  
  249. Set the cursor position (using LOCATE) to where you want
  250. the upper left corner of the menu before calling this
  251. routine.  help$() must be dimensioned to the same value
  252. as mb$(), but need not be defined.  For ONE helpline for
  253. all menu selections, set help$(1) to the text desired.
  254.  
  255. Example: title$="Select an Option"
  256.      redim mb$(2),help$(2)
  257.      mb$(1)="Option 1":mb$(2)="Option 2"
  258.      help$(1)="Select an option or press ESC to cancel"
  259.      CALL menupick(title$, mb$(), help$(), choice%)
  260.      print "You Picked ";choice%
  261.  
  262. -----------------------------------------------------------------------------
  263. * SUB messagebox (title$, msg$())
  264.  
  265. This routine prints a multi-line message in a box and exits
  266. without delay.  Use for messages you want to remain on the
  267. screen.  Title$ is printed at the top of the box, followed by
  268. a horizontal line, followed by the text in msg$().  Upon exit,
  269. the cursor is located at the position corresponding to the upper
  270. left corner of the box.  You can use this to calculate where to
  271. print further messages inside the box.
  272.  
  273. Example: LOCATE 10, 10
  274.      redim msg$(1:1)
  275.      title$="Loading..."
  276.      msg$(1)="Record #:"
  277.      call messagebox(title$, msg$())
  278.      LOCATE csrlin+3, pos(0)+11
  279.      print "5";  'Print Record #
  280.  
  281. -----------------------------------------------------------------------------
  282. * SUB mgetpos
  283.  
  284. Checks current position of mouse cursor and updates the
  285. corresponding global variables msy% and msx%.
  286.  
  287. Example: CALL mgetpos
  288.      PRINT msy%; msx%
  289.  
  290. -----------------------------------------------------------------------------
  291. * SUB mgetpress (button%, numpresses&, ycc%, xcc%)
  292.  
  293. Checks button indicated in button% (1 = left, 2 = right)
  294. and returns status of buttons in globals lb% and rb%, number
  295. of presses of specified button since last call (in numpresses&),
  296. and Y and X coordinates of mouse cursor the last time the specified
  297. button was pressed (in ycc% and xcc%).
  298.  
  299. Example: CALL mgetpress(button%, numpresses&, ycc%, xcc%)
  300.  
  301. -----------------------------------------------------------------------------
  302. * SUB mgetrelease (button%, numreleases&, ycc%, xcc%)
  303.  
  304. Checks button indicated in button% (1 = left, 2 = right)
  305. and returns status of buttons in globals lb% and rb%, number
  306. of releases of specified button since last call (in numreleases&),
  307. and Y and X coordinates of mouse cursor the last time the specified
  308. button was released (in ycc% and xcc%).
  309.  
  310. Example: CALL mgetrelease(1, numreleases&, ycc%, xcc%)
  311.  
  312. -----------------------------------------------------------------------------
  313. * SUB mousepick (ypos%(), xmin%(), xmax%(), pick%)
  314.  
  315. Checks arrays to see if mouse cursor is at positions specified
  316. in: ypos%(x) = line, xmin%(x) = minimum x pos. on line ypos%(x)
  317. and xmax%(x) = maximum x pos. on line ypos%(x).  If mouse cursor is
  318. at any of these locations (inclusive) AND left button is pressed,
  319. hilights desired area, waits til left button released, then returns
  320. with position number in pick%.
  321.  
  322. This routine requires quite a bit of setting up to use effectively,
  323. but essentially simulates a number of "buttons" on the screen that
  324. can be "pressed" with the mouse.  This routine does not utilize the
  325. keyboard at all, just the mouse, and you must draw the "buttons" on
  326. the screen first before calling the routine.  DIM the arrays to the
  327. number of "buttons" desired, Specify the Y position of each "button"
  328. in ypos%(), the minimum (lowest) X position of each "button" in
  329. xmin%(), and the maximum (highest) X position of each button in
  330. xmax%().
  331.  
  332. Example: DIM ypos%(1:5), xmin%(1:5), xmax%(1:5): '5 "buttons"
  333.      ... draw 5 "buttons" on the screen
  334.      ... (set ypos%(1) thru ypos%(5), same with xmin%()
  335.           and xmax%()
  336.      CALL mousepick(ypos%(), xmin%(), xmax%(), pick%)
  337.      'Check to see if any of the "buttons" were pressed,
  338.       if so, return the button number in pick%.
  339.  
  340. -----------------------------------------------------------------------------
  341. * SUB msetpos
  342.  
  343. Uses global variables msy% and msx% to set a new
  344. position for the mouse cursor.  Change msy% and/or
  345. msx% before calling this routine.
  346.  
  347. Example: msy% = 1: msx% = 1: CALL msetpos
  348.  
  349. -----------------------------------------------------------------------------
  350. * SUB mwaitpress
  351.  
  352. Waits for a Mouse Button to be Pressed.
  353.  
  354. Example: CALL mwaitpress
  355.  
  356. -----------------------------------------------------------------------------
  357. * SUB mybounds (mn%, mx%)
  358.  
  359. Sets minimum and maximum y-axis boundaries for mouse cursor
  360. movement.
  361.  
  362. Example: CALL mybounds(2, 24)
  363.  
  364. -----------------------------------------------------------------------------
  365. * FUNCTION pathstring$
  366.  
  367. Returns current disk/path in a string of the
  368. form C:\QB\EXE\ ... Trailing backslash included.
  369.  
  370. Example: PRINT pathstring$
  371.  
  372. -----------------------------------------------------------------------------
  373. * SUB picklist (lst$(), choice%)
  374.  
  375. *P*
  376.  
  377. Lets the user pick from a long list of options in a window, sizing
  378. and scrolling the window as necessary.  Set lst$() to the text for
  379. the list.  User's choice is returned in choice% (0 if cancelled).
  380.  
  381. Example: DIM lst$(100)
  382.      ... Read in text file to lst$(x)
  383.      CALL picklist(lst$(), choice%)
  384.      PRINT "You Picked ";choice%
  385.  
  386. -----------------------------------------------------------------------------
  387. * SUB printborder
  388.  
  389. Prints a border around the text screen
  390.  
  391. Example: CALL printborder
  392.  
  393. See demo program.
  394.  
  395. -----------------------------------------------------------------------------
  396. * SUB printtitle (title$, starty%, hilight%)
  397.  
  398. Prints a title on the screen, either highlighted
  399. or not highlighted.  See the demo program (title
  400. is printed one line below the menu bar at the top).
  401.  
  402. Example: CALL printtitle("Program.dat", 20, 1)
  403.  
  404. -----------------------------------------------------------------------------
  405. * SUB radiobox (title$, optn$(), choice%)
  406.  
  407. Displays a "radio button box" and lets user select one
  408. option from a list of options.  Set title$ to title of
  409. radio button box, optn$() to the options.  User's choice
  410. is returned in choice%.  Use instead of checkbox if only
  411. one option is possible out of a list of many.
  412. If cancelled (with ESC), choice% = 0.
  413.  
  414. Example: DIM optn$(3)
  415.      optn$(1) = "Option 1"....
  416.      CALL radiobox("Pick One",optn$(), choice%)
  417.      PRINT "You Chose ";choice%
  418.  
  419. -----------------------------------------------------------------------------
  420. * SUB screenedit (x1%, x2%, y1%, y2%, ky$)
  421.  
  422. *P*
  423.  
  424. An advanced routine that allows a user to edit a portion of the
  425. screen, using all the normal cursor keys and editing controls.
  426. This is one routine that's made to be edited and modified, so
  427. be sure to register and get the source code version of MENULIB.
  428.  
  429. x1%, x2% = Minimum and Maximum X Positions allowed (1-80).
  430. y1%, y2% = Minimum and Maximum Y Positions allowed (1-25).
  431. ky$ = keypress returned (if ESC or a scancode key is
  432.       pressed that the routine doesn't recognize).
  433.  
  434. Example: CALL screenedit(1, 80, 1, 25, ky$)
  435.  
  436. -----------------------------------------------------------------------------
  437. * SUB scrolldown (y1%, x1%, y2%, x2%, atrb%, ln%)
  438.  
  439. Scrolls a specified window of the screen down.
  440. y1%,x1% = Upper Left Corner
  441. y2%,x2% = Lower Right Corner
  442. atrb% = Attrib stored in blanked area
  443. ln% = Number of lines to scroll
  444. Note: x/y pos start from 0 instead of 1
  445.  
  446. This routine is a duplicate of mscrolldown in MENUSYS, with
  447. the parameters changed around a bit.  Use whichever you
  448. prefer.
  449.  
  450. Example: CALL scrolldown(1, 1, 25, 80, 7, 1)
  451.  
  452. -----------------------------------------------------------------------------
  453. * SUB scrollup (y1%, x1%, y2%, x2%, atrb%, ln%)
  454.  
  455. Scrolls a specified window of the screen up.
  456. y1%,x1% = Upper Left Corner
  457. y2%,x2% = Lower Right Corner
  458. atrb% = Attrib stored in blanked area
  459. ln% = Number of lines to scroll
  460. Note: x/y pos start from 0 instead of 1
  461.  
  462. This routine is a duplicate of mscrollup in MENUSYS, with
  463. the parameters changed around a bit.  Use whichever you
  464. prefer.
  465.  
  466. Example: CALL scrollup(1, 1, 25, 80, 7, 1)
  467.  
  468. -----------------------------------------------------------------------------
  469. * SUB selectback(ch%)
  470.  
  471. *P*
  472.  
  473. Allows a user to select a background color from a menu, and
  474. returns selection in cl% ... -1 if user cancelled.
  475.  
  476. Example: CALL selectback(ch%)
  477.  
  478. -----------------------------------------------------------------------------
  479. * SUB selectfore (cl%)
  480.  
  481. *P*
  482.  
  483. Allows a user to select a foreground color from a menu, and
  484. returns selection in cl% ... -1 if user cancelled.
  485.  
  486. Example: CALL selectfore(cl%)
  487.  
  488. -----------------------------------------------------------------------------
  489. * SUB setdisk (d%)
  490.  
  491. Sets disk in d% to be default (current drive):
  492. 0 = A, 1 = B, 2 = C, etc.
  493. Returns number of logical drives in system in d%.
  494.  
  495. Example: CALL setdisk(0) :' Set to A:
  496.  
  497. -----------------------------------------------------------------------------
  498. * SUB showtextfile (fi$, clr%)
  499.  
  500. *P*
  501.  
  502. An advanced routine that displays a textfile specified in fi$.
  503. Set clr% to the foreground color to display the text file in
  504. before calling this routine.  This is one routine that's made
  505. to be edited and modified, so be sure to register and get the
  506. source code version of MENULIB.
  507.  
  508. Example: CALL showtextfile("test.dat", 15)
  509.  
  510. -----------------------------------------------------------------------------
  511. * SUB sounds (num%)
  512.  
  513. Plays a sound on the PC's speaker.
  514. Set num% to:
  515.  
  516. 1 = popup
  517. 2 = popdown
  518. 3 = klaxon
  519. 4 = siren
  520. 5 = blip
  521. 6 = 2-tone
  522. 7 = 2-tone triple
  523. 8 = 3-tone
  524. 9 = buzz
  525. 10 = chirp
  526. 11-14 = beep1-4
  527. 15 = 60hz
  528.  
  529. Example: CALL sounds(1)
  530.  
  531. -----------------------------------------------------------------------------
  532. * FUNCTION startofline% (ln%)
  533.  
  534. Finds the position of the START OF TEXT on a specified screen line.
  535. For example, if line 20 of the screen had the line
  536.  
  537.  
  538.     This is a test
  539.  
  540.     ^
  541.     5
  542.  
  543. on it, PRINT startofline%(20) would return 5 (the position of
  544. the first character on the line).  If there is no text on the
  545. specified screen line, a value of 1 will be returned.
  546.  
  547. Example: a% = startofline%(2)
  548.  
  549. -----------------------------------------------------------------------------
  550. * SUB vscrollbar (starty%, startx%, length%)
  551.  
  552. Displays a vertical "scroll bar" on the screen starting at position
  553. starty%/startx%m, of length% characters (vertically).  See the demo
  554. program for an example of vscrollbar.  This routine displays the
  555. scrollbar only - does not control scrolling or anything else.  You
  556. will have to write the routines yourself to display a scroll indicator,
  557. or wait for a future version of menulib <grin>.
  558.  
  559. Example: CALL vscrollbar (1, 78, 15)
  560.  
  561. -----------------------------------------------------------------------------
  562. * SUB yesnobox (msg$, choice%)
  563.  
  564. Prints a one-line message on the screen in a box,
  565. and waits for user to select YES, NO or CANCEL.
  566. Returns 1 (YES), 0 (NO) or -1 (Cancel) in choice%.
  567. Shortest string should be >20.
  568.  
  569. Example: CALL yesnobox("Are you Sure?", choice%)
  570.  
  571. -----------------------------------------------------------------------------
  572.