Menusys Menuing System
Text-Mode GUI for Power BASIC 3.0
Version 1.0A

(C) Copyright 1993 by Tim Gerchmez
----------------------------------


		      ** Sub and Function Reference **


Total Routines: 24
-----------------------------------------------------------------------------
* FUNCTION altkey%

This function returns the state of the ALT key.  It will return one
if the ALT key is pressed, or zero if it isn't.

Example: IF altkey% <> 0 THEN PRINT "ALT Key Pressed!"

-----------------------------------------------------------------------------
* SUB dopcopyfrom

This routine copies the page zero text screen to page
one, turning off the mouse first if necessary.

Example: CALL dopcopyfrom

-----------------------------------------------------------------------------
* SUB dopcopyto

This routine copies the text screen at page one back
to page zero, turning off the mouse first if necessary.

Example: CALL dopcopyto

-----------------------------------------------------------------------------
* SUB drawbox (yd%, xd%, tpe%, shadow%, title$)

Draws a box with the upper left corner at the current cursor
position.

yd% / xd% = Y and X dimensions of the box desired

tpe% = border type:
0 = no border
1 = single border
2 = double border

shadow% = shadow type:
0 = no shadow
1 = left shadow
2 = right shadow

title$ = title for box (set to "" for none)

Example: LOCATE 1,1
	 CALL drawbox(10, 10, 1, 2, "This is a box")

------------------------------------------------------------------------------
* SUB findfile (fi$, yn%)

Searches for the specified path\file in fi$.  If not
found, yn% = 0, else yn% = 1.

example: INPUT "Filename ";fi$
	 call findfile(fi$, yn%)
	 if yn% = 0 then print "File Not Found"

-----------------------------------------------------------------------------
* SUB mcheck

Checks current position of mouse cursor and state of buttons
and updates the corresponding global variables msy%, msx%, lb%
and rb% (for lb% and rb%, 1 = pressed, 0 = not pressed).

msy% = y coordinates of mouse cursor (1-25)
msx% = x coordinates of mouse cursor (1-80)
lb% = left button
rb% = right button

Example: CALL mcheck

-----------------------------------------------------------------------------
* SUB MENUSYS (menu$(), help$(), menucount%(), menutype%(), topchoice%, bottomchoice%)

Displays a pull-down menu at the top of the screen.  DIM menu$
(topcount%, bottomcount%), help$(topcount%, bottomcount%),
menutype%(topcount%, bottomcount%).  Topcount% should correspond
to the number of top (bar) menu choices available, and bottomcount%
to the MAXIMUM number of bottom menu choices available.

topchoice% and bottomchoice% will be returned, corresponding to the top
(bar) and bottom (box) menu choices selected by the user.  If the user
presses ESC, bottomchoice% will equal zero.

* This is the "main" routine in the MENUSYS Library,
* and the one routine that calls most of the others.

Menu Types (for menutype%):
0 = Available (normal)
1 = Unavailable (cannot be selected)
2 = Bullet On
3 = Bullet Off

Use Function ALTKEY in a separate program to determine if the ALT key
is pressed (to call this routine) and/or use the mouse routines to
determine if the mouse cursor is in the top row and proper column
to call this routine.  If not using ALTKEY or mouse cursor to call
MENUSYS, you can set topchoice% to the starting choice number for
the top menu before calling (defaults to menu option one).

Menu Selection Columns (for each top item):
1 = 1-10       2 = 11-20       3 = 21-30       4 = 31-40
5 = 41-50      6 = 51-60       7 = 61-70       8 = 71-80

Example: CALL menusys(menu$(), help$(), menucount%(), menutype%(), topch%, botch%)
	 PRINT "You Chose ";topch%; botch%

-----------------------------------------------------------------------------
* SUB mhardreset (ms%, nb%)

Checks status of mouse and resets if present.  Use this routine
at the beginning of a program to check for the presence of a mouse
and to reset it if present.
Returns ms% = -1 and nb% = number of buttons if mouse driver present
and reset, otherwise ms% = 0.

Example: CALL mhardreset(ms%, nb%)
	 IF ms%<>0 then print "Mouse Found, with ";nb%;" buttons."

-----------------------------------------------------------------------------
* SUB mhide

Makes the mouse cursor invisible, and decrements the internal
mouse cursor flag by one.

Example: IF mouse% <> 0 THEN CALL mhide

-----------------------------------------------------------------------------
* SUB mscrolldown (nls%, uly%, ulx%, lry%, lrx%, atrb%)

Scrolls a portion of the text screen down, turning the mouse
cursor off first if necessary.  Set uly% and ulx% to the
coordinates for the upper left corner of the area to scroll,
and lry% and lrx% to the lower right corner of the area to
scroll.  Set atrb% to the attribute to scroll into the blank
area.  nls% = number of lines to scroll down (if 0, the entire
area is blanked).

Example: CALL mscrolldown(1, 1, 1, 25, 80, 7)

-----------------------------------------------------------------------------
* SUB mscrollup (nls%, uly%, ulx%, lry%, lrx%, atrb%)

Scrolls a portion of the text screen up, turning the mouse
cursor off first if necessary.  Set uly% and ulx% to the
coordinates for the upper left corner of the area to scroll,
and lry% and lrx% to the lower right corner of the area to
scroll.  Set atrb% to the attribute to scroll into the blank
area.  nls% = number of lines to scroll up (if 0, the entire
area is blanked).

Example: CALL mscrollup(1, 1, 1, 25, 80, 7)

-----------------------------------------------------------------------------
* SUB mshow

Increments the internal mouse cursor flag, and if flag = 0, makes
the mouse cursor visible.  Flag defaults to -1 when driver is reset,
so this function will usually make the cursor visible on the screen.

Example: CALL mshow

-----------------------------------------------------------------------------
* SUB mwaitrelease

Waits for Left/Right Mouse Button to be Released.

Example: CALL mwaitrelease

------------------------------------------------------------------------------
* sub pagecopy(source%, dest%)

This routine copies the screen page specified in source% to the page
specified in dest%, and is called by dopcopyfrom and dopcopyto to
save/restore the current text screen.

This is a text-mode only imitation of the
QuickBASIC/QBASIC PCOPY command.

Example: CALL pagecopy(1, 0)

-----------------------------------------------------------------------------
* SUB printbottomhelp (hlp$)

Internal routine used by Menusys, but can be used externally as well.
Displays the line of help text in hlp$ on the bottom of the screen.
Blanks the bottom screen line if hlp$ = "-". To skip print, set hlp$
to "".


Example: hlp$="Press F1 for Help"
	 CALL printbottomhelp(hlp$)

-----------------------------------------------------------------------------
* SUB readhelp (topchoice%, bottomchoice%)

A routine to display context-sensitive help.  Utilized by MENUSYS but can
also be called externally.  The global variable HELPFN$ should be set to
the path\filename of the help file, and PROGNAME$ to the name of the program
that the help is for.  The format of the help files in MENUSYS is:

[1/1]

HELP TEXT

~~~
[1/2]

HELP TEXT

~~~
[1/3]

HELP TEXT

~~~

The top and bottom menu entries for the help item desired should be in
topchoice% and bottomchoice% before calling.  Notice that each help entry
in the help file has the top/bottom menu entries defined in square brackets,
followed immediately by the help text.  At the end of the help text for each
menu item, there are three tildes in a row.  There can be an unlimited
number of help items in each help file, as long as they follow the above
format (see the example help file included with MENUSYS).  If you use
[0/0] or any other numbers that don't fall in the area of the top/bottom
menu entries, you can call readhelp from the main program to display help
on other program options.  For example, you could CALL READHELP(0,0) and
have a [0/0] entry in your help file.

If you don't want MENUSYS to display help for the various pulldown menu
items, just set HELPFN$ to "" before calling.  Also, if READHELP doesn't
find the help file indicated in HELPFN$, it won't crash but it won't
display any help either.  If it finds the help file but not the entry
specified in topchoice%/bottomchoice%, it will display "NO HELP AVAILABLE
FOR THIS MENU ENTRY."

Example: PRINT "You Pressed F1!"
	 CALL readhelp(0, 0)

-----------------------------------------------------------------------------
* SUB readscreen (y%, x%, ch%, atr%, fgd%, bkg%)

A routine to read the contents of the screen at the Y (1-25) and X
(1-80) coordinates specified in y% and x%.  The character at the screen
position specified will be returned in ch%, the attribute value in atr%,
the foreground color in fgd%, and the background color in bkg%.

Example: CALL readscreen(1, 1, ch%, atr%, fgd%, bkg%)

-----------------------------------------------------------------------------
* FUNCTION vidseg&

A function to return the correct video segment.  VIDSEG& will equal
&hb800 if color or &hb000 if a monochrome monitor is detected.  These
values can then be used with DEF SEG and an offset to access video
(text) memory directly.

Example: IF vidseg& = &Hb800 then print "Color"

-----------------------------------------------------------------------------
* SUB writescreen (y%, x%, ch%, atr%, fgd%, bkg%)

A routine to store a certain value at a specified screen location.  Set y%
and x% to the Y and X screen coordinates desired, ch% to the character to
store.  Then either set atr% to 0 and fgd% and bkg% to the desired
foreground/background colors, or set atr% to the desired attribute and
ignore the values of fgd% and bkg%, and call this routine.

Example: CALL writescreen(1, 1, 32, 0, 7, 1)

-----------------------------------------------------------------------------
Internal Routines used by function MENUSYS:

* SUB bottomdehilight (top%, bottom%, menu$(), menutype%())

This is an internal routine used by MENUSYS to dehighlight
box menu options.


* SUB bottomhilight (top%, bottom%, menu$(), menutype%())

This is an internal routine used by MENUSYS to highlight
box menu options.


* SUB printbottommenu (top%, menu$(), menucount%(), menutype%(), bcheck$)

An internal routine used by MENUSYS to display the bottom (box) menus.


* SUB printtopmenu (menu$(), hilight%)

An internal routine used by MENUSYS to display the top (bar) menu.


* SUB tophilight (top%, hilight%, menu$())

An internal routine used by MENUSYS to highlight entries on the top
(bar) menu.

-----------------------------------------------------------------------------