THE NEW HB ALL-PURPOSE LIBRARY

FOR POWER-BASIC PROGRAMMERS

INTRODUCTION AND DOCUMENTATION





Version 2.00000 // SPRING - SUMMER 1990


==================

This is my custom routines library, a set of procedures etc. that I have
written over a few years time, mostly for my own use in database programs
and my custom dos shell. Also I include a do-nothing program intended for
demonstration and development of the functions in the library; this also
contains detailed how-to instructions (embedded as remarks) to help other
programmers use the various library features.

FEATURES:
------

MAIN MENUS ACROSS TOP OF SCREEN AND PULLDOWN SUBMENUS -- WITH
STANDARD KEYBOARD AND MOUSE CONTROL INTERFACE.

POP UP AND VANISH MENUS AND DIALOG BOXES, ANYWHERE ON THE SCREEN

INPUT ROUTINES FOR TEXT FIELDS, NUMBERS, DATES ETC. W/ FULL EDITING --

SPECIAL DATE ENTRY ROUTINE THAT "SCROLLS" THE DATE FORWARD OR BACK
(starting for example with the present date) USING ARROW KEYS

FULL DATE ARITHMETIC BACK TO 1900. SPECIAL AGE FUNCTION.

POP-UP DATA ENTRY WINDOWS -- CURSOR OR TAB BACK AND FORTH FROM
FIELD TO FIELD

ROUTINES TO GET DISK, DIRECTORY AND SYSTEM INFO DIRECTLY FROM DOS

ALL IN BASIC FOR RELIABILITY AND EASY MAINTENANCE

NOW USES SEPARATELY COMPILED POWER-BASIC UNITS.

NOW SAVES SCREENS DIRECTLY TO MEMORY
(used to need a ram-disk, but no more)


THE FILES AND WHAT TO DO WITH THEM
============================


AP-LIB DOC The file you're reading now, part of the doc.

APL-QREF BAS A quick ref guide. I can keep it handy in the Pick
List for quick access (Alt-F3)


HBDEMO BAS This is the demo. Compile it to an EXE file using
Power Basic and you'll see all the tricks these
units and utilities can do. Also contains most of
the real documentation for the various procedures
& functions (as comments).

DEMO SW The SW files are screen design files for Static
DEMO INC Windows (display text & data but no user entry).
ENTERDEM SW The INC files are the result of processing them
ENTERDEM INC through the SWW.EXE utility (see below)

PWDEMO INC PW files are design files for PopWindows -- data
PWDEMO PW entry windows. PWW made them into INC files.

SETUP-H BAS Header that has to be $INCLUDEd in a program that
uses the AP Library

BOXES-U BAS |
FENTRY-U BAS |
FIGDAT-U BAS | The units comprising the library.
INIT-U BAS |
MENUS-U BAS |
MISC-U BAS |

HBDEMO PV When you have Power Basic units with a lot of
variables you declare as EXTERNAL (i.e. global),
each of them must appear in a PUBLIC statement in
your main program. I have a utility, PUBVARS, which
automatically reads your main program, detects unit
names, reads the units and makes you a neatly sorted
list (uses the new ARRAY statements) of PUBLIC vars.
All the main prog. has to say is "$INCLUDE HBDEMO.PV"

PUBVARS BAS | THREE UTILITIES: PWW and SWW are code generators
PWW BAS | that create *.INC files for opening the two types
SWW BAS | of data windows -- one for entry, one just to
COLORSET.BAS | display data (see above). PUBVARS is expained
| above. NOTE: if you're missing any of the INC
| or PV files, these utilities will recreate them.
| (Of course the best part is that you can modify
| your windows all you want and just reprocess
| them to get a new display.)
|
| COLORSET automates the process of using command
| line switches to reset the colors of the Demo
| (or any PB program that uses the SetColors
| routine). Start it and follow directions!
| (Thanks to Barry Erick of Spectra support for
| giving his OK to recycle his color selector
| procedure as the kernel of COLORSET.)


The program no longer needs a RAM-Disk to save temporary files to!
Thanks to the new PB functions PEEK$ and POKE$, screens can be quickly
saved to regular memory space. See SCREENPUSH and SCREENPOP.

There is still an initialization procedure (INIT-U.BAS) which sets
itself up for any monitor and several types of printer. Works on Mono,
CGA and EGA at least. Please note that I have only briefly tried the
current version out on a Mono system to see if the COLOR statements are
OK, since I don't have one handy any more.

Many of the SUB procedures -- and even subroutines -- in the old library
(which was to be $INCLUDE'd, of course, in a TB 1.1 program file) have
now become true FUNCTION's because that was their true nature. (Shades
of "C" ! ) Also ... colors are handled differently (as a single integer)
and can be altered from the command line by command line switches.
I have a program to generate same, but it's not ready for PB 2.0 yet.


So this is what I have so far, if anyone is interested. It works and I
like it so far. I'll be working on it more, of course, and once it's
improved I'll do another upload.


A NOTE ABOUT STYLE: You may be horrified at my use of GOTO and GOSUB in
================== these files. Sorry! I don't like puzzles, I don't care
for C, and I see no reason to use contrived outer loops and
unnecessary flag variables to avoid a simple, clear and self-evident
jump (e.g. GOTO FileSubMenu). And why, I say, incur all the overhead
of a SUB procedure, with a ton of SHARED variables to pass, and no
local variables at all ... when a GOSUB / RETURN stucture is faster
(maybe measurably, maybe no) and does the job perfectly for me and
you.


' ============================================================================


QUICK REFERENCE FOR HB'S ALL-PURPOSE LIBRARY:

>>>>>>>>>>>>> in SETUP-H.BAS <<<<<<<<<<<<<
DEFINT statement; %False, %True, Register Names and other named const.
DIM statements
... etc.

>>>>>>>>>>>>> in INIT-U.BAS <<<<<<<<<<<<<

SUB Initialize (PrinterType) PUBLIC (reads hardware, sets printer codes etc.)

>>>>>>>>>>>>> in FENTRY-U.BAS <<<<<<<<<<<<<

SUB ENTERSTRING (Wkg$,FLength,Opt$) PUBLIC | These are the Formatted
SUB ENTERNUMBER (Wkg#, Masq$, Opt$) PUBLIC | Entry routines
SUB ENTERDATE (A$, Opt$) PUBLIC |
SUB RotaDate (D$,Opt$) PUBLIC |
SUB ENTERTIME (A$, Opt$) PUBLIC |
SUB ENTERSSN (A$, Opt$) PUBLIC |
SUB ENTERPHONE (A$, Opt$) PUBLIC |

SUB PressAKey PUBLIC Displays a little box that says Press A Key
If you have mouse, says you may also Click

FUNCTION GetYesOrNo PUBLIC Prints "y/n" and waits til you answer with
an appropriate key or mousebutton (Left = Yes)

SUB ENTERYESNO (Yes) PUBLIC Prints a field with a Y or N in it; press
Y or N or [Enter]. Used in data entry windows.


>>>>>>>>>>>>> in BOXES-U.BAS <<<<<<<<<<<<<

SUB BOXMESSAGE(CornerLin, CornerCol, Margin) PUBLIC
SUB BOXMESSAGE2 (CornerLin, CornerCol, Margin, I$(1), Items%, Maxx) PUBLIC
(prints a box, with lines of text you specify in it.)

SUB POPWINDOW PUBLIC
SUB PWSetUp (Fld$,Z) PUBLIC
(prints a window with entry fields in it and
readies it for data entry)

SUB QBOX (L, C, Lines%, Message$, AnsFldLength) PUBLIC (one-field dialog box)

>>>>>>>>>>>>> in MENUS-U.BAS <<<<<<<<<<<<<

SUB TOPMENU (Lines% ,Choice, TLine$) PUBLIC
Top of screen menu; select with letter
key, cursor and CR, or click and
pull-down with your Furry Friend.

SUB POPMENU (TopKey$,MenuRight,MenuDown,Choice,MLine$,MCode$) PUBLIC
(retained only for compatibility with old code)

SUB SUPERMENU (MenuData$$ (), MenuRight, MenuDown, Choice, Title$, Ky%) PUBLIC
Regular moving-bar menu with mouse or keybd selection,
optional pulldown style or multipage styles, optional
help lines that appear in line 25.

>>>>>>>>>>>>> in FIGDAT-U.BAS <<<<<<<<<<<<<

FUNCTION FigDate&(A$) PUBLIC convert a date to a "Julioid" long-int
FUNCTION WriteDate$ (W&) PUBLIC convert the other way
FUNCTION WkDay$(W&) PUBLIC what day of the week is a given date
FUNCTION YearsSince (D0$) PUBLIC how old is a client born on D0$

FUNCTION FlipDate$ (WrittenDate$) PUBLIC rearrange date for sorting
or indexing (e.g. 900829)
FUNCTION UnflipDate$ (FlippedDate$) PUBLIC unrearrange date

>>>>>>>>>>>>> in MISC-U.BAS <<<<<<<<<<<<<

SUB SCREENPUSH PUBLIC |
SUB SCREENPOP PUBLIC | screen save & restore
SUB RestoreDOSScreen PUBLIC |

SUB PRINTLINE (L$) PUBLIC (fancy printer control -- keep track of pages etc.)

SUB FileFunctions (MenuRight, MenuDown, Choice$) PUBLIC
(A smart Menu that gives choices like SAVE, FIND, CLEAR --
but only as applied to the field cursor is on)

FUNCTION IsBlank (W$) PUBLIC (is W$ a nul string or nothing but spaces?)
FUNCTION GetAttr PUBLIC (what is the color at the cursor ??)
FUNCTION IsRodent PUBLIC ' finds if you have a rodent and also resets it
SUB Mouse(MV1, MV2, MV3, MV4) PUBLIC
FUNCTION GetCurrentDrive$ PUBLIC
FUNCTION GetCurrentDir$ PUBLIC
FUNCTION GetFreeSpace! (Drv$) PUBLIC
FUNCTION ReadParamFor (A$) PUBLIC ' this reads parameters from the command tail
SUB ClearLine PUBLIC
SUB DirFirst (F$, FileSize&, DateCode&, TimeCode&) PUBLIC
SUB DirNext (F$, FileSize&, DateCode&, TimeCode&) PUBLIC
FUNCTION DecodeDate$ (DateCode&) PUBLIC
FUNCTION DecodeTime$ (TimeCode&) PUBLIC


===============================================================================


SUB BOXMESSAGE(CornerLin, CornerCol, Margin) 'Boxes and displays your message.
==== Top L. corner will be at the designated coordinates,
but errors are trapped so box will stay on the
screen regardless. The message line should appear
in your code as DATA statements, terminated by
"END". A RESTORE statement is needed, of course.
See HBDEMO2.BAS for examples & comments.


SUB ENTERSTRING (Wkg$,FLength,Opt$)
======= This routine provides a field at Ln, Col for the operator
to enter data into. Wkg$ is the current value of the field.
FLength = length of field. Opt$ may be "" or may hold
the strings "Cap" for all uppercase, "Auto" for automatic
entry when full, "UpOut" or "BackOut" if UpArrow or Left/
backspace keys are to be able to end entry.
On exiting sub, Opt$ may be reset as Left, Auto, Up, Down, ESC or CR.
At any time during string entry the operator can press [CR] or DOWN-
ARROW to enter; [F2] is pressed for Database Function commands
(Clear, Find, Next/Prev, View Notes, Save) implemented below ...
not to mention the groovy pop-up data entry windows ...
2-4-89: Now supports: Ins default (in Opt$), ^Y, ^T, and ^Arrow
Negative numbers not allowed unless Opt$ includes a "-"


*** HOW TO USE SUPERMENU ***
===================

MENU SETUP: THE MenuData$$ ARRAY:
Each choice on your menu is represented by one string element in
this array. The decription of each choice -- for example, "LOAD",
will start with the third character of this string. If you are
specifying the hot-key for each choice put it into the first
character -- set MenuData$$ (1) as something like "L LOAD". To let
the software number or letter the items in order for you, set
MenuData$$ as just " LOAD". (If there are <11 items, numbers
are used rather than letters.) After the last menu item, you
must set the next array element as "END".
PASSING HELP LINES TO MENU: Set MenuHelpLine$() to contain lines (up
to 80 chr long) to appear at screen bottom whenever the
corresponding menu choice is highlighted.
POSITION OF MENU ONSCREEN ETC.: MenuRight moves it right or left -- 0
is top center. MenuDown moves it -- you guessed it! Errors will be
trapped. Vertical centering is gotten by setting MenuDown = 25.
Usually set Choice = 1. Title$ is title of menu.

*** AFTER MENU ROUTINE: Choice will hold the choice #. Title$ reset to "".
MKeyPressed$ if the actual key used (if mouse was used it
simulates the CR key, i.e. CHR$(13)) -- or if [ESC] or a legal
function key was pressed it contains "ESC", "PgDn", "PgUp", "F1",
or "F2".


THIS IS INTENDED AS A DEVELOPMENT TOOL FOR PROGRAMMERS. IF YOU LIKE IT,
PASS IT ON.

Your feedback is welcomed -- write to 2097 7th St. in
Oakland, Ca. 94607 -- or via the CompuServe PCVENB
Forum (# 71121,776), or Pro-Net or MOE in the Bay Area.

-- Howard Ballinger