Shareware Grab Bag/Shareware Grab Bag.iso/007/baswind.arc/BASWIND.DOC

Text File | 1980-01-01 | 24.0 KB | 482 lines

                                  BASWIND.MRG

                   POP-UP WINDOWS FOR COMPILED BASIC PROGRAMS

                                      by

                                  Dave Evers
                             2500 Larch Rd. #58
                              Quincy, IL  62301

                           using CALLS to ADBVAS.LIB
                                      by
                               Thomas Hanlin III


         BASWIND.MRG is a general purpose BASIC subroutine which can be
         incorporated into Compiled BASIC programs to allow for simple
         windowing capability with a minimum of programming effort. By
         "simple" I really do mean simple: about the only thing this sub-
         routine does is put the window on the screen. What you do with
         the window, what you put in it, and what you do with it once
         you're done is all up to you. However, it does give you the
         ability to make your compiled programs look "high-tech"; even
         if your programming isn't.

         I wish I could take full credit for all of the capabilities of
         BASWIND.MRG. The truth is, however, that very little of the
         "meat" of this program is my doing. BASWIND.MRG relies heavily
         on the routines in the excellent assembly language library of
         advanced BASIC functions contained in ADVBAS.LIB. Perhaps the
         most important of these features is the XQPRINT command, which
         writes data to the screen extremely quickly. It is this command
         which makes the BASWIND subroutine useful because entire sec-
         tions of the screen can rapidly be "painted" into a colored,
         framed "window" in a fraction of a second.

         True windowing, of course, involves much more than just making a
         box appear quickly on the screen. Programs such as TopView,
         Microsoft Windows, Desq, and others allow such features as
         treating the windows as virtual screens with relative cursor
         positioning and independent scrolling; multiple layers of
         overlapping panels that can be added and removed from a screen
         while leaving the underlying data undisturbed, and delegating
         the screen output from multiple programs to their assigned
         windows. BASWIND.MRG is not likely to put these companies out of
         business. (For that matter, it's not likely going to put me in
         business, either). However, other features of the ADVBAS library
         can be combined with the BASWIND.MRG subroutine to allow at
         least a small percentage of these features to be incorporated
         into your programs. Commands are included in ADVBAS.LIB to save
         and restore the screen to an array; scroll a rectangular section
         of the screen up or down or clear it; print to the screen rapid-
         ly, and many other useful functions. Virtually any program that
         is compiled can benefit in some way from ADVBAS.LIB; and hope-
         fully, from BASWIND.MRG as well.

         ADVBAS.LIB was written by Thomas Hanlin III, and I and the rest
         of the PC users community owe a debt of gratitude to this talen-
         ted and generous man for his contribution to the free distribu-
         tion of knowledge. Mr. Hanlin, our hats are off to you!

         INSTALLING BASWIND.MRG

         Before you can take advantage of the capabilities of this sub-
         routine, of course, you must MERGE it into your BASIC program.
         BASWIND is distributed as a .MRG file in ASCII format to allow
         it to be easily added to any program. Just load your program
         into memory, and then type:

                               LIST 55000-55590

         at the command level. This will tell you if your program uses
         line numbers that BASWIND might conflict with. BASWIND uses line
         numbers beginning at 55000 and ending at 55590; so obviously if
         your program already uses these line numbers you should renumber
         the .MRG file to another area not used in your program before
         MERGEing it. Once you have done this, or if the response to the
         above query indicates your program will have no problems, simply
         type:

                               MERGE BASWIND.MRG

         After a few seconds, the BASIC ready prompt will return and
         BASWIND will be integrated into your program. Before you do any-
         thing else, SAVE your program so that your working copy will
         have BASWIND installed. Then you're ready to start taking
         advantage of the advanced and awesome (ahem!) capabilities of
         the subroutine.

         USING BASWIND

         BASWIND is invoked, like any other BASIC subroutine, by the
         GOSUB command. If you MERGEd BASWIND as distributed, you would
         use GOSUB 55000. If you had to renumber the subroutine, of
         course, you would use the new beginning line number in your
         GOSUB statement. However, in order to get anything useful out of
         the module (and probably in order to keep your program from
         locking up), you first have to set up some parameters that the
         subroutine will use. This is done by making assignments to the
         following variables prior to the GOSUB statement:

                ULR - (Upper Left-hand Row) - the screen row of the Upper
                      Left-hand corner of your desired window. Value
                      should be between 2 and 23  (for reasons explained
                      below). WARNING - the subroutine does not check for
                      proper values. You must check these yourself or ac-
                      cept the consequences.

                ULC - (Upper Left-hand Column) - the screen column of the
                      Upper Left-hand corner. Value should be between 2
                      and 79.

                LRR - (Lower Right-hand Row) - the screen row of the Low-
                      er Right-hand corner of your window. Value should
                      be greater than ULR but less than 23.

                LRC - (Lower Right-hand Column) - The screen column loc-
                      ation of the Lower Right-hand corner. Value should
                      be greater than ULC but less than 79.

              FRAME - A number between 1 and 4 indicating the type of
                      frame to be drawn around your window. Valid frame
                      values are:

                         1 - Single Line Frame

                         2 - Double Line Frame

                         3 - Single Horizontal Line, Double Vertical
                             Line Frame

                         4 - Single Vertical Line, Double Horizontal
                             Line Frame

                       NOTE: The frame is drawn * around * the window
                             coordinates specified in ULR,ULC,LRR, and
                             LRC. Thus, the dimensions of your window
                             will actually be two columns greater in
                             width (one on each side) and two rows
                             greater in length (top and bottom). This
                             is why you should make allowances in the
                             value of the window corners. Allowing the
                             frame to fall outside proper values will
                             cause unpredictable results.

               FORE - The color of the frame in the window. Standard
                      color attributes are used (Black=0, Blue=1, etc.)
                      and valid values are 0 to 15.

               BACK - The actual color of the window panel. The area de-
                      fined by the corners of the window will be cleared
                      to spaces in the background color specified. Val-
                      ues considered valid are 0 through 7.

               GROW - A "switch" used to indicate to the subroutine if
                      the window should "grow" from a small box at the
                      midpoints of the coordinates to full size. A value
                      of 1 indicates the window should grow. A value of
                      0 indicates it should not. The "growing" illusion
                      is most effective for windows of medium size; and
                      is better suited to "wide" windows rather than
                      "tall" ones.

             SHADOW - Another "switch" to indicate if the window should
                      have a black "shadow" under it offset down and to
                      the left. This gives a three-dimensional effect
                      that seems to "raise" the window away from the
                      screen. A value of 1 indicates a shadow is desired
                      while a value of 0 means no shadow.

                      WARNING - Adding a shadow to the window increases
                                the effective window size by 3 columns
                                to the left of the window and 1 row
                                below. These additions must be consid-
                                ered when assigning the corner values
                                since invalid values that fall off the
                                screen will produce unpredictable
                                results.

                       NOTE: Windows that grow and windows with shadows
                             are mutually exclusive. That is, a window
                             that is desired to grow cannot have a shad-
                             ow. The on-screen effect of such a combin-
                             ation was determined to be undesireable.
                             The "grow" switch takes precedence. If a
                             window is created which calls for both a
                             shadow and a growing attribute, the shadow
                             will be cancelled and the window will grow.


             LABEL$ - A character string that will serve as a label for
                      the window. The label will appear in the top line
                      of the frame on the left-hand side, enclosed by
                      square brackets ([ ]). If the length of the label
                      is greater than the width of the window, the label
                      will be omitted. The attributes for the label are
                      the same as for the window frame.


         All of the above variables (with the exception of LABEL$) must
         either be declared globally as integers by means of a DEFINT
         statement early in the program; or must have the specific
         integer identifier (%) attached wherever they appear in the
         program. The BASIC compiler is picky about this; so be sure to
         verify that the type assignment is correct.

         EXAMPLE

         To produce a window with a blue background, a bright white
         single line frame, and a label of "Ye Olde Window"; between
         columns 20 and 60 and rows 4 to 20, the following statements
         would be required:

              100 ULC=21:ULR=5:LRC=59:LRR=19:FORE=15:BACK=1:FRAME=1
              110 SHADOW=0:GROW=0:LABEL$="Ye Olde Window"
              120 GOSUB 55000

         To generate a green window with a black single horizontal,
         double vertical line frame, with a shadow; the following
         statements would be needed:

               200 ULC=13:ULR=3:LRC=45:LRR=15:FORE=0:BACK=2:FRAME=3
               210 SHADOW=1:GROW=0:LABEL$=""
               220 GOSUB 55000

         To "grow" a cyan panel in the middle of the screen with a
         yellow double line frame, the program would make the following
         call:

               300 ULC=10:ULR=5:LRC=70:LRR=19:FORE=14:BACK=3:FRAME=2
               310 SHADOW=0:GROW=1:LABEL$=""
               320 GOSUB 55000

         Of course, 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 above window calls only give you the canvas on
         which to work. You, as the artist, produce the masterpiece on
         your own.

         ADVANCED WINDOWING FUNCTIONS

         The basic BASWIND subroutine calls give you a fair amount of
         flexibility in producing simple windows on the screen; but to
         really add some "pizzazz" to your programs, you need more
         capability than just these humble beginnings. This is where some
         of the additional features in the ADVBAS library come into play.

         By combining some of these functions with the easily-used
         BASWIND subroutine, some very powerful and exciting possibili-
         ties are generated. Actually, compiled BASIC becomes a very
         effective development medium with some impressive capabilities
         when all of these advanced tools are put to use.

         Making "Pop-ON/Pop-OFF Windows"

         Most programs which use windows make very effective use of the
         screen by allowing a window to "pop on" to the screen over the
         existing information, display some important data such as help
         or statistics, and then "pop off" on demand; leaving the screen
         data undisturbed. Obviously, the simple commands introduced
         earlier would not be of use by themselves because they destroy
         the information on the screen at the window coordinates. In
         order to allow "non-destructive" windows on the screen, the
         contents of the screen must be saved prior to adding the window,
         and then quickly restored when the window is removed.

         Fortunately, the ADVBAS library includes two special commands
         that make this work extremely easy. The SCRSAVE and SCRREST
         functions allow the virtually instantaneous transfer of screen
         data to and from a numeric array. Once the array has been
         dimensioned and the space reserved in memory, the entire screen
         can be saved in just a fraction of a second. The window can then
         be drawn anywhere on the screen without regard to the loss of
         screen data. The SCRREST command performs the dual function of
         erasing the window and restoring the screen's previous contents.
         And all of this magic can be accomplished with just a few lines
         of simple BASIC code.

         A typical use of the SCRSAVE and SCRREST commands would be as
         follows:

                  10 OPTION BASE 1:DIM SCR%(4000)
                  .
                  .
                  .
                 100 WHER%=VARPTR(SCR(1)):CALL SCRSAVE(WHER%)
                 110 CURSX%=pos(0):CURSY%=CSRLIN
                  .
                  .
                  .
                 150 REM Add window to screen
                  .
                  .
                  .
                 200 WHER%=VARPTR(SCR(1)):CALL SCRREST(WHER%)
                 210 LOCATE CURSY%,CURSX%
                  .
                  .
                  .

         While it is theoretically possible to maintain multiple arrays
         to allow for several levels of non-destructive windows, each
         array uses 8000 bytes and thus rapidly depletes free memory
         space. Most programs can do nicely with only one array and one
         level of windowing support.

         Scrolling and Clearing Data Inside a Window

         Another powerful feature made possible by the ADVBAS library is
         the ability to scroll and clear a selected area of the screen,
         independent of the rest of the data displayed. When combined
         with the effective display techniques described above, this
         impressive capability mimics that of expensive commercial prog-
         rams. And best of all, the function calls are as easy to use as
         the routines described above for BASWIND.

         The SCROLL and BKSCROLL commands take five parameters; four of
         which are already defined as ULC,ULR,LRC,LRR in the BASWIND
         window definition and display routine. Since the frame of the
         window is drawn around the area defined by these coordinates,
         the scrolling can take place within the confines of these
         windows without any further complications. The fifth parameter,
         the number of lines to scroll, is easily set. Most often, it
         will only be one line; so that another line can be PRINTed into
         its place either on the top or the bottom depending on whether
         the scroll is up or down. In the special case that the number of
         lines is zero, the entire area is cleared with spaces of the
         background attribute; so an easy way of clearing a window is
         available as well.

         As with the BASWIND parameters above, all of the SCROLL
         variables must be integers. Thus, either a DEFINT statement must
         be in place early in the program or the variables must carry the
         "%" type identifier throughout the program.

         The program statements required to scroll up the contents of a
         window defined and displayed by BASWIND would be as follows:

                  100 LINS=1
                  110 CALL SCROLL(ULC,ULR,LRC,LRR,LINS)

         To scroll the same window down instead, the following series of
         statements would be used:

                  100 LINS=1
                  110 CALL BKSCROLL(ULC,ULR,LRC,LRR,LINS)

         And to clear the window of any data:

                  100 LINS=0
                  110 CALL SCROLL(ULC,ULR,LRC,LRR,LINS)

         FURTHER ENHANCEMENTS

         The routines presented here allow a good start in providing
         advanced windowing features in almost any compiled BASIC
         program; but there is certainly room for improvements and
         enhancements to these basic ideas. A few of which that come to
         mind immediately are:

                - Being able to move the window on the screen in real
                  time under the control of the cursor keys. Such a
                  procedure would involve rapidly restoring the orig-
                  inal screen and redrawing the window at the updated
                  position; something that seems feasible with the
                  ADVBAS features.

                - Adding clipping to the display of data in the window.
                  For example, moving a window across a text file under
                  cursor control.

                - "Collapsing" windows which are removed from the screen
                  in the opposite manner to "growing".

                - A means of providing "point and select" functions with-
                  in a window by moving a highlight bar up and down a
                  list of options.

         I am sure that with a little experimentation with these
         routines, you will think of many more possibilities. Should you
         come up with a routine that you like, please upload it to your
         favorite bulletin board to help pass along this free exchange of
         information. Drop me a line also, as I would like to keep up
         with all of the developments these initial offerings inspire.

         COMPILING PROGRAMS

         As mentioned before, the routines in BASWIND and ADVBAS are
         available only in Compiled BASIC. DON'T TRY TO USE THESE
         PROGRAMS IN INTERPRETED BASIC!!!! At the very least, your
         computer will probably lockup requiring a re-boot. At worst,
         your system could go crazy, maybe even to the point of erasing
         data on disks in the drive. You are forewarned!

         BASWIND requires no special handling when it comes to compiling
         your program. Just make certain that all of your variables
         passing parameters to the BASWIND subroutine are identified as
         integers, and you will be able to proceed with the compile
         operation as with any other program.

         The actual compilation of your program should be straight-
         forward. However, once you get to the LINK operation, you MUST
         remember to list ADVBAS in response to the LINK program's
         request for library (LIB) files. Failure to do this will result
         in unresolved external reference errors. This is true even if
         you are using only BASWIND functions with no ADVBAS routines in
         your program, since BASWIND uses the XQPRINT function in ADVBAS
         as the heart of its operation.

         ACKNOWLEDGEMENTS

         As mentioned earlier, the ADVBAS.LIB library upon which all of
         the routines in BASWIND.MRG are based was developed by Thomas
         Hanlin III. For convenience sake, I have included this library
         along with the accompanying .DOC file as part of the BASWIND.ARC
         package. Tom has done an excellent job of providing many useful
         features in an economical and well documented package. In the
         .DOC file, Tom asks for a minimal contribution if you find these
         routines useful. I have sent him my check; and I strongly urge
         you to do so as well. To keep this spirit of information
         exchange alive, those people who make such a generous effort
         deserve to be rewarded.

         I am deeply indebted to Tom for his routines which are key to
         the operation of BASWIND. But as I look at my bank account, I
         find that I am deeply indebted, period. Thus, I humbly request
         that if you find BASWIND to be of some use to you that you
         acknowledge your appreciation in a similar contribution of $10.
         Unlike Tom, I don't guarantee you anything back for your money.
         I don't have any other programs to give you; and I've included
         all the source code in this package. But I do promise that I'll
         like you a lot if you do send me money. And just the fact that I
         haven't burdened down the code with a message that pops on the
         screen and begs for money until you "PRESS ANY KEY TO CONTINUE"
         ought to be worth something!

         Whether or not you feel BASWIND is worth anything, please feel
         free to use it to your hearts content; copy it shamelessly and
         give it to all your friends and enemies; use it in your
         commercial programs and sell them for hundreds of thousands of
         dollars. But whatever you do, keep contributing to the Public
         Domain and FreeWare/ShareWare community. The best people in the
         world live here!


         Dave Evers
         2500 Larch Rd. #58
         Quincy, IL  62301









                            DISCLAIMER OF LIABILITY



         I, David Evers, as author of the BASWIND.MRG subroutine
         contained in this package, hereby disclaim all responsibility
         for any consequence arising from the use, misuse, or non-use of
         any of the materials included herein. If this scares you and you
         feel that you can't in good conscience use this product without
         deposits and bonds and insurance policies for millions of
         dollars, THEN DON'T USE THIS SOFTWARE. If you are afraid that
         use of this product will damage your reputation, turn your green
         screen monitor amber, change your house AC voltage from 110 to
         220, or make your hair fall out; THEN DON'T USE THIS SOFTWARE.
         And if by chance you DO use this software, and your spouse
         leaves you, your children sell the house, your health fails, and
         your hard disk crashes, THEN DON'T COME CRYING TO ME. With this
         software, "you don't pays your money, but you still takes your
         chances"!



ME CRYING TO ME. With this
         software, "you don't pays your money, but you still takes your