POINT Software Programming/PPROG1.ISO/basic/mnusys21/menulib.doc

Text File | 1993-10-06 | 18.6 KB | 565 lines

Menulib for Menusys-PB
Add-On Library Routines V2.1
Documentation/Reference
for SUBs/FUNCTIONs

Total SUBs/FUNCTIONs: 40 (38 SUBs, 2 FUNCTIONs)

--------------------------------------------------------------------------------
* 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 clr%, bckg%.
Set chr% = 0 for black background, 1 for dark background, 2 for medium,
3 for light, 4 for pure

Example: CALL background(2)

--------------------------------------------------------------------------------
* 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.

Note: Use LBOUND of 1 for arrays (DIM 1 : X)

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%

Note: Use LBOUND of 1 for arrays (DIM 1 : X)

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$, rod%)


Changed in V2.0 (rod% parameter added).
Lets a user select from a directory entry on the screen.  Includes
the 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 in ch$ if cancelled).  Set rod% to
1 to Return to the Original Directory when the routine was first called,
or 0 to stay at the user-selected directory.  If rod% = 1, the entire
path of the user's choice will be returned, otherwise just the filename,
and the default directory will be set to the user's choice.
Set global variable flash% to 1 for "flashing" entry when selected
with mouse or ENTER.

ROD% = 1: Stay at current directory/drive and return full path.
ROD% = 0: Change to directory/drive selected by user and return filename.

Example: CALL choosedir("*.*", ch$, 0)

--------------------------------------------------------------------------------
* sub getdirectory (fi$, atype%)


An internal routine used by CHOOSEDIR to get the current
directory.  Requires shared variables within module.
This routine may be made accessible to external programs
in future versions of Menulib.

--------------------------------------------------------------------------------
* sub getdisk (d%)


Returns drive code of current or default drive.
0 = A, 1 = B, 2 = C, Etc.

Example: CALL getdisk(d%)

--------------------------------------------------------------------------------
* sub hscrollbar (starty%, startx%, length%)


Displays a horizontal "scroll bar" on the screen starting at position
starty%/startx%, of length length% characters.  See the demo program
for an example of hscrollbar.  This routine displays the scroll bar only-
it does not control scrolling or any other related functions.  A future
version of Menulib may more fully implement the hscrollbar feature.

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.

Note: Use LBOUND of 1 for arrays (DIM 1 : X)

Example: DIM msg$(2)
     msg$(1)="Disk Problem-"
     msg$(2)="Select OK"
     CALL infobox(msg$())

--------------------------------------------------------------------------------
* sub inpbox (msg$, ip$, mx%, ll%, ul%)


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$.

If the user presses ENTER alone, ip$ will be set
to CHR$(13).  If the user presses ESC or CANCEL,
ip$ will be the null string ("").  ip$ is re-used
as the default for the next user input, so you can
control the "default" input by setting ip$ before
calling this routine.

For example, to input a 3-digit number
with "100" being the default value:

msg$="Enter Number:"
mx% = 3:ip$ = "100"
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 marklist (lst$(), mrk?())


New for V2.0.
Similar to picklist, but lets the user "mark off"
options, instead of selecting one.
Call with lst$() = the list of items, mrk?() =
the array of "markers" (1=marked, 0=not).

Example: CALL marklist (lst$(), mrk?())

--------------------------------------------------------------------------------
* sub mcls


New for V2.0.
Clears the screen and turns the mouse cursor
on/off to prevent "mouse droppings."

Example: CALL mcls

--------------------------------------------------------------------------------
* 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.  Set global
variable flash% to 1 for "flashing" entry when
selected with mouse or ENTER.

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 mprint (mp$)


New for V2.0
Same as normal PRINT, but turns off mouse cursor first if
necessary.  Only prints strings, and does not work with PRINT
USING.  No carriage return afterwards.

Example: mprint a$
or     : call mprint (a$)

--------------------------------------------------------------------------------
* 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 mxbounds(mn%, mx%)

Sets minimum and maximum x-axis boundaries for mouse cursor
movement.  In other words, confines the mouse cursor to a
certain range of (horizontal) columns on the screen.

Example: CALL mxbounds(3, 77)

--------------------------------------------------------------------------------
* sub mybounds (mn%, mx%)


Sets minimum and maximum y-axis boundaries for mouse cursor
movement.  In other words, confines the mouse cursor to a
certain range of (vertical) rows on the screen.

Example: CALL mybounds(2, 24)

--------------------------------------------------------------------------------
* function pathstring$


Returns current disk/path in a string of the
form C:\QB\EXE\ ... Trailing backslash included.
Updated for Menusys 2.0 using curdir$ function.

Example: PRINT pathstring$

--------------------------------------------------------------------------------
* sub picklist (lst$(), choice%)


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).
Set global variable flash% to 1 for "flashing" entry when selected
with mouse or ENTER.

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 -
See demo program for example usage.

Example: CALL printborder

--------------------------------------------------------------------------------
* 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$)


An advanced routine that allows a user to edit a portion of the
screen, using all the normal cursor keys and editing controls.

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$)

See the MNSDEMO.BAS program for an example of how screenedit
can be used.

--------------------------------------------------------------------------------
* sub screenrecall(scn%)


New for V2.0
Recalls a screen previously saved with SCREENSTORE.
See SCREENSTORE for details on how to use.

Example: CALL screenrecall(4)

--------------------------------------------------------------------------------
* sub screenstore(scn%)


New for V2.0
Stores a screen in the global buffer variable
SCRNBUF?.  Set the second dimension of SCRNBUF?
to the highest value desired (depending on how many
screens you want to store).  It's recommended you
don't store to screens 0-3, as these are reserved by
Menusys/Menulib.  For example, you could use:
DIM scrnbuf?(1:4096, 0:7)
which would provide storage space for screens 0-7.
You could then CALL SCREENSTORE (4) to store the
current text screen in slot number 4, and
CALL SCREENRECALL(4) to recall it.  In this case, you'd
have set aside 32K (8*4096) bytes for screen storage,
and you could use slots 4-7 for storing your own screens.

Example: CALL screenstore(4)

--------------------------------------------------------------------------------
* sub selectback (ch%)


Allows a user to select a background color from a menu, and
returns selection in cl% ... -1 if user cancelled.
See MLIBDEMO.BAS for example of use.

Example: CALL selectback(ch%)

--------------------------------------------------------------------------------
* sub selectfore (ch%)


Allows a user to select a foreground color from a menu, and
returns selection in cl% ... -1 if user cancelled.
See MLIBDEMO.BAS for example of use.

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 showarray (title$, maxline%, holdit$())


New to Version 2.0 - Displays passed text array.
Called by SHOWTEXTFILE in Menulib V2.0.  Does not
save previous screen or change array in holdit$().
Call with title$ = title to display at bottom
of screen and maxline% maximum element of the
array (line) to display.

Example: CALL showarray("DEMO.BAS", 32, holdit$())

--------------------------------------------------------------------------------
* sub showtextfile (fi$, clr%)


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 routine calls SHOWARRAY after
loading a text file into an array.

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 trimpath$(fi$)


New to V2.0 -
Trims the path off a filename, returning
just the original filename (12 char. max).

Example: PRINT trimpath$("C:\TEMP\TEST.BAS")

--------------------------------------------------------------------------------
* sub vscrollbar (starty%, startx%, length%)


Displays a vertical "scroll bar" on the screen starting at position
starty%/startx%, 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.  A
future version of Menulib may more fully implement the VSCROLLBAR
feature.

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 in msg$ should be >20.

Example: CALL yesnobox("Are you Sure?", choice%)