CD Actual 15/CDACTUAL15.iso/cdactual/program/basic/PULDOWN.ZIP/INTRO.DOC

Text File | 1991-07-11 | 11.0 KB | 249 lines

                       ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
                       █ PULDOWN MANUAL █
                       ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

                        WHAT IS PULDOWN?

PULDOWN is a programming tool that generates customized menus for QB programs.
The generated menus function in essentially the same way as the QuickBASIC
menu, as demonstrated by running DEMO.BAT, and can be used either in the
QuickBASIC environment or in a compiled program.

                    WHY THE QuickBASIC MENU?

If you're reading this, you must be a QuickBASIC programmer, and chances are
that--like me--you love QuickBASIC, and have come to recognize that the
QuickBASIC menu may well be the ultimate in keyboard driven menu systems
for power, flexibility and ease of use. And, it's as handy with a mouse
as you can wish. Chances are that even if you've been using QuickBASIC for
a long time, you're still not aware of all the capabilities of its menu
system. I know I wasn't until I started writing this program.
In addition, the QB menu is part of the standard Microsoft menu family,
which has become the leading standard in the DOS world, and the only
standard in Windows.

                           WHY PULDOWN?

PULDOWN is written in assembly language, and you just can't touch that
for speed and compactness. PULDOWN.LIB, the compile module, is a mere 4.4K.
In QB, it would probably take 30K or more, in C, 20+. And I've tried to make
PULDOWN as easy to use as possible--there's not a single command or argument
name to memorize.

                              AND IT'S FREE

And it's free. Not cheap, mind you--it cost me plenty in time and aggravation.
Why do I give it away? Because I love doing this. I'm an amateur programmer,
and trying to get money for it would spoil the fun.

                          IS PULDOWN TOO MUCH?

It can be. Puldown is a heavy-duty menu system that can put well over 500
second-level menu items on the screen. Not that anybody would want to--
anything over 40-50 gets too cumbersome to be useful. PULDOWN is meant for a
menu with 4-7 first level items and 20-50 at the second level. That's for a
program of at least medium complexity. If your program doesn't need to select
between more than a total of 6-8 menu items, you might be better off skipping
PULDOWN.

                          ONLY ONE KIND OF MENU?

Yes. Unlike some other menu generating packages, you only get one kind: the
kind that sits on a bar at the top of the screen. You don't get menus that
play hide-and-seek all over the screen, or explode, or make funny noises.
If you don't need that kind of menu--and you certainly don't when you use
QB or most other modern software packages, then PULDOWN is for you.


                          WHAT FILES DO YOU NEED?

This package contains 7 files. It is important for you to know something
about them, and which of them you may need:

        MAKEPUL.BAS is the program that generates the QB code for calling
        the PULDOWN function. This is where you tell PULDOWN what your menu
        will look like and what it will contain.

        TUTORIAL.BAS is a sample QB program. It has extensive comments and
        step-by-step instructions. You can use it as an alternative to
        MAKEPUL to create your menu, or as a reference.

        PULDOWN.QLB is a QuickLibrary file that contains PULDOWN's "engine".
        It is useful only when a program that uses PULDOWN is running in the
        QuickBASIC environment.

        PULDOWN.LIB is essentially the same as PULDOWN.QLB. It is a "library
        module" that is used when a QuickBASIC program is compiled to
        an EXE file.

        PULDEMO.EXE is a standalone program that demonstrates what PULDOWN
        does. Its source code is essentially the same as that for
        PULDOWN.BAS + PULDOWN.QLB/LIB, but it is entirely in asm. Please
        activate it with DEMO.BAT, at least the first time.

        PULDOWN.OBJ is the object file from which PULDOWN.QLB/LIB derive. It
        is useful only when PULDOWN needs to be linked to other library
        modules (If you're not sure what that means, then you need not worry
        about it anyway)

        INTRO.DOC is this file.


------------------------█████ ESSENTIAL: █████--------------------------------

Whenever you work with PULDOWN, you must load QB thus:

                qb /l puldown

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

                            GETTING STARTED

The quick start is to copy: MAKEPUL.BAS, PULDOWN.QLB, PULDOWN.LIB to your
QB directory. Load and run MAKEPUL.  The use of this program is self evident,
but you may need one run-through to see what it does. Don't sweat any
mistakes, there are editing and redo provisions. And if the final product
is not to your liking, just run it again.

MAKEPUL will create a text file, PULDOWN.INC, which contains all the
necessary QB code, declarations, variables, etc. All that you need to do
is to incorporate the file into your QB program--MAKEPUL gives more details
on that.

PLEASE NOTE that MAKEPUL will give its output file the same name every time.
That means that if you create a second, different menu, the include file for
the first menu will be overwritten! Presumably, by then its contents will
have been copied to your program, but if you wish to avoid overwriting it,
either rename the first include file, or change the name of the output file
in the source code.

Once MAKEPUL.INC's contents are in your program, PULDOWN is ready to run in
the QB environment or to compile (provided you've loaded with  L/PULDOWN).
But one more step needs to be taken to make it useful: PULDOWN appears in
the QB code as a function named PULL that returns the value RETVAL%, an
integer number. It is this number that tells your program what menu item
was selected, and it is your job to write the code to sort this out.
An example of how to do it can be found in TUTORIAL.BAS.

RETVAL can have one of four different kinds of values:

        1. The first kind consists exclusively of the number 1. This means
           that the user has pressed ESC and exited the menu without taking
           action.

        2. The second range is 64 to 90. This means that Ctrl+Char has been
           pressed. 65 through 90 are normal ascii codes: A-Z and a-z.
           64 means that a non-letter character has been pressed with Ctrl.

        3. The third group includes 159-168. They represent the function
           keys F1-F10.

        4. When RETVAL is greater than 168, it represents the address of the
           menu item that was selected. PEEKing RETVAL will produce the actual
           menu item.


Details on and examples of all of the above are provided in TUTORIAL.BAS.
You can cut and paste the relevant code into your program and adapt it.
Search for RETVAL%.

                            ALTERNATIVE METHOD

Another way you can generate a custom menu is to use TUTORIAL.BAS instead of
MAKEPUL. (Or you can, indeed, use a combination of both). The advantage of
MAKEPUL is its much greater ease and speed. But it does have some
limitations. For example, it limits the number of items in a pull down
menu to eight, and, if you run it in a mono system, it will not let you
choose the colors. TUTORIAL.BAS, on the other hand, has the advantage of
explaining what's going on, and is a working, though minimal, program. So
that you can simply lift it or parts of it into your own code.

                               MOUSE NOTES

PULDOWN 2.0 is equipped with cat whiskers to detect and catch mice. Its mouse
functions are extremely simple: a left click will select and activate an item.

                             PROGRAMMING NOTES

PULDOWN stores pull down menu items in a 1000 byte buffer, which sets an
upper limit to the number of characters and spaces that can be used in the
pull down menus (the bar menu items have their own storage, and are not of
concern). It's unlikely a program would push this limit, but a formula for
figuring out the fit is in TUTORIAL.BAS.

The Int 9h (keyboard) vector is hooked while PULDOWN is active in order to
trap the Alt key. The interrupt is momentarily diverted, and then returned
to its proper handler. A TSR that also hooks Int 9h should not be a problem,
but if one does arise, this is a good place to look.

If your program sets up a mouse handler prior to invoking PULDOWN, you should
know that PULDOWN disables any existing mouse handlers, saves the state, and
restores it upon exit. A save state buffer is used that should be large
enough for all contingencies, but if mouse conflicts occur, the fault may lie
here. Let me know.

                              COMPATIBILITY

PULDOWN has been tested on XT clones, a 286 and 386 system, and with DOS 2.1
to 3.3. That's only a fraction of the possible machine/OS combinations, but
so far it's worked wherever it's been tested.

PULDOWN is designed for QuickBASIC (version 4.5 to be specific). I don't know
whether it will work with older QuickBASICs or with BASCOM, or with the MS
BASIC Professional Development System, but I'd like to find out.

It WILL NOT work with BASICA or GWBASIC. I have no reason to think it will
work unmodified with Turbo/Power BASIC or other non-Microsoft BASIC
compilers, but if anybody wants to try to adapt it, I'll be glad to cooperate.

                               WINDOWS?

An application using PULDOWN menus can run in Windows 3.0 in a DOS box.

                                 BUGS?

If I thought there were any bugs left in PULDOWN, I wouldn't have published
it. But I am no less fallible than Lotus or Microsoft. If you run across a
bug, please accept my apologies and let me know. I will fix it if it is
fixable.

                              WHO TO BLAME

If you wish to contact me regarding a bug, or any other aspect of PULDOWN,
write to or call:

                Albert Duro
                MAYAM Productions
                509 Alvarado Street
                Brisbane, CA 94005

                415 468-2155
                415 467-2060
                FAX [phone]

                Compuserve: 73757,2167 (I usually hang around IBMPRO)


                               LEGALITIES

PULDOWN is copyrighted, and I retain rights to it.
PULDOWN may be freely used by anyone to develop non-commercial software.
PULDOWN may be freely distributed, so long as the distributor does not charge
any fee for it, other than to cover the costs of distribution and not in
excess of $10 per copy.
PULDOWN may be used in the development of commercial software only with my
permission.
PULDOWN is offered as is. Anyone who uses it does so at their own risk. It is
not guaranteed to be free of errors or to work on any particular system. If
you use PULDOWN, you agree to these terms.


                           A WORD TO MICROSOFT

Yes, PULDOWN is a blatant and precise rip-off of the look-and-feel of the
QuickBASIC menu system. It is meant as sincerest flattery. Please don't sue
me.