Menulib for Menusys Add-On Library Routines for Power BASIC 3.0 Version 1.0A (C) Copyright 1993 by Tim Gerchmez ---------------------------------- ** SUB/Function Reference ** Note: Especially powerful/high-level routines are marked with "*P*" to distinguish them from the rest. Total Routines: 41 ------------------------------------------------------------------------------ * SUB about Displays the title and author of the current program in a window and waits for the user to press ENTER or click "OK" with the mouse. Source code version is required to modify this routine. Example: CALL about ----------------------------------------------------------------------------- * SUB alertbox (msg$) Prints a one-line alert message on the screen and waits for user to select OK with mouse or ENTER. Example: CALL alertbox("File Not Found") ----------------------------------------------------------------------------- * SUB background (ch%) Fills the screen with a special character, creating a background. Uses colors in global variables clr% and bckg%. Set ch% = 0 for black background, 1 for dark background, 2 for medium, 3 for light, 4 for pure. Example: CALL background(2) ----------------------------------------------------------------------------- * SUB bigprint (ch$, u$) Prints a giant representation of the ASCII value in ch$. Uses the character in u$ to represent the "dots" for the big character. Cursor Position is restored afterward. Example: CALL bigprint ("A",chr$(219)) ------------------------------------------------------------------------------ * SUB bigprintline (ln$, u$) *P* Print an entire line of characters in ln$ in giant size print. Uses the character in u$ to print the giant "pixels." Maximum: 10 characters in ln$ (80-col. screen). Ready to print another line after routine is called .. begins on the line the cursor is currently on. Add 8 to the current Y position for the next "screen line". One screen will hold about 3 lines of 10 giant characters. Example: LOCATE 1, 1 CALL bigprintline("Testing123",chr$(219)) ----------------------------------------------------------------------------- * SUB checkbox (title$, optn$(), optn%()) Lets the user pick from a list of options with the mouse cursor or the keyboard. More than one option can be selected. Set title$ to the title to display on the list, and DIM optn$() to the text for the list of options. Upon return, optn%(x) will contain either a zero (user didn't select it) or a one (user selected it). Subsequent calls to checkbox will retain the user's choices in optn% if the array isn't erased or redimensioned. Example: title$="Select Options:":REDIM optn$(1:3), optn%(1:3) optn$(1)="Option 1":optn$(2)="Option 2":optn$(3)="Option 3" CALL checkbox(title$, optn$(), optn%()) ----------------------------------------------------------------------------- * SUB choosebox (msg$(), choice%) Prints a multi-line message on the screen in a box, and waits for user to select OK or CANCEL. Returns 0 (OK) or 1 (Cancel) Shortest string in msg$(x) should be >20. Returns with user's choice in choice%: 0 = OK 1 = Cancel Example: DIM msg$(1:2) msg$(1)="Would you like to" msg$(2)="Continue the current operation?" CALL choosebox(msg$(), choice%) IF choice% = 1 then print "Nope!" : end ----------------------------------------------------------------------------- * SUB choosedir (d$, ch$) *P* Lets a user select from a directory entry on the screen. Includes ability to switch to new drives/subdirectories. Call with d$ = directory mask (normally "*.*"). Routine returns with user's choice of filename in ch$ (or null string if cancelled). Example: CALL choosedir("*.*",ch$) ----------------------------------------------------------------------------- * SUB clearline (ln%) Clears a selected screenline, including position 80, without scrolling the screen. Also preserves the current cursor position and turns off the mouse cursor if necessary. Example: CALL clearline (25) ----------------------------------------------------------------------------- * FUNCTION endofline% (ln%) Finds the position of the END OF TEXT on a specified screen line. For example, if line 20 of the screen had the line This is a test ^ 15 on it, PRINT endofline%(20) would return 15 (the last character plus one, indicating the blank space following the line of text). If there is no text on the specified screen line, a value of 80 will be returned. Example: a% = endofline%(2) ----------------------------------------------------------------------------- * SUB getdisk (d%) Returns drive code of current or default drive. 0 = A, 1 = B, 2 = C, Etc. in d%. Example: CALL getdisk(d%) ----------------------------------------------------------------------------- * SUB getfontinfo (code%, points%, rows%, sg&, offset&) EGA, MCGA, VGA Returns a pointer to a font's character definition table, and the points (bytes per character) and rows for that font. Call with code% set to one of the following values: 0 = INT 1fh contents, 1 = INT 43h contents, 2 = ROM 8x14 font, 3 = ROM 8x8 font (chars 00h-7fh), 4 = ROM 8x8 font (chars 80h-ffh), 5 = ROM alternate 9x14 font, 6 = ROM 8x16 font, 7 = ROM alternate 9x16 font. Returns points%, rows%(char. rows on screen - 1), sg% (segment of char def table), offset% (offset of char. def table). Used internally by BIGPRINT and BIGPRINTLINE to define the shape of their giant character representations. Example: CALL getfontinfo(3, points%, rows%, sg&, offset&) ----------------------------------------------------------------------------- * SUB getpath (dv%, pth$) Gets the current path from the root directory to the current directory for the drive specified in dv% (0 = Default, 1 = A, Etc). Returns path in pth$ (including leading backslash). If error, pth$ will = "". Example: if current path was C:\PB\SLAM\, pth$ would return \PB\SLAM\. If path was C:\ then pth$ would return \. Used internally by choosedir. Example: CALL getpath(0, pth$) print "Current Path: "; pth$ ----------------------------------------------------------------------------- * SUB hscrollbar (starty%, startx%, length%) Displays a horizontal "scroll bar" on the screen starting at position starty%/startx%m, of length% characters. See the demo program for an example of hscrollbar. This routine displays the scrollbar only - does not control scrolling or anything else. You will have to write the routines yourself to display the scroll indicator, or wait for a future version of menulib . Example: CALL hscrollbar (23, 1, 20) ----------------------------------------------------------------------------- * SUB infobox (msg$()) Prints a multi-line message on the screen in a box, and waits for user to select OK with mouse or ENTER. This differs from alertbox in that you can display more than one line of text in the box. Example: DIM msg$(2) msg$(1) = "Disk Problem -" msg$(2) = "Select OK" call infobox(msg$()) ----------------------------------------------------------------------------- * SUB inpbox (msg$, ip$, mx%, ll%, ul%) *P* Allows user input in a shadowed screen box. Set msg$ to message, mx% to max length of user input, ll% = lowest ASCII value permitted for input, ul% = highest ASCII value permitted for input. The string the user enters is returned in ip$. For example, to input a 3-digit number: msg$="Enter Number:" mx% = 3 ll% = 48 :' ASCII value of "0" ul% = 57 :' ASCII value of "9" CALL inpbox(msg$, ip$, mx%, ll%, ul%) number% = val(ip$) print "You Entered ";ip% ----------------------------------------------------------------------------- * SUB menupick (title$, mb$(), help$(), choice%) Allows user to choose from a menu using either the mouse or the cursor keys. This is the typical "vertical" menu displayed in the center of the screen, with a highlighted bar than can be moved with the mouse or crsr keys. Screen is saved upon calling and automatically restored when done. title$ = title to display on menu mb$() = text for menu choices help$() = one-line help message for each menu option choice% = choice returned by the user (0 if cancelled). Set the cursor position (using LOCATE) to where you want the upper left corner of the menu before calling this routine. help$() must be dimensioned to the same value as mb$(), but need not be defined. For ONE helpline for all menu selections, set help$(1) to the text desired. Example: title$="Select an Option" redim mb$(2),help$(2) mb$(1)="Option 1":mb$(2)="Option 2" help$(1)="Select an option or press ESC to cancel" CALL menupick(title$, mb$(), help$(), choice%) print "You Picked ";choice% ----------------------------------------------------------------------------- * SUB messagebox (title$, msg$()) This routine prints a multi-line message in a box and exits without delay. Use for messages you want to remain on the screen. Title$ is printed at the top of the box, followed by a horizontal line, followed by the text in msg$(). Upon exit, the cursor is located at the position corresponding to the upper left corner of the box. You can use this to calculate where to print further messages inside the box. Example: LOCATE 10, 10 redim msg$(1:1) title$="Loading..." msg$(1)="Record #:" call messagebox(title$, msg$()) LOCATE csrlin+3, pos(0)+11 print "5"; 'Print Record # ----------------------------------------------------------------------------- * SUB mgetpos Checks current position of mouse cursor and updates the corresponding global variables msy% and msx%. Example: CALL mgetpos PRINT msy%; msx% ----------------------------------------------------------------------------- * SUB mgetpress (button%, numpresses&, ycc%, xcc%) Checks button indicated in button% (1 = left, 2 = right) and returns status of buttons in globals lb% and rb%, number of presses of specified button since last call (in numpresses&), and Y and X coordinates of mouse cursor the last time the specified button was pressed (in ycc% and xcc%). Example: CALL mgetpress(button%, numpresses&, ycc%, xcc%) ----------------------------------------------------------------------------- * SUB mgetrelease (button%, numreleases&, ycc%, xcc%) Checks button indicated in button% (1 = left, 2 = right) and returns status of buttons in globals lb% and rb%, number of releases of specified button since last call (in numreleases&), and Y and X coordinates of mouse cursor the last time the specified button was released (in ycc% and xcc%). Example: CALL mgetrelease(1, numreleases&, ycc%, xcc%) ----------------------------------------------------------------------------- * SUB mousepick (ypos%(), xmin%(), xmax%(), pick%) Checks arrays to see if mouse cursor is at positions specified in: ypos%(x) = line, xmin%(x) = minimum x pos. on line ypos%(x) and xmax%(x) = maximum x pos. on line ypos%(x). If mouse cursor is at any of these locations (inclusive) AND left button is pressed, hilights desired area, waits til left button released, then returns with position number in pick%. This routine requires quite a bit of setting up to use effectively, but essentially simulates a number of "buttons" on the screen that can be "pressed" with the mouse. This routine does not utilize the keyboard at all, just the mouse, and you must draw the "buttons" on the screen first before calling the routine. DIM the arrays to the number of "buttons" desired, Specify the Y position of each "button" in ypos%(), the minimum (lowest) X position of each "button" in xmin%(), and the maximum (highest) X position of each button in xmax%(). Example: DIM ypos%(1:5), xmin%(1:5), xmax%(1:5): '5 "buttons" ... draw 5 "buttons" on the screen ... (set ypos%(1) thru ypos%(5), same with xmin%() and xmax%() CALL mousepick(ypos%(), xmin%(), xmax%(), pick%) 'Check to see if any of the "buttons" were pressed, if so, return the button number in pick%. ----------------------------------------------------------------------------- * SUB msetpos Uses global variables msy% and msx% to set a new position for the mouse cursor. Change msy% and/or msx% before calling this routine. Example: msy% = 1: msx% = 1: CALL msetpos ----------------------------------------------------------------------------- * SUB mwaitpress Waits for a Mouse Button to be Pressed. Example: CALL mwaitpress ----------------------------------------------------------------------------- * SUB mybounds (mn%, mx%) Sets minimum and maximum y-axis boundaries for mouse cursor movement. Example: CALL mybounds(2, 24) ----------------------------------------------------------------------------- * FUNCTION pathstring$ Returns current disk/path in a string of the form C:\QB\EXE\ ... Trailing backslash included. Example: PRINT pathstring$ ----------------------------------------------------------------------------- * SUB picklist (lst$(), choice%) *P* Lets the user pick from a long list of options in a window, sizing and scrolling the window as necessary. Set lst$() to the text for the list. User's choice is returned in choice% (0 if cancelled). Example: DIM lst$(100) ... Read in text file to lst$(x) CALL picklist(lst$(), choice%) PRINT "You Picked ";choice% ----------------------------------------------------------------------------- * SUB printborder Prints a border around the text screen Example: CALL printborder See demo program. ----------------------------------------------------------------------------- * SUB printtitle (title$, starty%, hilight%) Prints a title on the screen, either highlighted or not highlighted. See the demo program (title is printed one line below the menu bar at the top). Example: CALL printtitle("Program.dat", 20, 1) ----------------------------------------------------------------------------- * SUB radiobox (title$, optn$(), choice%) Displays a "radio button box" and lets user select one option from a list of options. Set title$ to title of radio button box, optn$() to the options. User's choice is returned in choice%. Use instead of checkbox if only one option is possible out of a list of many. If cancelled (with ESC), choice% = 0. Example: DIM optn$(3) optn$(1) = "Option 1".... CALL radiobox("Pick One",optn$(), choice%) PRINT "You Chose ";choice% ----------------------------------------------------------------------------- * SUB screenedit (x1%, x2%, y1%, y2%, ky$) *P* An advanced routine that allows a user to edit a portion of the screen, using all the normal cursor keys and editing controls. This is one routine that's made to be edited and modified, so be sure to register and get the source code version of MENULIB. x1%, x2% = Minimum and Maximum X Positions allowed (1-80). y1%, y2% = Minimum and Maximum Y Positions allowed (1-25). ky$ = keypress returned (if ESC or a scancode key is pressed that the routine doesn't recognize). Example: CALL screenedit(1, 80, 1, 25, ky$) ----------------------------------------------------------------------------- * SUB scrolldown (y1%, x1%, y2%, x2%, atrb%, ln%) Scrolls a specified window of the screen down. y1%,x1% = Upper Left Corner y2%,x2% = Lower Right Corner atrb% = Attrib stored in blanked area ln% = Number of lines to scroll Note: x/y pos start from 0 instead of 1 This routine is a duplicate of mscrolldown in MENUSYS, with the parameters changed around a bit. Use whichever you prefer. Example: CALL scrolldown(1, 1, 25, 80, 7, 1) ----------------------------------------------------------------------------- * SUB scrollup (y1%, x1%, y2%, x2%, atrb%, ln%) Scrolls a specified window of the screen up. y1%,x1% = Upper Left Corner y2%,x2% = Lower Right Corner atrb% = Attrib stored in blanked area ln% = Number of lines to scroll Note: x/y pos start from 0 instead of 1 This routine is a duplicate of mscrollup in MENUSYS, with the parameters changed around a bit. Use whichever you prefer. Example: CALL scrollup(1, 1, 25, 80, 7, 1) ----------------------------------------------------------------------------- * SUB selectback(ch%) *P* Allows a user to select a background color from a menu, and returns selection in cl% ... -1 if user cancelled. Example: CALL selectback(ch%) ----------------------------------------------------------------------------- * SUB selectfore (cl%) *P* Allows a user to select a foreground color from a menu, and returns selection in cl% ... -1 if user cancelled. Example: CALL selectfore(cl%) ----------------------------------------------------------------------------- * SUB setdisk (d%) Sets disk in d% to be default (current drive): 0 = A, 1 = B, 2 = C, etc. Returns number of logical drives in system in d%. Example: CALL setdisk(0) :' Set to A: ----------------------------------------------------------------------------- * SUB showtextfile (fi$, clr%) *P* An advanced routine that displays a textfile specified in fi$. Set clr% to the foreground color to display the text file in before calling this routine. This is one routine that's made to be edited and modified, so be sure to register and get the source code version of MENULIB. Example: CALL showtextfile("test.dat", 15) ----------------------------------------------------------------------------- * SUB sounds (num%) Plays a sound on the PC's speaker. Set num% to: 1 = popup 2 = popdown 3 = klaxon 4 = siren 5 = blip 6 = 2-tone 7 = 2-tone triple 8 = 3-tone 9 = buzz 10 = chirp 11-14 = beep1-4 15 = 60hz Example: CALL sounds(1) ----------------------------------------------------------------------------- * FUNCTION startofline% (ln%) Finds the position of the START OF TEXT on a specified screen line. For example, if line 20 of the screen had the line This is a test ^ 5 on it, PRINT startofline%(20) would return 5 (the position of the first character on the line). If there is no text on the specified screen line, a value of 1 will be returned. Example: a% = startofline%(2) ----------------------------------------------------------------------------- * SUB vscrollbar (starty%, startx%, length%) Displays a vertical "scroll bar" on the screen starting at position starty%/startx%m, of length% characters (vertically). See the demo program for an example of vscrollbar. This routine displays the scrollbar only - does not control scrolling or anything else. You will have to write the routines yourself to display a scroll indicator, or wait for a future version of menulib . Example: CALL vscrollbar (1, 78, 15) ----------------------------------------------------------------------------- * SUB yesnobox (msg$, choice%) Prints a one-line message on the screen in a box, and waits for user to select YES, NO or CANCEL. Returns 1 (YES), 0 (NO) or -1 (Cancel) in choice%. Shortest string should be >20. Example: CALL yesnobox("Are you Sure?", choice%) -----------------------------------------------------------------------------