S C R E E N U T I L I T I E S

for the

QuickBASIC 4.0 Programmer

Version 1.0





by
Tony Martin
of
The BAD SOFTWARE Company




















The BAD SOFTWARE Company
7623 Matera Street #104
Falls Church, Virginia 22043

Welcome to the Screen Utilities for QuickBASIC 4.0 programmers.
Let's get the nasty stuff out of the way right off.

First of all, QuickBASIC and Microsoft are trademarks of Microsoft
Corporation. Just in case you didn't know.

Second, this package of utilities, including all source code and
documentation, is (C)opyright 1988 by Tony Martin (that's me). I retain
all rights to it until I decide to relinquish them.

Third, this package is being distributed as shareware. It is not
free. I don't expect to make any money from it to speak of, but it
would be nice to see if the shareware system really works. The response
to this product will determine future marketing techniques. Right now
I'm still feeling innocent, benevolent and trusting of the American
computer programmer, and truly believe that if s/he uses this package,
they will register it. I'm only asking for the paltry donation of $5.
If you use the routines supplied in this package in any fashion, and
like them, I urge you to respond by sending the $5 donation to me
(checks to TONY MARTIN, not BAD SOFTWARE),

Tony Martin
7623 Matera Street, #104
Falls Church, VA 22043

If you register, I'll send you a flyer with a list of the other goodies
I've written. Even if you don't actually use them, how about dropping a
few comments about it? You can mail them to the above address, or give
my bulletin board a buzz and leave me a comment:

The Story Board BBS
703/847-0374
300/1200 bps
24 hours/day

You can also find out about other programs/packages I've written by
similar methods.

And now that we have the formalities out of the way, let's move on
to the fun stuff.


FILES IN QBSCR

In the QBSCR.ARC package, you should find the following files:

QBSCR.BAS The source code for the screen utilities
QBSCR.QLB The library file for use in the QuickBASIC
environment
QBSCR.LIB The library file for use in command line
compilation
QBSCR.INC A $Include file that contains DECLARE statements
for all the utilities
SAMPLE.BAS A demo program that shows the usage and notes for
all the utilities. Kinda fun, and useful, too.
QBSCR.DOC This text file

If any of these files are missing, you can send me a check for $5 (this
does NOT cover registration - only the cost of the disk and mailing,
etc. Add another $5 if you want to register as well) and I'll send you
a copy of the whole package.



THE UTILITIES

Here is a brief description of the utilities included in the
library and what they do.

Subprogram Banner: This subprogram will, with successive calls, create
a scrolling billboard effect with a string on any line of the
display.

SubProgram Center: Will center a string of text on any given line on
the screen.

Function ColorChk: Returns TRUE (Non-Zero) if the machine it is run on
has color capability. Returns FALSE (Zero) if it has only mono.

Function MakeMenu%: This function will create a vertical list menu just
like you've always wanted to have in your programs. It will let you
move a highlight bar up and down to select one of the menu entries.
Returns as a value the number in the list of the selected entry.

Subprogram MakeWindow: This extremely versatile routine will create
windows on the screen for you. You'll have to read the detailed
description to see all the features, but to tantalize you, it will
display 10 different types of windows, with 6 different frame
types, can "explode windows" onto the screen, add shadows, and
more.

Subprogram OffCenter: Allows you to center text between two supplied
points, creating a centered effect that is not relative to the
entire screen.


LOADING AND USING THE UTILITIES

There are a couple of different methods you can use to incorporate
these routines into your own programs. The two methods I use are:

1) Load the library file with the /L parameter when starting up
QuickBASIC. Like QB SAMPLE /L QBSCR.

2) Incorporate the actual source code as part of the program.

Of the two methods, the latter is much more effective. There are
reasons for this perverse view. One, there are bugs in QuickBASIC 4.0
that cause problems. If have the library loaded as the first method
describes, you cannot make any calls to it from SUBs in your own
program. The machine tends to lock up and blank the screen. I mean, the
routines are pretty simple and don't do anything odd. So there's
something strange afoot at Microsoft.

The second method not only alleviates this problem, but it also
makes your executable code smaller. If you use a QLB or LIB library,
the entire library gets linked into your program, regardless of whether
or not you use all it's functions. By incorporating the actual source
code into your programs, you can cut the executable size by using only
the functions you want. It's also easier to modify the QBSCR routines
when they're right in your own program - you don't have to exit
QuickBASIC, load the library source, make your changes, recreate the
library and reload QuickBASIC with the new library.


To actually use the utilities, you again have a couple options. If
you don't care to declare the utilities in your own program (though
we've made it very easy to do so), you can simply make a CALL to the
particular utility you want. This requires 1) the CALL statement, and
2) the parameters must be in parentheses. Example:

CALL Center(ST$, Row%)

If you're like me, you don't like alot of CALLs cluttering your program
- you want it to look as "BASICy" as possible. You can use the
utilities without the call statements, making each look just like a
regular BASIC command. The parameters must not be in parentheses.
Example:

Center ST$, Row%

Saves on code size too. To do this, you must declare the SUBs and
FUNCTIONs from the utilities library that you use in standard declare
statements. Example:

DECLARE SUB Center(ST$, Row%)

This isn't difficult, but in case it bothers you, we've made it even
easier than this. With the package you should find a file entitled
QBSCR.INC. It contains all the proper DECLARE statements for the
utilities. To incorporate these into your program, simply add this
statement at the beginning of your code:

REM $INCLUDE: QBSCR.INC

When the compiler sees this "Metacommand" it will stop processing your
code and pick up QBSCR.INC. When it finishes with that file, it will
return to your source code and resume compiling where it left off. The
compiler must be able to find QBSCR.INC, so make sure it's on the same
drive/directory where QB is. Easy, No?

A note on the SAMPLE program. Since all the code for the SAMPLE
program is at the module level, you can run and compile this program
using either method. Use the command above, QB SAMPLE /L QBSCR and the
program will run or compile from the environment just fine. And
speaking of SAMPLE...


THE SAMPLE PROGRAM

Included is a sample program (SAMPLE.BAS) that demonstrates the
uses for all the utilities. It is thoroughly commented and tells you
purpose, usage and has some code for an example so you can see how it
works in real life.

The program can be run by loading it into QuickBASIC with the

QB SAMPLE /L QBSCR

command. The files QBSCR.QLB and QBSCR.LIB must be in the same
drive/directory that QuickBASIC and SAMPLE.BAS are in. Once loaded, you
can hit Shift-F5 to run it, or compile it to an EXE file. Whatever your
heart desires.

As you watch the program work (there are frequent pauses), follow
along in the SAMPLE.BAS source code to see just how things are working.



THE UTILITIES REFERENCE - HOW TO USE THEM

Here we will describe in detail (probably more than you care for)
how each of the utilities work. BASIC keywords are in UPPERCASE. There
will be two usages - one using the CALL statement, one without. All
references to rows of the screen are like standard locate statements -
row 1 is at the top of the screen and row 25 is at the bottom. All
references to color are just like BASIC - 0 through 15 for foreground,
and 0 through 7 for background. Also, you might note that there are
alot of integer values required here. This is for speed. PC's work alot
faster with integers than with real numbers, so integers were used
whenever possible.


SUB PROGRAM "Banner"

Purpose: To create a scrolling string of text on a given line of the
screen.

Usages: CALL Banner(ST$, Row%)
Banner ST$, Row%

Where: ST$ = the text string to center,
Row% = the row of the screen to put it on. Must be INTEGER.

Notes: When Banner is called, what happens is that the string passed to
it has all it's characters shifted one to the left, while the first
character goes to the tail end. The scrolling effect is achieved by
continuously calling Banner. Example:

ST$ = " This is a scrolling banner "
KeyPress$ = ""
WHILE KeyPress$ = ""
LET KeyPress$ = INKEY$
Banner ST$, 1
WEND

Unfortunately, you can only use this with one text string per program.
The routine requires a STATIC statement to hold it's place in the
shifted string, so the value won't change if you pass it another
string. This will be fixed eventually, we hope. It's kind of a freebee
anyway.

You can change the scrolling rate by changing the counter in the
delay loop in the source code. Increase it to slow the scroll, decrease
it or eliminate the delay loop altogether to speed it up.


SUB PROGRAM "Center"

Purpose: To center a string of text on any given row of the screen.

Usages: CALL Center(ST$, Row%)
Center ST$, Row%

Where : ST$ = The string to center,
Row% = The row of the screen to center it on. Must be INTEGER.

Notes: Nothing special. Example:


ST$ = "A string of centered text."
Row% = 3
Center ST$, Row%

This would center the text string ST$ on row 3 of the screen.


FUNCTION "ColorChk"

Purpose: To determine if the machine in use has color capability.

Usages: ColorChk
As a boolean variable. Returns TRUE (Non-Zero) if the machine can
display color, or FALSE (Zero) if it cannot. See example.

Notes: This function REQUIRES that you have a DECLARE statement in your
program for it. it would be:

DECLARE FUNCTION ColorChk ()

Otherwise, it will return false values. You can use it repeatedly as a
boolean variable, or set your own variable based on it's returned value
to avoid calling it so often. Example:

CONST False = 0, True = NOT False

Kolor = False
IF ColorChk THEN
Kolor = True
ELSE
Kolor = False
END IF

IF Kolor THEN
COLOR 15, 4
ELSE
COLOR 7, 0
END IF

Everytime you wanted to change the color of your screen, you could
issue a statment like the second IF...THEN...ELSE above, and change or
not change colors appropriately.


FUNCTION "MakeMenu%"

Purpose: To create a menu with a scrolling selection bar, and return a
value that is the number of the choice in the menu that was
selected.

Usages: As a function that is assigned to a variable, or whose value is
directly used.

VariableName% = MakeMenu%(Choices$(), NumberOfChoices%, Justify$,
LeftCol!, RightCol!, Row%, FG%, BG%, HFG%, HBG%)

Where: Choices$() = an array of text strings that contains the
actual menu choices.
NumberOfChoices% = the number of choices in the menu. The same
number as the number of elements in
Choices$. Must be INTEGER.

Justify$ = the type of justification of the menu
choices when displayed. See below for detail
LeftCol! = the left-most column to consider when
displaying the menu choices. Must be REAL.
RightCol! = the right-most column to consider when
displaying the menu choices. Must be REAL.
Row% = the row of the screen where the menu choices
will begin. Must be INTEGER.
FG% = the foreground color of a normal menu
choice. Must be INTEGER.
BG% = the background color of a normal menu
choice. Must be INTEGER.
HFG% = the foreground color of a highlighted menu
choice. Must be INTEGER.
HBG% = the background color of a highlighted menu
choice. Must be INTEGER.

Notes: While at first this seems like alot of stuff to worry about, a
second reflection shows how versatile all these parameters make it.
Let's consider each parameter separately to make things very clear. You
can name you actual variables whatever you want, or even pass constants
and literals instead. We'll refer to them by the names above for
clarity.

Choices$: This is where you store the actual text of the menu choices.
Say your menu choices consisted of "Begin program", "Open a file"
and "Quit". You would assign these strings to the array Choices$,
like this:

Choices$(1) = "Begin Program"
Choices$(2) = "Open a file"
Choices$(3) = "Quit"

NumberOfChoices%: This is how you tell MakeMenu how many choices it has
to deal with. In the above example, you would set NumberOfChoices
equal to 3. This value must be an INTEGER.

Justify$: Use this parameter to tell MakeMenu how to justify your menu
entries when it displays them on the screen. Possible values are:

"C" = Centered
"R" = Right justified
"L" = Left justified

Which brings us to the next two parameters...

LeftCol! and RightCol!: These contain the values of the left and right
most columns to display your entries between. If you wanted your
menu to be locate between columns 10 and 40, you would pass these
values and your menu choices would be displayed between columns 10
and 40, either centered, right justified or left justified,
depending on the value you chose for the Justify$ parameter. These
values must be real, as decimal division is performed on them.

Row%: This is the row of the screen where the first of your menu
entries is to be displayed. The rest will be displayed below it,
one to a line. This value must be an INTEGER.

FG%, BG%: These are the foreground and background colors of normal
(non-highlighted) menu choices. Normally, these values will be the
same as the foreground and background you are displaying them on.
These values must be INTEGERS.


HFG%, HBG%: These are the foreground and background colors of the
highlighted menu choice. In other words, the colors of the
scrolling menu selection bar. It is generally a good idea to make
this background color contrast with the background color for normal
menu entries, so you can easily see the selection bar. You might
try making the foreground color here different than the foreground
color of normal entries. You can easily tweak it to see what color
combos you like the best. These values must be INTEGERS.

Look at the SAMPLE program for an example of an actual use of MakeMenu.

From the user's viewpoint, operation is simple. Use the up and down
arrow keys to move the highlight bar up or down one space. If you're at
the top and go up, or the bottom and go down, the highlight bar will
wrap to the other end. You can use Home or PgUp to go to the top of the
list, or End or PgDn to go to the bottom. Once you have highlighted
your choice, hit Enter to select it.


SUBPROGRAM "MakeWindow"

Purpose: To display windows anywhere on the screen.

Usages: CALL MakeWindow(TopRow!, LeftCol!, BotRow!, RightCol!, Fore%,
Back%, WindowType%, FrameType%, ShadowColor%,
ExplodeType%, Label$)

MakeWindow TopRow!, LeftCol!, BotRow!, RightCol!, Fore%,
Back%, WindowType%, FrameType%, ShadowColor%,
ExplodeType%, Label$

Where: TopRow! = the topmost screen row of your window. Must be
REAL.
LeftCol! = the leftmost screen column of your window.
Must be REAL.
BotRow! = the bottommost screen row of your window. Must
be REAL.
RightCol! = the rightmost screen column of your window.
Must be REAL.
Fore% = the foreground color of your window. Must be
INTEGER.
Back% = the background color of your window. Must be
INTEGER.
WindowType% = the type of window you want to display. Must
be INTEGER. Valid values are 0 to 9.
FrameType% = the type of frame your window will have. Must
be INTEGER. Valid values are 0 to 5.
ShadowColor% = the color of the window shadow. Must be
INTEGER. Valid values are (-1) to 15.
ExplodeType% = controls the way a window is placed on the
screen. Must be INTEGER. Valid values are
0 to 3.
Label$ = a string that goes on the top line of the win-
dow as a label for it. Length of Label$ must
be <= (RightCol - LeftCol) - 4.

Notes: And you thought MakeMenu had alot of parameters! Seriously,
though, MakeWindow is the most versatile window utility I've seen yet.
A list of it's features include:

1) 10 different types of windows
2) 6 different frame types
3) Window shadows in any color, or none at all

4) "Exploding" windows, or not

We'll go over each parameter in detail so you know what's going on. It
may help to refer to the SAMPLE program to see a real-life example.

TopRow!, LeftCol!, BotRow!, RightCol!: These are the screen coordinates
of your window. The values must be REAL, as decimal division is
performed on them. The values include the window frame.

Fore%, Back%: These are the foreground and background colors of your
window. IMPORTANT NOTE! After MakeWindow executes, the colors you
specified in these parameters are now the defaults! If you need to
print in a different color than those supplied to MakeWindow, you
will have to change the colors with a COLOR statement right after
the call to MakeWindow. These values must be INTEGER.

WindowType%: This is where MakeWnidow gets to be 1) really useful, and
2) really fun. WindowType% is an INTEGER in the range 0 to 9 which
corresponds to the type of window you want to display. Below find a
picture of all the different window types. Note that if your
printer does not support the IBM extended character set (ASCII
128-255), they will not look right on your printer. You'll have to
view it on your screen to reference it.

WINDOW TYPES


Window Type 2

Window
Window Type 0 Type
4





Window Type 5

Window Type 1


Window Type 3


Window Window Type 7
Type
6



Window Type 8









Window Type 9


The size of the windows will change based on your window coordin- ates,
but the concept will be the same. The real power of this system is that
it's so easy to change a window if you don't like something about it.
Colors, type, location, whatever, by simply changing a single
parameter.

FrameType%: This parameter controls the actual lines used to make your
window. There are six valid types, 0 to 5, and are shown below.
Again, your printer must support the IBM extended character set, or
it will look like so much junk. Look at it on screen to reference
it.

FRAME TYPES





Frame Type 0 Frame Type 1 Frame Type 2








Frame Type 3 Frame Type 4 Frame Type 5





Note the differences. Type 0 uses all single lines. Type 1 uses all
double lines. Type 2 makes all vertical lines double, and all
horizontal lines single, while type 3 does the opposite. Type 4 has all
the outside lines double and all interior lines single, while type 5
has the reverse.

ShadowColor%: This parameter allows you to place a shadow on the right
side and bottom of the window, providing a "3-D" or floating
effect. A value from 0 through 15 will give you a shadow in that
color, while a negative value will not give you any shadow at all.

ExplodeType%: The value of this parameter determines how the window
will be placed on the screen. Valid values are 0 through 3,
described as follows:


Value Effect
----- -----------------------------------
0 Normal display - top to bottom
1 Exploding windows - AUTO mode
2 Exploding windows - horizontal bias
3 Exploding windows - vertical bias

A value of 0 will cause the window to be displayed as any normal
text - top to bottom (though it is often too fast to see a top to
bottom display, especially with small windows and faster machines.
It looks like it just "pops" on).

A value of 1 will cause the windows to "explode" or "grow" onto
the screen. Just run the SAMPLE program and you'll see exactly what
I mean. 1 also is AUTO mode. That is, it calculates its own
horizontal-to-vertical expansion ratio, so that the window expands
as evenly as possible. For example, if your window has a top row of
5, a bottom row of 10, a left column of 10 and and right column of
70, your horizontal-to-vertical ratio would be

(RightColumn - LeftColumn) / (BotRow - TopRow)

or

(70 - 10) / (10 - 5)

or

60 to 5

which reduces to 12 to 1 (12:1). Therefore the window would expand
12 columns to every row, causing the vertical and horizontal
expansion to reach their maximums at about the same time. The whole
point is to make the window explosion look as even and smooth as
possible.

Now if you want to achieve some other effect, there are two other
possiblities (beyond your modifying the source code to suit your
own needs). A value of 2 for ExplodeType% will provide a fixed
expansion ratio of 3 to 1 (3:1). This can be useful for very wide
but short windows, where it will provide almost a completely
horizontal expansion.

A value of three will give you a fixed expansion ratio of 1 to 1
(1:1). This is good for tall but narrow windows. Since rows are
much taller than columns are wide, this is highly biased toward
vertical expansion.

Label$: This is a short text string that can be displayed at the upper
left corner of the window, right along the top line of the frame.
Example:

Label$










Always allow room for two characters on either side of the Label$.
In other words, your maximum Label$ length should be

(RightColumn - LeftColumn) - 4

or the routine will not display the label you pass to it.


SUBPROGRAM "OffCenter"

Purpose: To center a text string between to off-center coordinates.

Usages: CALL OffCenter(ST$, Row%, LeftCol!, RightCol!)
OffCenter ST$, Row%, LeftCol!, RightCol!

Where: ST$ = the string to center.
Row% = the row to center the string on. Must be INTEGER.
LeftCol! = the leftmost column to center between. Must be
REAL.
RightCol! = the rightmost column to center between. Must be
REAL.

Notes: The best way to explain this function is to use an example.
Suppose you had just used MakeWindow to pop a window on the screen,
between columns 10 and 30. To center text in that window, you would use
the OffCenter subprogram, supplying the values 10 and 30 for the
LeftCol! and RightCol!, respectively. It would then center the text
with respect to those columns.


That's all there is to this set of utilities. It's really a decent
package if you're out to produce professional-looking programs. A few
easy calls and you've got a nice setup. One way to make sure the QBSCR
utilities are easy to use is to plan ahead how you want your screens to
look. Figure out the coordinates of where you want your windows, menus
and text. Then go to code it. A little planning will save alot of
frustration.

Use the SAMPLE program as a reference. It will help in showing you
real-life applications of the code, and how it works.

Lastly, feel free to modify the source code to suit your needs. If
you find you need another window type, add it! If you want a special
effect to go along with the utilities, add it in. For example, I
modified MakeMenu in one program I wrote so that everytime the
highlight bar was moved to a new location, MakeMenu called a short
routine and passed it the current selection, so that it would print a
short text description of that selection in a different window on the
screen.

These tools, combined with a little imagination and forethought,
will give your programs an impressive professional look, with very
little work on your part.