home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
World of Shareware - Software Farm 2
/
wosw_2.zip
/
wosw_2
/
QBAS
/
WNDTOOL5.ZIP
/
WINDTOOL.DOC
< prev
Wrap
Text File
|
1989-07-04
|
83KB
|
3,044 lines
WINDOW TOOLS
Programming 'Toolbox' Routines
version 5.0
for the
Microsoft QuickBASIC 4.5 (tm) Compiler
July 4, 1989
by
James P. Morgan
5226 Via Hacienda #115
Orlando Fl, 32809
Compuserve 71121,2006
AND
based on public domain works by
Dave Evers
Copyright (C) 1989 by James P. Morgan
TABLE OF CONTENTS
Overview..................................................... 03
Basic Requirements........................................... 04
Routine Overview............................................. 05
Keyboard Conventions ........................................ 09
Mouse Conventions ........................................... 10
Calling Conventions.......................................... 11
POPMENU ................................................ 12
POPLIST ................................................ 14
POPDIR ................................................. 15
TAGLIST ................................................ 16
TAGDIR ................................................. 17
BARMENU ................................................ 18
MENU123 ................................................ 19
CALENDAR ............................................... 20
CALENDR3 ............................................... 21
KEYCAL ................................................. 22
QUERY .................................................. 23
CAUTION ................................................ 24
QUESTION................................................ 25
WARNING ................................................ 26
ROW25 .................................................. 27
TITLE .................................................. 28
FULLMENU ............................................... 29
WAITTIME ............................................... 30
FASTPRT ................................................ 31
MAKEWIND ............................................... 32
SAVESCRN ............................................... 34
RESTSCRN ............................................... 35
SAVEWIND ............................................... 36
RESTWIND ............................................... 37
SCROLL ............................................... 38
Page 01
MMBUTTON ............................................... 39
MMCHECK ............................................... 40
MMCLICK ............................................... 41
MMCURSORON ............................................. 42
MMCURSOROFF............................................. 43
MMGETLOC ............................................... 44
MMSETLOC ............................................... 45
MMSETRANGE ............................................. 46
What is a QUADRANT ............................................. 47
Comments and Suggestions ........................................ 48
Page 02
OVERVIEW
--------
The Window Tool routines are designed and enhanced to perform
tasks that are common to many programs; and they were created
to perform these tasks in a manner that will enhance the value
of the programs they work with. Window Tools were also design-
ed to be as universal as possible, so that they can be adapted
easily to work in your programs. They were enhanced to be as
aesthetically pleasing, to give your programs that commercial
'look and feel'.
All of these routines use, as a base, the BASWIND5 package which
is included in these libraries. The routines in BASWIND5 allow
for fast screen writing (which is fundamental to all of these
procedures); the ability to easily create a colored 'window'
on the screen; and to let you save and restore the contents of
the screen so that you can create 'pop-up' window features in
your program with a minimum of effort.
The Window Tools routines build upon these basic functions to
provide for more 'high-level' applications. A simple call to a
Window Tool procedure, with the appropriate parameters, will
enable you to perform relatively complex tasks such as choosing
a filename from a directory, by simply selecting it from a list.
Page 03
BASIC REQUIREMENTS
------------------
All of the BASWIND5 and Window Tools routines require the
Microsoft QuickBASIC 4.5 Compiler.
You CANNOT use these routines with the BASIC or BASICA inter-
preter. Attempting to do so will surely cause your computer to
become spastic; possibly to the point of damage to files on
disk. So PLEASE DO NOT ATTEMPT TO USE THEM WITH THE INTER-
PRETER.
There is basically ONE(1) way to use the routines included in
this package (for now):
1) In a standalone EXE file created by compiling the
main program with the 'BC /O' option; and then linking
with the correct WINDQB45 library. Programs created
in this manner will be large; but they will be totally
self-sufficient. These routines were NOT meant to be used
from within the QuickBASIC environment (at this time)
because the QB environment handles arrays differently than
it does when a program is compiled as standalone. However
limited testing has been done in the QB 4.5 environment with
no problems found, so far.
Page 04
ROUTINE OVERVIEW
----------------
The following is a brief summary of the function of each of the
routines contained in the Window Tools package:
FASTPRT - A method of direct-screen writing to replace
the relatively slow PRINT statement. Allows
you to place a message string at a given row
and column using any valid screen attributes.
MAKEWIND - A routine to create a colored window on the
screen, with either no border or a line-
graphic border in one of 4 styles; with or
without a true 'shadow' underneath; and
either immediately appearing on the screen
or 'growing' into position.
SAVESCRN - Saves the contents of the current screen into
an array.
RESTSCRN - Restores the screen from the saved array.
SAVEWIND - Like SAVESCRN, but instead saves only the
screen data from a particular window area;
rather than the entire screen. Saves time
and memory.
RESTWIND - Restores the area of the screen saved by
SAVEWIND.
SCROLL - Allows you to scroll a section of the screen
either up or down and optionally write a new
string into the line created at either the
bottom or top, respectively. BIOS dependant.
POPMENU - Creates a 'pop-up' menu on the screen in a
window; allows you to scroll through the
menu with a 'select bar', and returns the
number of the option selected when [RETURN]
is pressed. Really sub-function of POPLIST.
POPLIST - While POPMENU is a display of several menu
items; all on screen at the same time; POP-
LIST displays a window with a few items from
a list that can be much larger than the on-
screen window. You may scroll through the
list with the cursor keys, move to the beg-
inning or end of the list with HOME and END,
respectively; or use the PG UP and PG DN
keys to move a 'window-full' at a time.
[RETURN] makes the selection.
Page 05
POPDIR - A special case of the POPLIST routine; where
the list displayed is the directory of a disk
obtained by specifying a filespec. The filespec
may contain the wildcard characters "*" and
"?".
TAGLIST - Where POPLIST is intended to select one value
from a list, TAGLIST allows you to 'Tag' one
or more items to be returned when [RETURN] is
pressed. Items that have been tagged can be
'untagged' (de-selected). Click on with mouse.
TAGDIR - Again, a special case of the TAGLIST routine
where the list of items is a directory.
BARMENU - If you like the user interface of QuickBASIC
Version 2/3, you will like this routine. A menu
bar across the top serves as the basis for
individual 'pull-down' menus from which you
can select via the cursor keys or mouse.
MENU123 - If you prefer the menu style of Lotus 1-2-3,
you may find this routine more to your liking
with its highlighting of the selected option
and the expanded description below.
CALENDAR - Given a month number and a year number, this
routine returns with a calendar in a window
for that month. As best as can be determined,
this calendar routine allows for leap years
and leap centuries correctly; and will provide
correct calendars for all years.
CALENDR3 - As above, this routine creates a calendar in
a window for a given month and year. However,
this one also provides calendars for the pre-
vious and following months.
KEYCAL - Starting from a month and year, this routine
allows you to advance or retreat months and
years by means of the cursor keys (in the
same fashion as Sidekick).
QUERY - Is a general-purpose window handler for such
function types as QUESTION/WARNING/CAUTION.
The above pseudo QUERY functions are still
included for downward compatibility ONLY.
CAUTION - Creates a yellow 'Caution' window on the
screen with message strings that you pass it.
You then select whether to Cancel or Continue
with the operation you are cautioning against.
NOT a true function, based on QUERY function.
Page 06
QUESTION- Allows you to present a user with a question,
and get back a YES or NO reply to your question.
NOT a true function, based on QUERY function.
WARNING - A bit more dramatic than CAUTION with its
red color and blinking 'WARNING' message;
but otherwise works exactly the same.
NOT a true function, based on QUERY function.
FULLMENU - Used when you want to create a full-screen
menu with several options requiring more
explanation than can be given in POPMENU.
TITLE - A 'sub-function' of the FULLMENU routine,
that places a title bar at the top of the
screen.
ROW25 - Also a spinoff of the FULLMENU routine. This
function lets you put a message on the bottom
row of the screen framed by flashing charac-
ters. Keeps the rest of the screen full of
data while prompting the operator.
WAITTIME - Pass it the number of seconds or fractions
thereof and it will pause for that long; re-
gardless of processor speed (unlike FOR-
NEXT loops).
Page 07
MMCHECK - Test for presence of a mouse and initializes it.
MMCLICK - Returns the number of times a mouse button has
pressed and released, since last time function
called.
MMBUTTON - Returns whether a mouse button is pressed and
currently held down.
MMGETLOC - Returns the current screen location of the mouse
cursor.
MMSETLOC - Moves the mouse cursor to the screen location
specified.
MMCURSORON - Turns on the mouse cursor, by making it visible.
MMCURSOROFF - Turns off the mouse cursor, by making it invisible.
MMSETRANGE - Restricts the mouses movements to an area of the
screen.
Page 08
KEYBOARD CONVENTIONS
--------------------
The keyboard ,as well as the mouse , may be used to allow you
to move within the windows, make window selections and page up
and down.
The keyboard is the primary input device. If an action is made
with the keyboard, the mouse will 'follow' the keyboards actions.
In otherwords, the mouse's cursor will re-position to the location
of the screen cursor, if the keyboard is used to move around the
screen.
The 'standard' keyboard key press and function are :
keyboard function that is performed
-------- -----------------------------------------------------
ENTER Pressing the ENTER key is the normal way to 'select'
an item from a window. ENTER signals that you are
through processing this window.
First Letter For most all windows you may select an items by
pressing the key that corresponds to the 'first
character' (case sensitive) of the item you may
want to select. If there are multiple items that
start with the same character, each will be high-
lighted in-turn.
CURSOR keys The CURSOR UP and CURSOR DOWN keys are normally used
to move the high-lighted select bar up or down within
a window. If there are more items than can be displayed
in the window, The CURSOR UP/CURSOR DOWN causes the
window selections to 'scroll' into or out of the
window. The CURSOR LEFT and CURSOR RIGHT keys are
normally used with a horizontal 'bar' type menu. You
cursor left or right to position to an item and it is
high-lighted. Positioning on a 'bar' item in some cases
causes a 'drop-down' window , with additional options,
to be displayed. You move the cursor up or down within
the 'drop-down' window and/or cursor left/right to
select another 'bar' menu item.
PgUp/PgDn If a window has more selection items than can be
displayed at once, you can page up or page down to see
a 'new' window of different selection items.
Home/End If a window has more selection items than can be
displayed at once, you can view the first window of
items by pressing Home. To view the last window of
items , press the End key.
ESC Most all windows/menus allow you to 'not select' an
option. If you decide that you really do not want to
make a selection off the window, then press the ESC
key.
Page 09
MOUSE CONVENTIONS
-----------------
The mouse ,as well as the keyboard , may be used to allow you
to move within the windows, make window selections and page up
and down.
The keyboard is the primary input device. If an action is made
with the keyboard, the mouse will 'follow' the keyboards actions.
In otherwords, the mouse's cursor will re-position to the location
of the screen cursor, if the keyboard is used to move around the
screen.
The 'standard' mouse usage and function is :
Mouse function that is performed
-------- -----------------------------------------------------
Click on Select an item within a window. Clicking on a high-
high-lighted lighted window item signals that this item is the
item one you want and that you are through processing
this window. You may click on an item to 'tag' or
'untag' it also.
Move Mouse For most all windows you may move to a new item by
pointer moving the mouse cursor, within the window or
on a 'bar' menu. Again, for most all windows, you may
move the mouse out of a window and back in.
Click on top If a window has more selection items than can be
or bottom of displayed at once, you can page up or page down to
window frame see a 'new' window of different selection items.
If a 'little arrow (up or down type)' is displayed
on the top or bottom in the window frame, you can
click on the 'little arrow' to get a window of
different selection items.
click outside Most all windows/menus allow you to 'not select' an
window or off option. If you decide that you really do not want to
menu 'bar' make a selection off the window, then click outside
the window or off the 'bar' menu (if one displayed).
Page 10
CALLING CONVENTIONS
-------------------
In all of the following descriptions, numeric variables MUST be
integers; either globally defined early in the program by means
of a DEFINT statement, or locally at the statement level by the
integer assignment '%'. The EXCEPTION is for the WAITTIME routine.
The parameter passed to WAITTIME MUST be a single precision var-
iable, to allow for fractions of a second.
You may also replace the variables in the parameter list with
constants. Strings must be quoted (i.e., "This is a String").
To see how each of these routines would be used in a typical ap-
plication program, please see the files on the disk marked
DEMO1.BAS and DEMO2.BAS. These are the source code files for the
demo programs distributed with BASWIND5. DEMO1 consists mainly
of CALLS to MAKEWIND, SAVESCRN, RESTSCRN, and SCROLL. DEMO2
includes a complete demo of all/most of the Window Tool Routines.
Run the DEMO1.EXE and DEMO2.EXE files to see the .BAS compiled
programs in action. The DEMO programs support a MS compatible mouse
if one is available.
Page 11
Routine: POPMENU
-------
Purpose: Provides a menu window from which you may make choices by
moving the 'select bar' by means of the cursor keys or mouse.
All the menu items to choose from are displayed at once.
CALL POPMENU(HEADER.TITLE$,NUMBER.ITEMS%,ITEMS$(),_
TYPE.FRAME%,FOREGROUND%,BACKGROUND%,_
HEADER.FORE%,HEADER.BACK%,QUADRANT$,_
SHADOW%,SELECTION%)
Passed:
HEADER.TITLE$ - A message that appears in the top row of the window.
The length of the header will determine the
width of the menu window unless a choice des-
cription in array ITEMS$() is longer.
NUMBER.ITEMS% - The number of items to choose from in the menu.
ITEMS$() - An array with the individual menu descriptions
for each choice.
TYPE.FRAME% - The type of frame that will go around the window:
0 - No frame. Just a border of spaces
of the background color.
1 - A single line frame.
2 - A double line frame.
3 - A single horizontal line,
double vertical line frame.
4 - A double horizontal line,
single vertical line frame.
FOREGROUND% - The foreground color; ranging from 0 (BLACK)
to 15 (BRIGHT WHITE). This will be the color
of the frame.
BACKGROUND% - The background color (the color of the window).
Can range from 0 (BLACK) to 7 (WHITE).
HEADER.FORE% - The foreground color of the Header.
HEADER.BACK% - The background color of the Header.
Page 12
QUADRANT$ - The quadrant or row:column co-ordinates
of where the window will be on the screen.
(see description of QUADRANT, page 47)
SHADOW% - A switch to determine if the menu window will
have a shadow underneath. Any non-zero value
will produce a shadow.
SELECTION% - The number of the item to be initially high-lighted.
This allow you to select the initial 'default' menu
selection item presented to the user.
Returns:
SELECTION% - The number of the item selected. This can be
used in a SELECT CASE .... statement to route
program flow to the desired section.
-1 - If [ESC] is pressed or mouse clicked
outside the menu window.
Page 13
Routine: POPLIST
-------
Purpose: To display a list of items from which to select one.
If there are more items in the list than can fit within
the window, you can scroll the list up or down, using
the cursor keys or the mouse.
CALL POPLIST(HEADER.TITLE$,SHOWITEMS%,NUMBER.ITEMS%,_
ITEMS$(),FOREGROUND%,BACKGROUND%,_
HEADER.FORE%,HEADER.BACK%,QUADRANT$,_
SHADOW%,SELECTION%)
Passed:
HEADER.TITLE$ - A message that appears in the top row of the window.
The length of the header will determine the
width of the menu window unless a choice des-
cription in array ITEMS$() is longer.
SHOWITEMS% - The number of items to display in the list window
at one time, in case there are more than can be
displayed in the window at one time.
NUMBER.ITEMS% - The total number of items in the list array.
ITEMS$() - A description for each item in the list array,
from which to choose.
FOREGROUND% - The foreground color; ranging from 0 (BLACK)
to 15 (BRIGHT WHITE). This will be the color of
the frame.
BACKGROUND% - The background color (the color of the window).
Can range from 0 (BLACK) to 7 (WHITE).
HEADER.FORE% - The foreground color of the Header.
HEADER.BACK% - The background color of the Header.
QUADRANT$ - The quadrant or row:column co-ordinates
of where the window will be on the screen.
(see description of QUADRANT, page 47)
SHADOW% - A switch to determine if list window will
have a black shadow underneath. Any non-zero
value will produce a shadow.
SELECTION% - The number of the item to be initially high-lighted.
This allow you to select the initial 'default' menu
selection item presented to the user.
Returns:
SELECTION% - The number of the item selected. The actual
list item selected can be determined by
LIST$(SELECTION%).
-1 - If [ESC] is pressed or mouse clicked
outside window.
Page 14
Routine: POPDIR
------
Purpose: Produce a window on the screen containing a list of files,
using the filespec in SEARCH$. The filespec may contain
the wildcards '*' and '?'. Select one file from the list
using the cursor keys or mouse.
CALL POPDIR(SEARCH$,SHOWITEMS%,FOREGROUND%,BACKGROUND%,_
HEADER.FORE%,HEADER.BACK%,_
QUADRANT$,SHADOW%,NUMFILES%,SELECTFILE$)
Passed:
SEARCH$ - The file specification used to determine
which files will be displayed in the
directory window. May contain the wildcard
characters "*" and "?". For example, "*.*"
or "BAS?????.TXT".
SHOWITEMS% - The number of items to display in the
directory window at one time, in case there
are more than can be displayed in the window
at one time.
FOREGROUND% - The foreground color; ranging from 0 (BLACK)
to 15 (BRIGHT WHITE). This will be the color of
the frame.
BACKGROUND% - The background color (the color of the window).
Can range from 0 (BLACK) to 7 (WHITE).
HEADER.FORE% - The foreground color of the Header.
HEADER.BACK% - The background color of the Header.
QUADRANT$ - The quadrant or row:column co-ordinates
of where the window will be, on the screen
(see description of QUADRANT, page 47)
SHADOW% - A switch to determine if list window will
have a black shadow underneath. Any non-zero
value will produce a shadow.
Returns:
NUMFILES% - The number of files that match the SEARCH$
filespec.
SELECTFILE$ - The full filename of the file selected.
NOTE: The header for this routine consists of the SEARCH$ string.
Page 15
Routine: TAGLIST
-------
Purpose: Produces a window on the screen with a list of items
as in POPLIST; only instead of returning only a single
selection from the list, allows you to 'tag' a number
of items using the 'Ins' key or 'untag' items with the
'Del' key. You may click on an item to tag/untag it also.
CALL TAGLIST(HEADER.TITLE$,SHOWITEMS%,NUMBER.ITEMS%,_
NUMTAGGED%,ITEMS$(),TAGITEMS%(),FOREGROUND%,_
BACKGROUND%,HEADER.FORE%,HEADER.BACK%,_
QUADRANT$,SHADOW%)
Passed:
HEADER.TITLE$ - A message that appears in the top row of the window.
The length of the header will determine the
width of the menu window unless a choice des-
cription in array ITEMS$() is longer.
SHOWITEMS% - The number of items to display in the window
window at one time, in case there are more
items than can be displayed in the window
at one time.
NUMBER.ITEMS% - The total number of items in the list array.
ITEMS$() - A description for each item in the list array,
from which to choose.
FOREGROUND% - The foreground color; ranging from 0 (BLACK)
to 15 (BRIGHT WHITE). This will be the color of
the frame.
BACKGROUND% - The background color (the color of the window).
Can range from 0 (BLACK) to 7 (WHITE).
HEADER.FORE% - The foreground color of the Header.
HEADER.BACK% - The background color of the Header.
QUADRANT$ - The quadrant or row:column co-ordinates
of where the window will be, on the screen.
(see description of QUADRANT, page 47)
SHADOW% - A switch to determine if list window will
have a black shadow underneath. Any non-zero
value will produce a shadow.
NUMTAGGED% - The maximum number of items allowed to be tagged
Returns:
NUMTAGGED% - The total number of tagged items.
TAGITEMS%() - An array holding the element numbers of the
tagged items.
Page 16
Routine: TAGDIR
------
Purpose: Produce a window on the screen containing a list of files,
using the filespec in SEARCH$. The filespec may contain
the wildcards '*' and '?'. Instead of returning only a
single selection from the list, you to 'tag' a number
of items using the 'Ins' key or 'untag' items with the
'Del' key. You may also click on an item to tag/untag it.
CALL TAGDIR(SEARCH$,SHOWITEMS%,FOREGROUND%,BACKGROUND%,_
HEADER.FORE%,HEADER.BACK%,QUADRANT$,_
SHADOW%,NUMTAGGED%,TAG$()$)
Passed:
SEARCH$ - The file specification used to determine
which files will be displayed in the
directory window. May contain the wildcard
characters "*" and "?". For example, "*.*"
or "BAS?????.TXT".
SHOWITEMS% - The number of items to display in the
directory window at one time, in case there
are more than can be displayed in the window
at one time.
FOREGROUND% - The foreground color; ranging from 0 (BLACK)
to 15 (BRIGHT WHITE). This will be the color of
the frame.
BACKGROUND% - The background color (the color of the window).
Can range from 0 (BLACK) to 7 (WHITE).
HEADER.FORE% - The foreground color of the Header.
HEADER.BACK% - The background color of the Header.
QUADRANT$ - The quadrant or row:column co-ordinates
of where the window will be, on the screen
(see description of QUADRANT, page 47)
SHADOW% - A switch to determine if list window will
have a black shadow underneath. Any non-zero
value will produce a shadow.
NUMTAGGED% - The maximum number of filenames that can be tagged.
Returns:
NUMTAGGED% - The number of filenames that were tagged.
TAG()$ - An array containing the full filenames of the
files tagged.
NOTE: The header for the window consists of the SEARCH$ string.
Page 17
Routine: BARMENU
-------
Purpose: Produces a display similar to the editing screen of
QuickBASIC with a bar across the top and 'pull-down'
menus for each selection.
CALL BARMENU(HEADER.TITLE$,FOREGROUND%,BACKGROUND%,_
BLKSIZE%,BLKNUM%,MAXSIZE%(), MAXITEMS%(),ITEMS$(),_
MENUSLCT%,SELECTION%)
Passed:
HEADER.TITLE$ - The Menu Headings that will be placed on the
second screen line (to allow for a screen border
if desired).
FOREGROUND% - The foreground color of the HEADER.TITLE$ string.
BACKGROUND% - The background color of the HEADER.TITLE$ string.
BLKSIZE% - The HEADER.TITLE$ string is divided into blocks
of fixed size, which will be highlighted as each
is selected and the appropriate menu 'drops down'
beneath it. BLKSIZE% sets the size of these blocks.
BLKNUM% - The number of fixed blocks of BLKSIZE% that are
present in HEADER.TITLE$.
MAXSIZE%() - An array with one element for each menu that will
appear (i.e., BLKNUM%). This array element holds
the maximum length of the items contained in the
corresponding menu. HOWEVER, with BASWIND5, this
array is NOT really effective, as BASWIND5 looks
at ALL the ITEMS$() and adjusts the window size.
MAXITEMS%() - An array with one element per menu, holding the
number of items in each corresponding menu.
ITEMS$() - A two-dimensional array (i.e. ITEMS$(1,1)
holding the actual menu item description.
The first dimension holds the menu number, and
the second holds the item number, within a
menu. Thus, ITEMS$(1,1) would be the first
item in Menu #1; and ITEMS$(5,10) would be
the 10th item in Menu #5 (depending on your
OPTION BASE or DIM statement).
SELECTION% - The number of the item to be initially high-lighted.
This allow you to select the initial 'default' menu
selection item presented to the user.
Returns:
MENUSLCT% - The menu number, of the menu selected.
SELECTION% - The item number, within the menu selected.
-1 - If ESC pressed or mouse clicked outside
menu window.
Page 18
Routine: MENU123
-------
Purpose: Produces two-line menus, similar to those used with
LOTUS 1-2-3.
CALL MENU123(HEADER.TITLE$,ROW%,FOREGROUND%,BACKGROUND%,_
NUMBER.ITEMS%,ITEMS$(),SELECTION%)
Passed:
HEADER.TITLE$ - A description the top menu line; from
which selection is made. The individual
names in the HEADER.TITLE$ string must be
separated by at least one space.
ROW% - The screen row on which the menu is to appear.
This allows you to place the menu on either the
top or bottom of the screen.
FOREGROUND% - The foreground color of the HEADER.TITLE$ and
the Description Line under it.
BACKGROUND% - The background color of the HEADER.TITLE$ and
the Description Line under it.
NUMBER.ITEMS% - The number of individual names within the
HEADER.TITLE$.
ITEMS$() - An array of descriptions, one for each selection
item in the HEADER.TITLE$.
SELECTION% - The number of the item to be initially high-lighted.
This allow you to select the initial 'default' menu
selection item presented to the user.
Returns:
SELECTION% - The number of the item selected.
-1 - If ESC pressed or mouse clicked off menu.
Page 19
Routine: CALENDAR
--------
Purpose: Displays a calendar for the month and year desired.
CALL CALENDAR(MONTH%,YEAR%,QUADRANT$,FOREGROUND%,BACKGROUND%,SHADOW%)
Passed:
MONTH% - The number of the month desired.
YEAR% - The year in 4 digit format; that is, 1986,1987 etc.
QUADRANT$ - The quadrant or row:column co-ordinates
of where the window will be, on the screen
(see description of QUADRANT, page 47)
FOREGROUND% - The foreground color; ranging from 0
(BLACK) to 15 (BRIGHT WHITE). This
will be the color of the frame.
BACKGROUND% - The background color (the color of the
window). Can range from 0 (BLACK) to
7 (WHITE).
SHADOW% - A switch to determine if list window will
have a black shadow underneath. Any non-zero
value will produce a shadow.
Returns:
No returned parameters.
NOTE: The calendar routines do no error checking, so for
proper results, you must insure that month and years
fall within proper ranges.
Page 20
Routine: CALENDR3
--------
Purpose: Displays a calendar for the month and year desired and also
for the previous and following month.
CALL CALENDR3(MONTH%,YEAR%,ROW%,FOREGROUND%,BACKGROUND%,SHADOW%)
Passed:
MONTH% - The number of the month desired.
YEAR% - The year in 4 digit format; that is, 1986,1987 etc.
ROW% - The row that the 3 calendars will be displayed on.
Since the 3 calendars produced by this routine
take up nearly the entire width of the screen,
there is no need to specify column parameter
FOREGROUND% - The foreground color; ranging from 0 (BLACK)
to 15 (BRIGHT WHITE). This will be the color of
the frame.
BACKGROUND% - The background color (the color of the window).
Can range from 0 (BLACK) to 7 (WHITE).
SHADOW% - A switch to determine if list window will
have a black shadow underneath. Any non-zero
value will produce a shadow.
Returns:
No returned parameters.
NOTE: The calendar routines do no error checking, so for
proper results, you must insure that month and years
fall within proper ranges.
Page 21
Routine: KEYCAL
------
Purpose: Display a calendar for the month and year desired.
However, using the cursor keys, you may advance or
back up months and years automatically.
CALL KEYCAL(MONTH%,YEAR%,QUADRANT$,FOREGROUND%,BACKGROUND%,SHADOW%)
Passed:
MONTH% - The number of the month desired.
YEAR% - The year in 4 digit format; that is, 1986,1987 etc.
QUADRANT$ - The quadrant or row:column co-ordinates
of where the window will be, on the screen
(see description of QUADRANT, page 47)
FOREGROUND% - The foreground color; ranging from 0 (BLACK)
to 15 (BRIGHT WHITE). This will be the color of
the frame.
BACKGROUND% - The background color (the color of the window).
Can range from 0 (BLACK) to 7 (WHITE).
SHADOW% - A switch to determine if list window will
have a black shadow underneath. Any non-zero
will produce a shadow.
Returns:
No returned parameters.
However, you may use the cursor keys
to vary the calendar displayed as follows:
UP ARROW - Increment Year
DOWN ARROW - Decrement Year
RIGHT ARROW - Increment Month
LEFT ARROW - Decrement Month
You may exit the routine by pressing
either RETURN or ESCAPE.
Page 22
Routine: QUERY
-----
Purpose: Allow a user to make a YES/NO or STOP/GO type of decision
based on a 'prompt', with supporting messages.
CALL QUERY(NUMBER.ITEMS%,ITEMS$(),QUADRANT$,HEADER.TITLE$,_
LEFT.BUTTON.MSG$,LEFT.BUTTON.REPLY$,_
RIGHT.BUTTON.MSG$,RIGHT.BUTTON.REPLY$,_
QUERY.TYPE%,SELECTION%)
Passed:
NUMBER.ITEMS% - The number of lines of message data to appear in
the QUERY window. Allow for any blank lines
you may want.
ITEMS$() - The array of the text message data to appear in
the window. You must provide null strings ("")
for any blank lines
QUADRANT$ - The quadrant or row:column co-ordinates
of where the window will be, on the screen
(see description of QUADRANT, page 47)
HEADER.TITLE$ - A message that reflects the main reason for display-
ing this QUERY window.
LEFT.BUTTON.MSG$ - The QUERY prompt that you want to appear in the left
window 'button', such as "YES"
LEFT.BUTTON.REPLY$ - The valid allowable user keyboard responses to
select this option. For example: for a YES reply you
would specify "Yy" (to allow for upper/lower case)
RIGHT.BUTTON.MSG$ - The QUERY prompt you want to appear in the right
window 'button', such as "NO"
RIGHT.BUTTON.REPLY$ - The valid allowable user keyboard responses to
select this option. For example: for a NO reply you
would specify "Nn" (to allow for upper/lower case)
QUERY.TYPE% - The type of QUERY window to be displayed, as follows:
0 - CAUTION/QUESTION type window
1 - WARNING type window
SELECTION% - The number of the item to be initially high-lighted.
This allow you to select the initial 'default'
dialog button presented to the user.
Returns:
SELECTION% - A 0 or 1, indicating selection as follows:
0 - left window 'button' selected
1 - right window 'button' selected
-1 - ESC key was pressed
Page 23
Routine: CAUTION
-------
Purpose: Produces a yellow (or brown, depending on your monitor)
Caution window with given text messages, allowing the
user to either Cancel or Continue with the operation at
hand. The CAUTION window is now only a special case of the
QUERY window function.
CALL CAUTION(NUMBER.ITEMS%,ITEMS$(),QUADRANT$,SELECTION%)
Passed:
NUMBER.ITEMS% - The number of lines of message data to appear in
the CAUTION window. Allow for any blank lines
you may want.
ITEMS$() - The array of the text message data to appear in
the window. You must provide null strings ("")
for any blank lines
QUADRANT$ - The quadrant or row:column co-ordinates
of where the window will be, on the screen
(see description of QUADRANT, page 47)
SELECTION% - The number of the item to be initially high-lighted.
This allow you to select the initial 'default'
dialog button presented to the user.
Returns:
SELECTION% - A 0 or 1, indicating selection as follows:
0 - CANCEL selected.
1 - CONTINUE selected.
-1 - ESC key was pressed
Page 24
Routine: QUESTION
--------
Purpose: Produces a yellow (or brown, depending on your monitor)
Question window with given text messages, allowing the
user to answer either Yes or No to the question.
The QUESTION window is now only a special case of the
QUERY window function.
CALL QUESTION (NUMBER.ITEMS%,ITEMS$(),QUADRANT$,SELECTION%)
Passed:
NUMBER.ITEMS% - The number of lines of message data to appear in
the QUESTION window. Allow for any blank lines
you may want.
ITEMS$() - The array of the text message data to appear in
the window. You must provide null strings ("")
for any blank lines
QUADRANT$ - The quadrant or row:column co-ordinates
of where the window will be, on the screen
(see description of QUADRANT, page 47)
SELECTION% - The number of the item to be initially high-lighted.
This allow you to select the initial 'default'
dialog button presented to the user.
Returns:
SELECTION% - A 0 or 1, indicating selection as follows:
0 - NO selected.
1 - YES selected.
-1 - ESC key was pressed
Page 25
Routine: WARNING
-------
Purpose: Similar to CAUTION above, but more dramatic with its
red color and flashing "WARNING" message.
The WARNING window is now only a special case of the
QUERY window function.
CALL WARNING(NUMBER.ITEMS%,ITEMS$(),QUADRANT$,SELECTION%)
Passed:
NUMBER.ITEMS% - The number of lines of message data to appear in
the WARNING window. Allow for any blank lines
you may want.
ITEMS$() - The array of the text message data to appear in
the window. You must provide null strings ("")
for any blank lines
QUADRANT$ - The quadrant or row:column co-ordinates
of where the window will be, on the screen
(see description of QUADRANT, page 47)
SELECTION% - The number of the item to be initially high-lighted.
This allow you to select the initial 'default'
dialog button presented to the user.
Returns:
SELECTION% - A 0 or 1, indicating selection as follows:
0 - CANCEL selected.
1 - CONTINUE selected.
-1 - ESC key was pressed
Page 26
Routine: ROW25
-----
Purpose: Produces a message centered on row 25 of the screen.
CALL ROW25(HEADER.TITLE$)
Passed:
HEADER.TITLE$ - A message that is to be placed on Row 25 of
the screen. This string must be of length 72
or less for proper display.
Returns:
No parameters returned.
NOTE: The string in HEADER.TITLE$ displayed centered on Row 25
bracketed by flashing highlights.
Page 27
Routine: TITLE
-----
Purpose: Produces a message centered in a Title Block.
CALL TITLE(HEADER.TITLE$)
Passed:
HEADER.TITLE$ - A message that is to be used to title the screen.
Returns:
No parameters returned
NOTE: The HEADER.TITLE$ displayed in a Title Bar at the top
of the screen.
Page 28
Routine: FULLMENU
--------
Purpose: Produces a full screen menu with choices selected by
pressing number keys.
CALL FULLMENU(HEADER.TITLE$,ITEMS$(),MAIN%,NUMBER.ITEMS%,SELECTION%)
Passed:
HEADER.TITLE$ - A message to be displayed in the screen title,
(uses TITLE function).
ITEMS$() - An array of the descriptions of each of the menu
selections
MAIN% - A switch indicating if this is the Main Menu
of the program. This determines if the Menu
description accompanying the [ESC] selection
states "Return to Previous Menu" or "Exit Program".
NUMBER.ITEMS% - The number of choices available for the menu.
Returns:
SELECTION% - The number of the item selected. This can be used
in a SELECT CASE .... statement to route program
flow to the desired section.
-1 - If ESC is pressed
Page 29
Routine: WAITTIME
--------
Purpose: Waits a given number of seconds or fractions thereof
regardless of processor speed or until ESC pressed.
CALL WAITTIME(SECONDS!)
Passed:
SECONDS! - A single precision number, holding the number of
seconds or fractions thereof to wait.
Returns:
No parameters returned.
NOTE: Returns to the calling program after the selected time
period or when the ESC key pressed.
The SECONDS was changed from a interger to a single precision
to allow for fractions of a second.
The WAITTIME was enhanced to allow for "rollover" at
midnite from a value of 86400 , back to 0 and still
correctly wait number of seconds specified.
A "backdoor" out of WAITTIME was added. The user can press
the ESC key and immediately cause a "timeout" to occur.
Page 30
Routine: FASTPRT
-------
Purpose: Performs direct write to the memory screen buffer. Writes
a string at a row and column location, using the specified
attributes. This is an adaptation of the QPRINT routine
that has been around for awhile.
CALL FASTPRT(HEADER.TITLE$,ROW%,COLUMN%,ATTR%)
Passed:
HEADER.TITLE$ - The information to be written directly to the
memory screen buffer (bypassing DOS).
ROW% - The row at which the HEADER.TITLE$ is to be written.
COLUMN% - The column at which the HEADER.TITLE$ to be written.
ATTR% - The screen attribute with which to display the
HEADER.TITLE$.
ATTR% is derived from the followung formula:
ATTR% = (backgrnd * 16) + foregrnd
Returns:
No return parameter.
Page 31
Routine: MAKEWIND
--------
Purpose: Produces a window of the given size and color at a
specified location on the screen; with options such
as a frame in various styles, a shadow underneath,
and 'growing' onto the screen.
CALL MAKEWIND(ULR%,ULC%,LRR%,LRC%,TYPE.FRAME%,FOREGROUND%,_
BACKGROUND%,GROW%,SHADOW%,HEADER.TITLE$)
Passed:
ULR% - An integer holding the upper left hand
corner row value.
ULC% - An integer holding the upper left hand
corner column value.
LRR% - An integer holding the lower right hand
corner row value.
LRC% - An integer holding the lower right hand
corner column value.
TYPE.FRAME% - An integer defining the type of frame style
for the window as follows:
0 - No frame. Just a border of spaces
of the background color. This is the
default if an invalid value is specified.
1 - A single line frame.
2 - A double line frame.
3 - A single horizontal line,
double vertical line frame.
4 - A double horizontal line,
single vertical line frame.
FOREGROUND% - The foreground color; ranging from 0 (BLACK)
to 15 (BRIGHT WHITE). This will be the color of
the frame. To get a blinking frame add 128 to
FOREGROUND%.
BACKGROUND% - The background color (the color of the window).
Can range from 0 (BLACK) to 7 (WHITE).
GROW% - A switch to determine if the window will grow
from the center outward. Any non-zero value will
produce a growing window.
SHADOW% - A switch to determine if the window will
have a black shadow underneath. Any non-zero
value will produce a shadow.
Page 32
HEADER.TITLE$ - A string that will be used to produce a
label in CENTERED in the top line of the
window frame. The label will be framed
by square brackets ( [ ] ). If the
HEADER.TITLE$ string is a null string ("") the
the label will not be displayed. If the
HEADER.TITLE$ is longer than the width of the
window, the label will be truncated.
Returns:
No parameters returned.
NOTES:
Once the window is placed on the screen, it is up to you
to fill it with data, by means of LOCATE, COLOR, and
PRINT statements.
The frame is drawn around the window coordinates. Thus the
dimensions of the windows will actually be two columns greater
in width and two row greater in length.
Adding a shadow increases the effective window size by 3
columns to the left and 1 row below.
You can use constants in the argument list of the CALL, so you
do not have to pre-assign variables to all parameters.
Page 33
Routine: SAVESCRN
--------
Purpose: Saves the screen buffer contents to an array.
CALL SAVESCRN(NOTEST%,SCRNARRY%)
Passed:
NOTEST% - A switch to determine whether to test horizontal
retrace status during data transfers to minimize
screen snow. The IBM CGA requires these tests;
but many non-IBM color cards and the EGA do not.
Operations can be significantly speeded up on
monitors NOT requiring a test of the horizontal
retrace.
A value of 0 for NOTEST% will cause the
routine to check horizontal retrace status.
Any other value will bypass status checking.
Regardless of this value, monochrome cards
will always bypass status checking.
SCRNARRY% - The memory location of the element of the array
that is to hold the screen data. The memory
location must be able to hold 4000 bytes.
The memory location is determined as follows:
(for the start of the array only)
SCRNARRY% = VARPTR(ARRY%(0))
If OPTION BASE 1 is used in the calling
program, the following statement would
be used instead:
SCRNARRY% = VARPTR(ARRY%(1))
Returns:
The data in the screen stored at the specified
memory location (of the array).
NOTE: This routine does not save the current cursor location. If you
require that it be saved, you must issue the following statement
BEFORE you call SAVESCRN:
OLDX% = POS(0):OLDY% = CSRLIN
You can restore the cursor position with the following statement
LOCATE OLDY%,OLDX%
Page 34
Routine: RESTSCRN
--------
Purpose: Moves screen data , that had been saved with SAVESCRN,
from the specified memory location ( in an array) back into
the screen memory buffer.
CALL RESTSCRN(NOTEST%,SCRNARRY%)
Passed:
NOTEST% - A switch to determine whether to test horizontal
retrace status during data transfers to minimize
screen snow. The IBM CGA requires these tests;
but many non-IBM color cards and the EGA do not.
Operations can be significantly speeded up on
monitors NOT requiring a test of the horizontal
retrace.
A value of 0 for NOTEST% will cause the
routine to check horizontal retrace status.
Any other value will bypass status checking.
Regardless of this value, monochrome cards
will always bypass status checking.
SCRNARRY% - The memory location of the element of the array
that is holding the screen data. The memory
location must be holding 4000 bytes.
The memory location is determined as follows:
(for the start of the array only)
SCRNARRY% = VARPTR(ARRY%(0))
If OPTION BASE 1 is used in the calling
program, the following statement would
be used instead:
SCRNARRY% = VARPTR(ARRY%(1))
Returns:
No parameters returned.
The screen as it was before the execution
of the SAVESCRN routine.
Page 35
Routine: SAVEWIND
--------
Purpose: Copies a rectangular area of the screen memory buffer
to a memory location (in an array).
SAVEWIND(ULR%,ULC%,LRR%,LRC%,WINDARRY%)
Passed:
ULR% - The upper left hand corner row value.
ULC% - The upper left hand corner column value.
LRR% - The lower right hand corner row value.
LRC% - The lower right hand corner column value.
WINDARRY% - The memory location of an element of an array
that is to hold the screen buffer data,
determined as follows: (for first elemeny only)
WINDARRY% = VARPTR(ARRY%(0))
or
WINDARRY% = VARPTR(ARRY%(1))
(if OPTION BASE 1)
Returns:
The data in the specified screen memory buffer
is stored at the specified memory location
(of an array).
Page 36
Routine: RESTWIND
--------
Purpose: Copies to a rectangular area of the screen memory buffer
from a memory location (in an array).
RESTWIND(ULR%,ULC%,LRR%,LRC%,WINDARRY%)
Passed:
ULR% - The upper left hand corner row value.
ULC% - The upper left hand corner column value.
LRR% - The lower right hand corner row value.
LRC% - The lower right hand corner column value.
WINDARRY% - The memory location of an element of an array
that is holding the screen buffer data,
determined as follows: (for first elemeny only)
WINDARRY% = VARPTR(ARRY%(0))
or
WINDARRY% = VARPTR(ARRY%(1))
(if OPTION BASE 1)
Returns:
No parameters returned.
The data in the specified array is restored
to the screen at the given co-ordinates. Note
that these DO NOT have to be the same coordinates
that were given at the time of the SAVEWIND
operation; allowing you to 'pick up' a section
of the screen and 'drop' it somewhere else.
Page 37
Routine: SCROLL
------
Purpose: Allows an area of the screen to be scrolled or cleared,
independent of the rest of the screen.
CALL SCROLL(ULR%,ULC%,LRR%,LRC%,LINES%,DIR%,HEADER.TITLE$)
Passed:
ULR% - The upper left hand corner row value.
ULC% - The upper left hand corner column value.
LRR% - The lower right hand corner row value.
LRC% - The lower right hand corner column value.
LINES% - The number of lines to be scrolled. Normally 1,
so that another line can be set into its place.
If number of lines is 0, THEN the area defined
is cleared, using the background attribute.
DIR% - The direction of the scroll.
1 - scroll up
-1 - scroll down
HEADER.TITLE$ - A text message that will be placed into the
area left clear by the scroll procedure.
Returns:
No returned parameters.
NOTE:
The SCROLL function takes advantage of calls made
directly to the BIOS. Therefore the PCs BIOS that
the program is running on MUST be able to provide
IBM compatibility for SCROLL to work correctly.
Page 38
Routine: MMBUTTON
--------
Purpose: Returns which mouse buttons are currently being held down.
CALL MMBUTTON(LFT%,RGT%)
Passed:
No parameters passed
Returns:
LFT% - Will return a non-zero value if the left button is
currently held down.
RGT% - Will return a non-zero value if the right button is
currently held down.
Page 39
Routine: MMCHECK
-------
Purpose: Check for an installed mouse, reset the mouse, initialize
all motion counters and set mouse to center position.
This call MUST BE MADE BEFORE any other mouse calls will
function.
CALL MMCHECK(MOUSE%)
Passed:
No parameters passed.
Returns:
MOUSE% - The number of mouse buttons installed.
Zero(0) if NO mouse installed.
Page 40
Routine: MMCLICK
-------
Purpose: Returns which mouse buttons have been clicked since you last
used this function.
CALL MMCLICK(LFT%,RGT%)
Passed:
No parameters passed
Returns:
LFT% - Will return the number of times that left button has
been pressed since the last call to this function.
RGT% - Will return the number of times that right button has
been pressed since the last call to this function.
Page 41
Routine: MMCURSORON
----------
Purpose: Makes the cursor associated with the mouse visible. This is
normally a blinking block, and shows where the mouse is
currently pointing.
CALL MMCURSORON
Passed:
No parameters
Returned:
No parameters
Page 42
Routine: MMCURSOROFF
-----------
Purpose: Makes the cursor associated with the mouse invisible.
If the cursor is off, the cursor will still follow the
mouses movements, but the cursor will not be seen until
turned on.
MMCURSORON.
CALL MMCURSOROFF
Passed:
No parameters
Returned:
No parameters
Page 43
Routine: MMGETLOC
--------
Purpose: Gets the current location of the mouse cursor. This is
returned as a value from 0-639 for columns, and 0-199 for
rows. You need to adjust this for the current screen format.
If you're in text mode, divide the columns by eight and the
rows by eight. If you're in low-res graphics mode, divide
by two. If you're in high res graphics, the numbers are fine.
CALL MMGETLOC(COL%,ROW%)
Passed:
No parameters passed
Returned:
COL% - 'x' co-ordinate (column) is a value from 0-639
ROW% - 'y' co-ordinate (row) is a value from 0-199.
NOTE: To normalize the values returned by MMGETLOC (for 80x25 text
screen) , the basic formula is:
Basics CSRLIN value is: ((ROW%\8) + 1)
Basics POS(0) value is: ((COL%\8) + 1)
Page 44
Routine: MMSETLOC
--------
Purpose: Sets the current location of the mouse cursor. This is
passed as a value from 0-639 for columns, and 0-199 for
rows. You need to adjust this for the current screen format.
CALL MMSETLOC(COL%,ROW%)
Passed:
COL% - 'x' co-ordinate (column) is a value from 0-639
ROW% - 'y' co-ordinate (row) is a value from 0-199.
Returns
No parameters returned.
NOTE: To translate Basic's CSRLIN and POS(0) values, (for 80x25 text
screen) , the basic formula is:
Mouses 'y' value is : ((CSRLIN-1)*8))
Mouses 'x' value is : ((POS(0)-1)*8)
Page 45
Routine: MMSETRANGE
----------
Purpose: Sets the range of locations where the mouse cursor is allowed
to be. This is done by specifying the upper left corner and
lower right corner of the edges of the mouse input field.
CALL MMSETRANGE(ULC%,ULR%,LRC%,LRR%)
Passed:
ULC% - The upper left hand corner column value.
ULR% - The upper left hand corner row value.
LRC% - The lower right hand corner column value.
LRR% - The lower right hand corner row value.
Returns:
No parameters returned.
NOTE: To translate Basic's CSRLIN and POS(0) values, (for 80x25 text
screen) , the basic formula is:
Mouses ROW value is : ((CSRLIN-1)*8))
Mouses COLUMN value is : ((POS(0)-1)*8)
Page 46
QUADRANT$
---------
A QUADRANT$ is defined as a string. This string can have a
a value as noted below ("0"/"4" or "01:01"). The "row:column"
format defines actual upper left screen co-ordinates of a window.
The other format, "0", defines a quadrant of the screen in which
a window is centered. With BASWIND5, IF the window does NOT center
in a quadrant (its to big for example), the center co-ordinates
for the quadrant are adjusted so that the window will still be
in that quadrant of the window.
screen layout
-----------------
---------------------------
| . |
| 1 . 2 |
| . |
|.............0.............|
| . |
| . |
| 4 . 3 |
| . |
---------------------------
"0" - In the exact center of the
screen; centered according
to menu size.
"1" - Upper Left Quadrant.
"2" - Upper Right Quadrant.
"3" - Lower Right Quadrant.
"4" - Lower Left Quadrant.
"rr:cc" - Specifies exact coordinates
of upper left corner of window
to be row rr and column cc
(two digits each).
Page 47
Comments, and Suggestions
In order to make the Window Tools routines the best that they
can be, and to better serve your needs; This form is provided
for your feedback. If you have any comments or suggestions on
these routines, please use this to communicate that information.
If you have any suggestions as to additional Window Tool
routines that would be useful to you, please include that infor-
mation as well.
You may also use this form if you would like to be kept informed
of any future additions and releases of Window Tools or supporting
assembler routines.
Name:________________________ Mail to: James P. Morgan
Address: ____________________ 5226 Via Hacienda #115
____________________ Orlando FL 32809
City: _______________________ U. S. A.
State: __________ Zip: ______
Country: ____________________
COMMENTS:
________________________________________________________________
________________________________________________________________
________________________________________________________________
________________________________________________________________
________________________________________________________________
________________________________________________________________
________________________________________________________________
________________________________________________________________
________________________________________________________________
________________________________________________________________
________________________________________________________________
________________________________________________________________
________________________________________________________________
Page 48
