Shareware Overload/ShartewareOverload.cdr/database/litebr42.zip/LITEBAR.DOC

Text File | 1987-07-25 | 18KB | 444 lines

Documentation for LITEBAR v. 4.2
7/25/87

Copyright (c) 1987 R. Russell Freeland, Synergy Corp.


________________________________________________________________________________
                         -- Overview --
________________________________________________________________________________

LITEBAR is a BIN routine that can be used to generate quick menus
from dBASE III Plus.  Some of its features are:

o Very little overhead in terms of memory required

o Parameters taken from either memory variables or a text file

o Menus can be horizontal or vertical (or zigzag for that
  matter)

o Compatibility with Clipper, Quicksilver, FoxBASE+, and dBASE
  III Plus

o Up to 50 menu options can be displayed at once

o Colors are selectable (monochrome monitors will be sensed and
  color parameters will be overridden)

o Function keys can be trapped (optionally)

o Keys which are normally reserved for LITEBAR can be trapped and
  returned to the calling program

o Help prompts can be displayed anywhere on the screen

o The time can be displayed while LITEBAR is waiting for input

o LITEBAR can "remember" the last option that was pressed and
  highlight that option first the next time you call it

o Support for 43-line EGA mode

o turn on/off snow suppression (default is on for CGA)

o selectable "first option"

o Banners (only partially implemented w/this version)


Options that are likely to be added to LITEBAR:
______________________________________________

o Zoom windows
o Borders around windows
o Enhanced trigger key trapping options
o Enhanced error reporting
o Script files--this is a high priority, should make possible more efficient
  "pulldown" style menus

If you use this program, I would appreciate a contribution.  It started as a
tiny experiment but *many* hours have gone into its development at this point.
I suggest a $40 registration fee.  If you register, I will make the source
code available to you on the Synergy BBS.  You will also have access to the
full documentation, which reveals some of the "other" options detailed at the
end of this text.  Updates will be free if you download them from the BBS.
No "runtime" charges are necessary; pay your $40 and go.  This seems reasonable
to me, especially when I look at the competition.

Also, I will make available to registered users a smaller version without the
screen save buffers, which will reduce by at leat 8K the BIN/OBJ files' size.

***************** If you use this program commercially, registration is
***************** mandatory!!!

If you send $75 instead, you will be licensed for all Synergy utilities.
Synergy BINs are FOXBASE-, QS- and mostly Clipper-compatible and include:

SCROLL   screen window scrolling (left right down up), coloring, fading, bolding
SAVER    screen save/restore, write to disk, read from disk, etc.
DISKSPAC free space any disk--returns error for drive not ready
CD       get current drive/directory
ENCRYPT  encrypt/decrypt strings
SRCHPATH search DOS path for file
FINDFL   find all files matching a wildcard, return all directory info
NETINFO  get net name (more to come)
MEMCHECK check memory on the system, also how much when dBASE was loaded
DIREXIST check existence of drive/directory
FSIZE    get size of file(s)
CHATTR   change attributes of (files)
SAT      SuperAt(), find every occurrence of a substring in one CALL
HANDLES  Get *true* amount of available file handles
RAND     Random number generator
IN/OUT   Port access
LBMRD    Litebars using UI's MRD.
SOUNDEX  get SOUNDEX codes
DELAY    delay specified number (and fraction) of seconds
VALDRIVE find out all valid drives on system
EQUIP    find out what equipment you're running on
GETCOLOR find out what the color is on the screen now (at cursor position)
SINE/COSINE/TANGENT etc.

...and many more.  Also startup code for C compilers to write your own BINs
in C is coming soon (in Beta now).  Sign up now, the price is going up as soon
as I crank out some more <grin>.

Synergy also will make available a parameter-generating program to make creation
of LITEBAR menus easier.  A rudimentary version written in dBASE is available
now.  This program (LBGEN.PRG) is will be an example of how to use LITEBAR as
soon as I comment it <grin>.  In the meantime, it is available to make
generation (and modification) of menus easier.  It only generates text files
for input to LITEBAR at this time.  In the ARC with this file there should be
an LBGEN.ARC that has a demo version of LBGEN and some rudimentary documentation
for it.  The demo version is limited to three menu choices, and is encrypted
using DBC.
________________________________________________________________________________

dBASE III Plus(tm) is a trademark of Ashton-Tate
Quicksilver(tm) is a trademark of Wordtech
Clipper(tm) is a trademark of Nantucket
FoxBASE+(tm) is a trademark of Fox Software
WordStar(tm) is a trademark of Micropro International

These are all (relative to me) huge corporations who could sue the living
beejeezus outta me, so I thought I'd just mention that stuff.


________________________________________________________________________________

Disclaimer:

This program has been tested rather thoroughly by many people.  It is "lean
and mean" which means it will run totally amok, crashing and burning, if you
misplace a comma in a parameter.  This is my method of getting you to register,
so you can get the generation program <grin>.  If it doesn't look "lean"
in size, that's because there is 8K in screen buffer built in and 6K of Litebar
parameter buffer.  LITEBAR will not trash your FAT, format your
disk, corrupt memory, or any other really bad things.  But....if you manage to
do any of those things I will:

1) Swear that LITEBAR is not responsible.
2) Claim no responsibility in any case.
3) Not refund your money (if you sent any).
________________________________________________________________________________

Well, now that all that's oughtta the way, here's the documentation:
================================================================================

________________________________________________________________________________
                       -- General Usage --
________________________________________________________________________________


LITEBAR is presently offered in two forms: as a BIN file for use
from dBASE, FoxBASE+, and Quicksilver, and as an OBJ file to be
linked to Clipper- or QS- compiled applications.

From any environment but Clipper, the syntax is:

LOAD LITEBAR
CALL LITEBAR WITH <parameters>

In Clipper, the same syntax is used except that the file need not
be LOADed, since it is already linked into the compiled EXE
file.  If you wish to use the OBJ code for QS instead of the BIN file,
use CCALL instead of CALL.

The procedure for linking LITEBAR to your compiled
application is:

o First compile the application into OBJ code.
o At the LINK step, add LITEBAR to your list of OBJ modules for
  LINK (or PLINK86)



________________________________________________________________________________
                       -- Parameter Options --
________________________________________________________________________________


There are many types of of parameters that can be passed to LITEBAR.  The basic
parameter list is preceded by optional "switches".  The switches must be
separated from the actual parameters by  the character "/" (not optional).  All
switches and parameters are concatenated into one character variable to be
passed to LITEBAR.

The first parameter after the separating "/" character must always consist of
two attributes for color.  The first attribute is the color of unhighlighted
menu options, the second is that of highlighted menu options.  They are
separated by a commas, and followed by a comma.  The colors are specified as
decimal screen attributes.  If you are a registered user you will receive a
program that allows you to pick from a grid of screen colors, otherwise refer
to the installation program for Sidekick, Superkey, QEDIT, etc.

Each menu option is added to the passed parameter in the following format:

Option row,option column,option text,"\",option trigger key

For instance, to display a menu option at row 10, column 24 with text
"this is a test", the parameter string could include the variable moption_1
where moption_1 is defined as:

moption_1="10,24, T)his is parameter one \T"

The trigger key for this option is "T".  Lower case T will be converted by
Litebar to a capital.



Let's do a simple Lotus-style menu at the bottom of the screen:

low_high='112,111,'   && should work on mono monitor w/no override
mchoice1="24,0, T)his is a demo \T"
mchoice2="24,30, O)f litebar version \O"
mchoice3="24,70, 4).0 \4"

mchoice="/"+low_high+mchoice1+mchoice2+mchoice3
LOAD litebar
CALL litebar WITH mchoice

Now to add help prompts, we'll change a few things.  First of all, we need to
tell LITEBAR we're sending help parameters.  This is done with the "H" switch.
We'll add a memvar called "switches", and then add the help prompts to each menu
option:


switches="H112,/"      && 112 is the attribute to use for erasing help
low_high='112,111,'
mchoice1="22,0, T)his is a demo \T\24,30, Help for option 1\"
mchoice2="22,30, O)f litebar version \O\24,30, Help for option 2\"
mchoice3="22,70, 4).0 \4\24,30, Help for option 4\"


mchoice=switches+low_high+mchoice1+mchoice2+mchoice3
CALL litebar WITH mchoice


Continuations:

When you want to send a parameter to LITEBAR that exceeds 254 characters in
length (dBASE doesn't allow strings > 254 bytes in length) you may break up the
string into parts and append a semicolon to the end of each part (with the
exception of last part).

Example:
m_param1 = "<whatever>"+";"
m_param2 = "<whatever>"

CALL LITEBAR WITH m_param1

(LITEBAR will return into the first character of m_param1 a CHR(2)
to indicate that it is waiting for more input.)

CALL LITEBAR WITH m_param2

It is easier in many cases to just put the parameter into a text file
(see below).  The quickest way to use memvars for long menus is to
keep them in a memvar file, but to edit them is a pain unless you
keep the code around that you used to create them.




File input:

To tell LITEBAR to read its parameter from a file, just pass "F"+filename.
There may be a little trouble if you don't have enough EOF marks at the end of
the file.  If you're having trouble with this option, try another text editor
(EDLIN should do it, WordStar is ideal).  Subsequent versions will probably fix
this problem.

"Memory" option:

If you just pass a CHR(255), LITEBAR will "remember" the last passed param
and key pressed, and resume with the last selected item highlighted.


________________________________________________________________________________
                       -- "Switch" Options --
________________________________________________________________________________

There are many switches which can be sent to LITEBAR.  They should
all precede the separator character "/" (in any order).  They are:

o Help char and attribute --"H" followed by an ASCII decimal string (attribute)
  denotes that there will be help prompts.  The help text follows the
  option trigger, separated by a \, starts with the row and column as with
  option text, and ends with a backslash.  There must be separate help prompts
  for each option string.  The help attribute should match the background color
  of the screen as this is the color that the help will be "erased" with.
  (You can use GETCOLOR.BIN to get this attribute if you're a registered user
  of Synergy Utilities.)

o Function key trapping -- pass a "K" in the flags string--LITEBAR will trap
  all function keys, returning CHR(4)+CHR(x) where x is the function key
  pressed.

o Trap extra keys--you may pass "O"+scan code, scan code, etc.+"O"
  to LITEBAR and it will trap those keys before it checks any other keys,
  returning a CHR(3)+CHR(trapped scan code) much in the same way as the
  function key option returns CHR(4)+CHR(number of function key)
  Example: "O75,77O" says trap the left and right arrow keys and return
  CHR(3)+CHR(75) if left arrow key is hit.  This enables you to trap
  PgUp, PgDn, left and right arrows, etc. for special use.

o Time display -- "T0,6," gives time display at 0,6 in the same color as the
  unhighlighted menu options.

o Force CR -- pass "E" (Enter) in the switches.

o Return whole string of option selected -- pass "V" (verbal).


In most cases, LITEBAR returns the trigger key you pressed.  If my rudimentary
error checking finds a problem, you get CHR(1) instead.  A continuation
character at the end of the passed parameter should get you a CHR(2).  If you
specified the "V", "O", or "K" options you should get the return value described
above.  See the demo programs for more details.


________________________________________________________________________________
                        -- keys trapped by Litebar --
________________________________________________________________________________

Litebar will trap some keys internally for its own use, unless otherwise
specified (with the "O" option).  They are left- and up-arrow (previous option),
right- and down-arrow (next option), Home (first option), End (last option).

Keys which (should) always return from Litebar are: Enter (Return), whatever
trigger key is specified (unless the "force CR" option is specified), and the
Escape key (returns CHR(27)).  Other keys can be trapped with "K" or "O" as
described above.

________________________________________________________________________________
                           -- "Other" Options --
________________________________________________________________________________

To consolidate a little, I built in most of the options from SCROLL3.BIN
(available to registered Synergy Utility users) and SAVER02 (available to
just about anyone with a modem).  I also threw in a few extras.

If you register this program, you can download the full documentation which
describes how to use the additional parameters (optionally you can figure out
*some* of them from looking at the demo programs <grin>).

The added functions include:

o  Window hiliting:  highlight all text in a window (leave color)
o  Window fading:    opposite of above
o  Window scrolling: up, down, left, right, any color
o  Window coloring:  color windows but leave text intact--you can "hide" and
                     "unhide" text this way if you're devious like me
o  Window blanking:  any color
o  Screen save/restore: up to two screens in memory, others can be read/written
                         from/to disk files
o  XOR bits:         XOR any bits for any window, which allows fading,
                     highlighting, blinking, color masking, etc.
o  OR bits:          Same as XOR but sets bits on instead of reversing them
o  Cursor on/off:    It was in there anyway, why not?
o  Junk a window:    Just for me <grin>
o  Dissolve text:    Also mostly for me, but it might be useable
o  Zap text
o  "Cloning"         "Clone" LITEBAR with a coupla screens and a menu built in!
o  Banners
o  Programmable "first option"

Anyway, I hope you enjoy the program; I worked hard on it.  If you have any
suggestions for improvements, drop me a note or leave Email on Compuserve.
Enjoy!

RRF

PS:
___
My phone number is not included here because I'm tired of answering
support calls for non-registered users.  Even for registered users,
$20 does *not* buy any support.  If you're reasonable, I will attempt to
support the product (in this case *I* define reasonable <grin>).  This is
*not* a product for beginning computer users, gang.

________________________________________________________________________________


LITEBAR order form:

send to:
R. Russell Freeland
Synergy Corp.
1780 SW 43 Ave.
Ft. Lauderdale, FL 33317
Compuserve: 76146,371

Yes, I am impressed with the incredibly cheap and versatile LITEBAR 4.2
so much that I want to register the product.  I enclose ($40) __________.

or:

Yes, I agree, LITEBAR only crashes and burns when you misplace a comma. I
am so impressed with the honesty of your documentation that I want to register
for the whole set of Synergy utilities.  I enclose ($75) ________________.

Check one (√):

 1) Just set me up on your BBS and give me the number.  I can download without
     any help from the likes of you.  Leave me a message on Compuserve with
     the password and BBS number.

 2) Set me up on your BBS. I don't like Compuserve or I use it too compulsively,
     send me a postcard or something with my password and the BBS number.

 3) I could care less about your stupid BBS.  Just cash the check and buy some
     groceries.

 4) I don't have a modem.  Send me the source code and expanded documentation
     (for whatever I filled in above) on disk.  I include an extra $5 for this
     service.  My machine uses (√):

        ___ 3.5 inch diskettes, 720K

        ___ 5.25 inch diskettes, 360K

        ___ 5.25 inch diskettes, 1.2M or 360K

        ___ Some other bizarre disk format that you're gonna have real trouble
            duplicating.

(If you are one of those unfortunate souls without a modem to your name, please
don't expect second-day air delivery.  Strange as it may seem, I do have to
work for a living <yuk> and it'll take at least 2 weeks to get a disk out
around here.)

Name:_______________________________________________________________________

Company:____________________________________________________________________

Street Address:_____________________________________________________________

City, State, Zip: __________________________________________________________

Compuserve number:____________________

Phone:__________________________________________________   Comments:____