home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 12 / CD_ASCQ_12_0294.iso / news / 440 / mnusysqb / menulib.ref < prev    next >
Text File  |  1993-09-07  |  20KB  |  496 lines
  1. Menulib for Menusys-QB
  2. Quick Reference Guide
  3.  
  4. (C) Copyright 1993 by Tim Gerchmez
  5. All Rights Reserved.
  6.  
  7. NOTE: Unless otherwise noted, all routines that use
  8.       arrays use an LBOUND of ONE (1).
  9. --------------------------------------------------------------------------------
  10. * sub about
  11.  
  12. Displays a box on the screen giving information about a program -
  13. name, author, etc.  The registered version/source code is necessary
  14. to modify/configure this routine to display your name and programname.
  15. This routine calls INFOBOX.
  16. --------------------------------------------------------------------------------
  17. * sub alertbox (message$)
  18.  
  19. Prints a one-line alert message on the screen and
  20. waits for user to select OK with mouse or ENTER.
  21. See MLIBDEMO.BAS for example.
  22.  
  23. Example: message$ = "Testing" : CALL alertbox(message$)
  24. --------------------------------------------------------------------------------
  25. * sub background (ch%)
  26.  
  27. Fills the screen with a special character, creating a
  28. background.  Uses colors in clr%, bckg%.
  29. Set chr% = 0 for black background, 1 for dark background, 2 for medium,
  30. 3 for light, 4 for pure.  See MLIBDEMO.BAS for example.
  31.  
  32. Example: CALL background(0)
  33. --------------------------------------------------------------------------------
  34. * sub bigprint (ch$, u$)
  35.  
  36. Prints a giant representation of the ASCII value in ch$.
  37. Uses the character in u$ to represent the "dots" for the big
  38. character.  Cursor Position is restored afterward.  Characters
  39. are size 8 X 8 regular characters.
  40.  
  41. Example: ch$ = "T" : u$ = "." : CALL bigprint(ch$, u$)
  42. --------------------------------------------------------------------------------
  43. * sub bigprintline (ln$, u$)
  44.  
  45. Print an entire line of characters in ln$ in giant size print.
  46. Uses the character in u$ to print the giant "pixels."
  47. Maximum: 10 characters in ln$, 3 lines per screen.
  48. Ready to print another line after routine is called .. begins
  49. on the line the cursor is currently on.
  50. One screen will hold 3 lines of 10 characters.
  51. This routine calls BIGPRINT.  See MLIBDEMO.BAS for example.
  52.  
  53. Example: LOCATE 1, 1 : CALL bigprintline("Test1234", ".")
  54. --------------------------------------------------------------------------------
  55. * sub checkbox (title$, optn$(), optn%())
  56.  
  57. Displays a list of selections and lets a user "check off" or
  58. select them using the mouse or keyboard.  Title$ should contain
  59. the title for the box, optn$() will contain the option names,
  60. and optn%(x) will be returned as 0 for not selected, or 1 for
  61. selected.  Locate cursor to upper-left corner position of box
  62. desired before calling. See MLIBDEMO.BAS for example.
  63.  
  64. Example: title$ = "Select any/all"
  65.          DIM optn$(1 TO 3), optn%(1 TO 3)
  66.          optn$(1) = "Option 1"
  67.          optn$(2) = "Option 2"
  68.          optn$(3) = "Option 3"
  69.          CALL checkbox(title$, optn$(), optn%())
  70. --------------------------------------------------------------------------------
  71. * sub choosebox (msg$(), choice%)
  72.  
  73. Prints a multi-line message on the screen in a box,
  74. and waits for user to select OK or CANCEL.
  75. Returns 0 (OK) or 1 (Cancelled).
  76. Shortest string should be >20.
  77. See MLIBDEMO.BAS for example.
  78.  
  79. Example: DIM msg$(1 TO 2)
  80.          msg$(1) = "Choice1"
  81.          msg$(2) = "Choice2"
  82.          CALL choosebox(msg$(), choice%)
  83.          PRINT "You Chose "; choice%
  84. --------------------------------------------------------------------------------
  85. * sub choosedir (dr$, ch$)
  86.  
  87. Lets the user choose an entry from a subdirectory using the
  88. mouse/cursor keys (see MLIBDEMO.BAS).  Upon calling, dr$ should 
  89. contain the filespec to be found (*.* for all), and upon
  90. return, ch$ will contain the directory entry the user selected.
  91. If ch$ = "", the user aborted the routine.
  92. See MLIBDEMO.BAS for example.
  93.  
  94. Example: dr$ = "*.*"
  95.          CALL choosedir(dr$, ch$)
  96.          PRINT "You Chose "; ch$
  97. --------------------------------------------------------------------------------
  98. * sub clearline (ln%)
  99.  
  100. Clears a selected screenline, including position 80, without
  101. scrolling the screen.
  102.  
  103. Example: CALL clearline (25)
  104.  
  105. --------------------------------------------------------------------------------
  106. * function endofline% (ln%)
  107.  
  108. Returns the position (column) of the end of a line of text.
  109. Specify the screen line to check in ln% (1-25) before calling.
  110. Upon return, endofline% will contain the position of the last
  111. character on the specified screen line, plus one (the next
  112. available blank on the screen line).  Note that this is a
  113. Function, not a Sub.
  114.  
  115. Example: e% = endofline%(10)
  116.          LOCATE 10, e%
  117.          PRINT "...more text"
  118. --------------------------------------------------------------------------------
  119. * sub getdirectory (fi$, atype%, dir$(), attrib%())
  120.  
  121. Gets the directory specified in fi$ (with the attributes to be
  122. searched for specified in atype%) and puts it into a string
  123. array (dir$()), and the attributes for each file in attrib%()).
  124. If no entries of the specified type are found, the routine returns
  125. with fi$="".  DIM dir$ and attrib% to any number (such as 1) before
  126. calling, but make sure to use $DYNAMIC, as arrays are re-dimensioned
  127. to correct size to hold all directory entries.  The values in attrib%
  128. are returned as follows (use AND to extract the bits):
  129.  
  130. Zero = "Ordinary" files only (0)
  131. Bit 0 = Read Only (1)
  132. Bit 1 = Hidden File (2)
  133. Bit 2 = System File (4)
  134. Bit 4 = Subdirectory (16)
  135. Bit 5 = Archive (32) - [0 or 32 = "Ordinary" file]
  136.  
  137. Example: if attrib%(5) AND 4 then print "System File"
  138. Example: If attrib%(2) = 16 then print "Subdirectory"
  139. Example: If attrib%(1) = 0 or attrib%(1) = 32 then print "Normal File"
  140.  
  141. Set atype% to the desired attributes to be searched for (as defined
  142. above) before calling.  For "Normal" files only, set atype% to zero.
  143. GETDIRECTORY is called by CHOOSEDIR.
  144.  
  145. Example: DIM dir$(1), attrib%(1)
  146.          atype% = 0 : fi$ = "*.*"
  147.          CALL getdirectory(fi$, atype%, dir$(), attrib%())
  148. --------------------------------------------------------------------------------
  149. * sub getdisk (d%)
  150.  
  151. Returns drive code of current or default drive.
  152. 0 = A, 1 = B, 2 = C, Etc.
  153.  
  154. Example: CALL getdisk(d%)
  155.          PRINT "Current disk is ";chr$(65 + d%)
  156. --------------------------------------------------------------------------------
  157. * sub getfontinfo (code%, points%, rows%, sg, offset)
  158.  
  159. EGA, MCGA, VGA
  160. Returns a pointer to a font's character definition table, and
  161. the points (bytes per character) and rows for that font.
  162. Call with code% set to one of the following values:
  163. 0 = INT 1fh contents, 1 = INT 43h contents, 2 = ROM 8x14
  164. font, 3 = ROM 8x8 font (chars 00h-7fh), 4 = ROM 8x8
  165. font (chars 80h-ffh), 5 = ROM alternate 9x14 font, 6 =
  166. ROM 8x16 font, 7 = ROM alternate 9x16 font.  Returns
  167. points%, rows%(char. rows on screen - 1), sg% (segment of
  168. char def table), offset% (offset of char. def table).
  169. GETFONTINFO is called by BIGPRINT.
  170.  
  171. Example: code% = 3 : CALL getfontinfo(code%, points%, rows%, sg, offset)
  172. --------------------------------------------------------------------------------
  173. * sub getpath (dv%, pth$)
  174.  
  175. Gets current path from root to current directory for
  176. the drive specified in dv% (0 = Default, 1 = A, Etc).
  177. Returns path in pth$ (including leading backslash).
  178. If error, pth$ will = "".
  179. Example: if current path was C:\QB\SLAM\, pth$
  180. would return \QB\SLAM\.  If path was C:\ then
  181. pth$ would return \.
  182.  
  183. Example: CALL getpath(0, pth$)
  184.          Print "Current Path: "; pth$
  185. --------------------------------------------------------------------------------
  186. * sub hscrollbar (starty%, startx%, length%)
  187.  
  188. Displays a horizontal "scroll bar" on the screen.
  189. Specify the start Y and X position of the bar, and
  190. the length in characters.  This routine displays a
  191. scroll bar only.  It does not read the mouse or move
  192. an indicator on the scroll bar.  See MNSDEMO.BAS for
  193. example usage.
  194.  
  195. Example: CALL hscrollbar(25, 5, 70)
  196. --------------------------------------------------------------------------------
  197. * sub infobox (msg$())
  198.  
  199. Prints a multi-line message on the screen in a box,
  200. and waits for user to select OK with mouse or ENTER.
  201. DIM msg$(1 to numofmsg%).  See MLIBDEMO.BAS for example.
  202.  
  203. Example: DIM msg$(1 to 3)
  204.          msg$(1) = "This is the first line"
  205.          msg$(2) = "of this message which is"
  206.          msg$(3) = "being displayed."
  207.          CALL infobox(msg$())
  208. --------------------------------------------------------------------------------
  209. * sub inputbox (message$, inp$, max%, ll%, ul%)
  210.  
  211. Allows user input in a shadowed screen box.
  212. Set message$ to message, max% to max length of user input,
  213. ll% = lowest char allowed, ul% = highest char allowed.
  214. User input is returned in inp$, and is used as "default"
  215. input the next time the routine is called. See MLIBDEMO.BAS
  216. for example usage of this routine.
  217.  
  218. Example: message$ = "Enter your name: "
  219.          max% = 10 : ll% = 0: ul% = 255
  220.          CALL inputbox(message$, inp$, max%, ll%, ul%)
  221. --------------------------------------------------------------------------------
  222. * sub menupick (title$, mb$(), help$(), choice%)
  223.  
  224. Allows user to choose from a menu using either
  225. the mouse or the cursor keys.  Dim mb$() and help$()
  226. to the number of menu items desired before calling.
  227. Upon return, choice% will contain the user's choice
  228. (zero for abort).  Set help$(x) to help for each menu
  229. item (one line only), or leave blank.  See MLIBDEMO.BAS
  230. for example usage of this routine.
  231.  
  232. Example: DIM mb$(1 to 2), help$(1 to 2)
  233.          title$ = "Select one"
  234.          mb$(1) = "One" : mb$(2) = "Two"
  235.          help$(1) = "Help for Option One"
  236.          help$(2) = "Help for Option Two"
  237.          CALL menupick(title$, mb$(), help$(), choice%)
  238.          PRINT "You picked "; choice%
  239. --------------------------------------------------------------------------------
  240. * sub messagebox (title$, msg$())
  241.  
  242. This routine prints a multi-line message on the
  243. screen and exits, without any delay.  Use it for
  244. messages that you don't need to be erased.  See
  245. MLIBDEMO.BAS for example usage of this routine.
  246.  
  247. Example: DIM msg$(1 to 2)
  248.          title$ = "Message"
  249.          msg$(1) = "This is a test of the"
  250.          msg$(2) = "Emergency Broadcast System"
  251.          CALL messagebox(title$, msg$())
  252. --------------------------------------------------------------------------------
  253. * sub mgetpos
  254.  
  255. Checks current position of mouse cursor and updates the
  256. corresponding global variables msy% and msx%.  This will
  257. return the current position of the mouse cursor on the 
  258. text screen (if mouse is active and displayed).
  259.  
  260. Example: CALL mgetpos
  261.          PRINT msy% ; msx%
  262.  
  263. --------------------------------------------------------------------------------
  264. * sub mgetpress (button%, numpresses!, ycc%, xcc%)
  265.  
  266. Checks button indicated in button% (1 = left, 2 = right)
  267. and returns status of buttons in globals lb% and rb%, number
  268. of presses of specified button since last call (in numpresses!),
  269. and Y and X coordinates of mouse cursor the last time the specified
  270. button was pressed (in ycc% and xcc%).
  271.  
  272. Example: CALL mgetpress(1, numpresses!, ycc%, xcc%)
  273.          IF lb% = 1 THEN PRINT "Left Button Pressed"
  274.          IF rb% = 1 THEN PRINT "Right Button Pressed"
  275.          PRINT "Left button pressed "; numpresses!; "Times"
  276.          PRINT "X = "; xcc%; "Y = "; ycc%
  277. --------------------------------------------------------------------------------
  278. * sub mgetrelease (button%, numreleases!, ycc%, xcc%)
  279.  
  280. Checks button indicated in button% (1 = left, 2 = right)
  281. and returns status of buttons in globals lb% and rb%, number
  282. of releases of specified button since last call (in numreleases!),
  283. and Y and X coordinates of mouse cursor the last time the specified
  284. button was released (in ycc% and xcc%).
  285.  
  286. Example: CALL mgetrelease(1, numreleases!, ycc%, xcc%)
  287.          IF lb% = 1 THEN PRINT "Left Button Pressed"
  288.          IF rb% = 1 THEN PRINT "Right Button Pressed"
  289.          PRINT "Left button released "; numreleases!; "Times"
  290.          PRINT "X = "; xcc%; "Y = "; ycc%
  291. --------------------------------------------------------------------------------
  292. * sub mousepick (ypos%(), xmin%(), xmax%(), pick%)
  293.  
  294. Checks to see if mouse cursor is at positions specified
  295. in: ypos%() = line, xmin%() = minimum x pos. on line ypos%,
  296. xmax%() = maximum x pos. on line ypos%.  If mouse cursor is
  297. at any of these locations AND left button is pressed, hilights
  298. desired area, waits til left button released, then returns with
  299. position number in pick% (whew).  This allows you to simulate
  300. "buttons" at various places on the screen, letting the user 
  301. "press" the buttons with the mouse.  See MLIBDEMO.BAS for example
  302. of how to use this routine.
  303.  
  304. --------------------------------------------------------------------------------
  305. * sub msetpos
  306.  
  307. Uses global variables msy% and msx% to set a new
  308. position for the mouse cursor.  Change msy% and/or
  309. msx% before calling this routine.
  310.  
  311. Example: msy% = 1 : msx% = 1
  312.          CALL msetpos
  313. --------------------------------------------------------------------------------
  314. * sub mwaitpress
  315.  
  316. Waits for a Mouse Button to be Pressed.
  317.  
  318. Example: CALL mwaitpress
  319. --------------------------------------------------------------------------------
  320. * sub mybounds (min%, max%)
  321.  
  322. Sets minimum and maximum y-axis boundaries for mouse cursor.
  323.  
  324. Example: min% = 2 : max% = 24
  325.          CALL mybounds(min%, max%)
  326. --------------------------------------------------------------------------------
  327. * function pathstring$
  328.  
  329. Returns current disk/path in a string of the
  330. form C:\QB\EXE\ ... Trailing backslash included.
  331. Note that this is a Function, not a Sub.
  332.  
  333. Example: PRINT pathstring$
  334. --------------------------------------------------------------------------------
  335. * sub picklist (list$(), choice%)
  336.  
  337. Lets the user pick from a long list of options.
  338. The list should be contained in list$() before calling.
  339. Upon return, the user's choice will be in choice%
  340. (zero if aborted).  See MLIBDEMO.BAS for example.
  341.  
  342. Example: DIM list$(1 to 100)
  343.          FOR x% = 1 TO 100
  344.          READ list$(x%) : NEXT x%
  345.          CALL picklist(list$(), choice%)
  346.          PRINT "You picked "; choice%
  347. --------------------------------------------------------------------------------
  348. * sub printborder
  349.  
  350. Prints a "border" around the screen.  Used in MNSDEMO to
  351. display the single border around the screen.
  352.  
  353. Example: CALL printborder
  354. --------------------------------------------------------------------------------
  355. * sub printtitle (title$, starty%, hilight%)
  356.  
  357. Prints the "title" of a program on the screen, similar to the
  358. way QuickBASIC does on the second screenline, centered.  Set
  359. title$ to the desired title, starty% to the desired Y position
  360. of the title on the screen, and hilight% to 1 for yes, 0 no
  361. highlighted (reversed) title.  See MNSDEMO.BAS for an example.
  362.  
  363. Example: CALL printtitle("MENULIB.REF", 2, 1)
  364. --------------------------------------------------------------------------------
  365. * sub radiobox (title$, optn$(), choice%)
  366.  
  367. Allows user to select a menu option using a "radio button"
  368. type interface.  User selects "OK" or "CANCEL" to end the
  369. routine.  If cancelled, choice% = 0, otherwise choice% will  
  370. contain the user's choice.  Locate cursor to upper left corner 
  371. of box desired before calling.  See MLIBDEMO.BAS for example.
  372.  
  373. Example: title$ = "Select One"
  374.          DIM optn$(3)
  375.          optn$(1) = "Option 1"
  376.          optn$(2) = "Option 2"
  377.          optn$(3) = "Option 3"
  378.          LOCATE 1,1
  379.          CALL radiobox(title$, optn$(), choice%)
  380.          PRINT "You chose ";choice%
  381. --------------------------------------------------------------------------------
  382. * sub screenedit (x1%, x2%, y1%, y2%, key$) static
  383.  
  384. An advanced routine that allows a user to edit a portion of the screen
  385. using all the normal cursor keys and editing controls.  Used by MNSDEMO
  386. to allow editing of the screen.  key$ will return keypresses not
  387. recognized by the routine (ESC if user pressed Esc.)
  388.  
  389. x1%, x2% = Minimum and Maximum X Positions allowed (1-80).
  390. y1%, y2% = Minimum and Maximum Y Positions allowed (1-25).
  391.  
  392. Example: CALL screenedit (1, 80, 1, 25, key$)
  393. --------------------------------------------------------------------------------
  394. * sub scrolldown (y1%, x1%, y2%, x2%, attrib%, ln%)
  395.  
  396. Scrolls a specified window of the screen down
  397. y1%,x1% = Upper Left Corner
  398. y2%,x2% = Lower Right Corner
  399. Attrib% = Attrib stored in blanked area
  400. ln% = Number of lines to scroll
  401. Note: x/y pos start from 0 instead of 1
  402.  
  403. Example: CALL scrolldown(1, 1, 25, 80, 7, 1)
  404. --------------------------------------------------------------------------------
  405. * sub scrollup (y1%, x1%, y2%, x2%, attrib%, ln%)
  406.  
  407. Scrolls a specified window of the screen up
  408. y1%,x1% = Upper Left Corner
  409. y2%,x2% = Lower Right Corner
  410. Attrib% = Attrib stored in blanked area
  411. ln% = Number of lines to scroll
  412. Note: x/y pos start from 0 instead of 1
  413.  
  414. Example: CALL scrollup(1, 1, 25, 80, 7, 1)
  415. --------------------------------------------------------------------------------
  416. * sub selectback (cl%)
  417.  
  418. Allows the user to select a background color from a menu
  419. and returns it in cl% (-1 if user cancelled the routine).
  420. This routine calls MENUPICK.  See MLIBDEMO.BAS for example.
  421.  
  422. Example: CALL selectback(cl%)
  423. --------------------------------------------------------------------------------
  424. * sub selectfore (cl%)
  425.  
  426. Allows the user to select a foreground color from a menu
  427. and returns it in cl% (-1 if user cancelled the routine).
  428. This routine calls MENUPICK.  See MLIBDEMO.BAS for example.
  429.  
  430. Example: CALL selectfore(cl%)
  431. --------------------------------------------------------------------------------
  432. * sub setdisk (d%)
  433.  
  434. Sets disk in d% to be default (current drive):
  435. 0 = A, 1 = B, 2 = C, etc.
  436. Returns number of logical drives in system in d%.
  437.  
  438. Example: CALL setdisk(0)
  439. --------------------------------------------------------------------------------
  440. * sub showtextfile (fi$, clr%)
  441.  
  442. Displays a text file (filename in fi$) using the foreground
  443. color in clr%.  See MLIBDEMO.BAS for example.
  444.  
  445. Example: CALL showtextfile("file.txt", 15)
  446. --------------------------------------------------------------------------------
  447. * sub sounds (num%)
  448.  
  449. Makes a brief sound through the PC's speaker.
  450. Call with num% set to:
  451.  
  452. 1 = popup
  453. 2 = popdown
  454. 3 = klaxon
  455. 4 = siren
  456. 5 = blip
  457. 6 = 2-tone
  458. 7 = 2-tone triple
  459. 8 = 3-tone
  460. 9 = buzz
  461. 10 = chirp
  462. 11-14 = beep1-4
  463. 15 = 60hz
  464.  
  465. Example: CALL sounds(1)
  466. --------------------------------------------------------------------------------
  467. * function startofline% (ln%)
  468.  
  469. Returns the start of text on a particular screen line.
  470. Call with ln% = the line you wish to check.  If there is
  471. no text on a particular screen line, the routine will return
  472. 1, otherwise returns the position of the first text (non-space)
  473. character on the line.  Note that this is a FUNCTION and not 
  474. a SUB.
  475.  
  476. Example: s% = startofline%(10)
  477. --------------------------------------------------------------------------------
  478. * sub vscrollbar (starty%, startx%, length%)
  479.  
  480. Displays a vertical scrollbar on the screen at the indicated
  481. start Y and X positions, of length length%.  Used by MNSDEMO
  482. to display the vertical scroll bar.
  483.  
  484. Example: CALL vscrollbar(1, 1, 15)
  485. --------------------------------------------------------------------------------
  486. * sub yesnobox (msg$, choice%)
  487.  
  488. Prints a one-line message on the screen in a box,
  489. and waits for user to select YES, NO or CANCEL.
  490. Returns 1 (YES), 0 (NO) or -1 (Cancel).
  491. Shortest string should be >20.
  492. See MLIBDEMO.BAS for example.
  493.  
  494. Example: CALL yesnobox("Are you sure you want to quit?", choice%)
  495. --------------------------------------------------------------------------------
  496.