World of Shareware - Software Farm 2/wosw_2.zip/wosw_2/QBAS/QB4WIN32.ZIP/W32.DOC

Text File | 1980-01-02 | 28KB | 589 lines

        Documentation for QBasic Windows Version 3.2

The routines and notes listed here appear in this file in
alphabetical order.

                        I.  Window Routines

        OpenW                   FillW                   Border
        SaveW                   InitW                   DefBorder
        CloseW                  SaveWgra                WSize
        CloseLastW              CloseWgra               WSizeGra

                        II. Print routines

        Printt                  PrintW                  Lokate
        Prnt                    PrntW                   Kolor
        PrntS                   PrntUsingS              Tabb
        KLS

                       III. Misc routines

        ScrollU                 ReadScreen              DebugW
        ScrollD                 Int3                    Dump1
        ScrollL                 Int10                   Refresh
        ScrollR                 Adapter                 Monochrome
        MapMask                 SetViewPage             SnowCheckingOn
        InitW                   SetViewW                SnowCheckingOff
        ConvertTG


                       IV. Notes

        Additional documentation         Description of this library
        Quirks and misc notes            W32.DEC
        If you have problems...          Registration
        Files included with this library
===========================================================================
Adapter (a%)
        Pass an integer variable to this call to find what kind of video
adapter is active. Adapter has not been tested on an EGA. An active VGA
will return a value of 3 even if it is emulating a CGA or EGA, since it is
the VGA that is active.
        Return codes:
                0 - MDA (monochrome)
                1 - CGA
                2 - EGA
                3 - VGA
===========================================================================
Additional documentation
        There are some routines for the VGA color registers written
        in QBasic included in W32.BAS.  Documentation for them is at
        the beginning of W32.BAS

        W32Lib.bat contains a list of the calls in each object file
        and commands to create .QLB and .LIB files.

===========================================================================
Border n
          The values  for border are:
               0       no border
               1       single line
               2       double line
               3       double line at top and bottom, single line on sides
               4       User defined (by Call DefBorder)
===========================================================================
CloseLastW ()
Closes the most recently opened window (created with OpenW or SaveW).
The coordinates and segment of the last ten windows are saved on a
revolving stack so it may be called up to ten times.  CloseW will bump
the last one off the stack. OpenW and SaveW add one to the stack (even
if the segment is 0). Call DebugW to view the stack.
Example:
       redim b(1000):
       CALL SaveW(VARSEG(b(1)), 1, 1, 24, 80)
       call OpenW(0,1,40,10,60)
       call CloseLastW
       call CloseLastW
===========================================================================
CloseW (segment,TR,LC,BR,RC)
Closes a window opened by either SaveW or OpenW.  The window may be
moved or copied to a new location on the screen by changing the
coordinates.
===========================================================================
DebugW ()
        Prints information about the current values for QB4Windows
        parameters.  In graphics modes, the window coordinates given
        will be graphics even if they were given as text coordinates via
        OpenW or SaveW.
===========================================================================
DefBorder(x$)
        Allows the user to define a new border.  X$ is a string of
        nine characters for the
            top left corner    -   top row   -  top right corner
            left side          -   middle    -  right side
            bottom left corner - bottom line - bottom right corner


       DefBorder may also be used to fill an area of the screen with a
       character. For example, to fill the entire screen with periods:
               Call DefBorder (".........")
               call OpenW(4,attribute,0,1,1,25,80)
        An example of this appears in W32.BAS in the sub Windows2.

===========================================================================
Description of this library

        Qb4Win32 is a screen oriented library written entirely in assembler
for QuickBasic and assembler programmers.  It is probably the easiest
subh library to use, and has the best routines for saving, clearing,
drawing and restoring windows.  A problem that kept earlier versions from
working with the Phoenix bios has been corrected.

        Qb4Win33 can save and draw windows in all of the text and
graphics modes, including the VGA extended modes. In addition, it can
scroll up, down, left and right in all of the text and graphics modes.
Other routines provide the programmer opportunity to print strings
and numbers in the 132-column text modes;  confine printing to a window;
determine the adapter in use;  print to two monitors; a powerful routine
called FillW to print string arrays;  set the text mode to any
of the VGA extended modes up to 100 lines by 132 columns;  set the color
registers; scroll only selected color planes; and read text from the screen
into strings.

        The library is divided into a few object files so that you may
exclude those you do not want to save memory.  The entire library
uses about 15K.  A simple batch file is included to facilitate linking
the object files with those from your own or other's libraries.  The demo
program contains useful basic routines and makes the use of and capabilities
of this library easy to understand.

===========================================================================
Dump1 (segment, offset,  attr, NLines,  Row)

        Does a debug-style memory dump.  W32.BAS demonstrates this routine
by using a sort of multi-tasking to do an X-RAY type dump of the keyboard
buffer.

        Seg     Segment to display
        Offset  Offset to display
        attr    defines the color
        NLines  # of lines to dump
        Row     Start printing at this row

        The Offset is not an integer variable as it was in W31.
        You may display the memory dump on a second monitor
by switching between the cga & vga video segments:
        Call Monochrome : Call Dump1 [or Refresh] : InitW
===========================================================================
Files included with this library

W32      DOC    27192           This file

W32DEMO  BAT       63           Batch file to run the demo
W32      BAS    52407           Demo program.  W32.DEC W32.VPT & W32.DOC
                                    should be in the current directory

W32LIB   BAT     1416           Use to create W32.LIB or change W32.QLB
W32      QLB    15341           QBasic library
W32      DEC     2510           Declare statements
W32      VPT       49           file used by W32.BAS

W32      OBJ     3653           object files used by W32LIB.BAT
PRNTS    OBJ     2145
MISC     OBJ     2952
SCROLL   OBJ     2492
SAVEW    OBJ     2629
PRNT     OBJ     1874

===========================================================================
FillW ( n , varptr(a$(L) )
        Fills a window with strings from an array.  The coordinates used
        are those of the window most recently  opened with OpenW or
        SaveW.  The first n characters of each string are skipped, so
        increasing n has the effect of scrolling to the left. Increasing
        L has the effect of scrolling up.
        Example:
              call OpenW(2,7,0,2,20,10,40)
               redim a$(500) : 'and assign strings to a$()
               n=0 : L=1
               FillW n , varptr(a$(L)
       L should not be greater than the last string dimensioned less the
       number of lines to print in the window plus 1, otherwise the
       remainder of the window will be printed with garbage.

        The sub FILL in WDemo.bas demonstrates using FillW to view a file and
        the main menu uses it to fill a menu box.

        This will not work with an array of fixed length strings.
===========================================================================
If you have problems
       If your computer locks up or loses data, check the following:
       Used SaveW or OpenW with an array that was too small.
       Used a static array - put REM $DYNAMIC in each SUB
       Passed the wrong segment to OpenW or SaveW. Example:
                REDIM a%(800): OpenW VARSEG (a(1)), ......
       Did not include W32.DEC - you must have the DECLARE statements.

        If you can't get this program to behave properly, before writing
        run the demo (W32.BAS) to see what does and does not work in it.
        Since most of this program is new and it got a little complicated,
        some bugs are probably inevitable, so don't hesitate too long
        before asking for help. You may also want to check for a more
        recent version on one of these bulletin boards (the next version
        will be QB4Win33.Zip):

        Exec-PC                         (414) - 964 - 5160

        The Utilities Exchange          (614) - 442 - 6695

        Greater Cincinnatti PC users    (513) - 221 - 7284

        Public Domain SIG               (619) - 749 - 2741

        Odie link                       (614) - 335 - 3972.

       Remember, it is up to YOU to protect valuable data and programs.

===========================================================================
InitW  (RR%, CC%)
        Resets all the parameters for windows to their default values.
        This should be called at the beginning of a program.  If the
        program is halted and run again, the defaults may be incorrect.
        This call passes the integer variables RR and CC so that Lokate,
        Prnt and PrntW can find them. The call to InitW is included in W32.DEC.
===========================================================================
int3 ()
        calls interrupt 3
===========================================================================
Int10   (ax%, bx%, cx%, dx%)
        Copies DS into ES, calls interrupt 10h, passes the values of 4
registers back to QBasic.
===========================================================================
KLS
        Clears the screen, sets the cursor coordinates (RR and CC) to 1.
===========================================================================
Kolor  foreground, background
        Sets the color for W32, like Basic's COLOR.
===========================================================================
Lokate line, column
        Sets the cursor location (used by PrntW, Prnt, PrntS, etc)
by setting the values of RR and CC.  RR and CC are defined as
common shared integers in W32.dec.  It also moves the cursor
to the new location.
        Use basic's LOCATE to change the shape of the cursor.  You may also
have to move the cursor or CLS to make it take effect.
===========================================================================
Monochrome
        This forces W32 to use the monochrome adapter. If the
active monitor is a CGA-VGA, the cursor movement will appear on the
active monitor even though the text is written to the MDA. With this
function you may have a VGA in a graphics mode and
still print text on a MDA. Call InitW to restore the defaults.
===========================================================================
OpenW (segment, TR, LC, BR, RC)
        This calls SaveW to save the window. In addition, the area in the
        window is blanked and a border drawn around it.  Use Border
        and Kolor to define the border and colors used.  See also SaveW.

If the segment passed is 0 the data is not saved and you do not have
       to dimension an array.  This is used to draw a box, set up
       coordinates for FillW and erase the window. Example:
       call OpenW(2,7,0,2,20,10,40)

       The sub Machine in W32.bas demonstrates using  OpenW to draw
       a black rectangle. The sub Windows2 shows how to draw 2 overlapping
       windows to create a shadow effect.

In SCREEN 2, OpenW will not print graphics characters.  To draw a border
in this mode, use Border (4) and define a border with DefBorder using only
CHR$(1) to CHR$(127)

        Note that in graphics modes, TR LC BR & RC are still TEXT coordinates.
        For example, in SCREEN 12, TR and BR are 1 to 30, not 0 to 479.

===========================================================================
Printt "string", attribute, row,column
PrintW "string", attribute, row,column
Prnt   "string"
PrntW  "string"

        The attribute for Prnt and PrntW is passed via a call to KOLOR.
        The locataion is passed with a call to LOKATE.  Printt and Prnt
        will print at any location on the screen, unless the display has
        been restricted by calling SetViewW.  PrintW and PrntW will only
        print within a window.

        The string may be a variable or literal, as:
        Prnt "Hello"
        msg$ = "Hello" : Prnt msg$

        The attribute, row and column may be any type of number:
        Printt "Hello", &h30, Row + 3, 15

        After the call, the cursor is positioned after the last character
        printed, and the values of RR and CC are updated to reflect the new
        cursor position so another string may be printed without making another
        call to lokate.  Thus these calls are equivalent to basic's
                        PRINT "string";
        where a semicolon suppresses the line wrap.

        With PrntW  the easiest way to position the cursor at the top
        left corner of the window is to Lokate 1, 1.  It will automatically
        move down and right until it is inside the window.  Likewise, use
        Lokate 25,81 to force the window to scroll up a line and position the
        cursor at the start of the last line.

-------------------------------------------------------------------------
CR$
        If a string printed with Printt, PrintW, Prnt or PrntW is appended
        with a chr$(13) a carriage return\linefeed is executed.  The
        line will be erased to the end and the cursor drops to the beginning
        of the next line, scrolling if necessary.  This is equivalent to
        PRINT a$.  Example:
                CR$ = Chr$(13): Lokate 1,1
                Prnt "Hello" + cr$
 'Hello' and 75 blank spaces will be printed and the cursor will be at 2, 1

-------------------------------------------------------------------------
EOL$
        Appending the string with chr$(10) is the same as chr$(13)
        except that scrolling is suppressed.  Use this to print on the
        last line of the screen and erase to the end of the line without
        causing the screen to scroll.  RR will go out of bounds instead.

        Example:
          Lokate 25,1 : EOL$ = chr$(10)
          Prnt "Hello" + EOL$
                 'prints "Hello" and 75 blank spaces
                 'Now RR=26 and CC=1
          Prnt "Goodby"
                'since RR is > 25, now the screen scrolls up and Goodby
                ' is printed at 25, 1

-------------------------------------------------------------------------
        Prnt and Printx are much faster than Basic, and don't have
        some of its quirks.  For example,
                Locate 24,79:Print "abc"; :' will scroll the top
                        24 lines and print at 24,1

                Locate 25,79:Print "abc"; :' will also scroll the
                        first 24 lines and print at 24,1

               a$="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
               locate 1,1:Print a$;a$;
               'the second a$ will print at 2,1 because it could not
               'entirely fit on the first line

===========================================================================
===========================================================================
PrntS   (BYVAL x!)
        Prints a single-precision number.  Use lokate & kolor to set the
location and color.  It is about twice as fast as QBasic, and 7 times
faster if called directly from assembler.  Maximum of 7 digits right of
the decimal point, about 18 left of the decimal point, and 7 significant
digits. This allows printing numbers in 132 column modes.  Positive
numbers do not have a leading blank space.
===========================================================================
PrntUsingS      (mask$, n)
        Prints a single precison number using a mask, like PRINT USING.
        Example:   x = 33.4 : PrntUsingS "####.###", x
        Output:    33.400
===========================================================================
Quirks and misc. notes
        If you have used 'INCLUDE:'W32.DEC' and the program halts at the last
line of W32.DEC, highlights "RR" and displays the message box
"wrong data type", unload W32.DEC. It happens when you load W32.DEC
to edit the file.
                 -------------------------------------
        The calls that don't have arguments can't be the first command
on a line because they will be interpreted as labels instead of commands.
These don't work:
        KLS : Prnt "Hello"
        CloseLastW : EXIT SUB
These do:
        Call KLS: Prnt "Hello"
        KLS
                  ------------------------------------
        All the print routines check the boundaries set by SetViewW, and
also check the current display.  Windows or Lokates outside these boundaries
are resized to fit the screen.
                  ------------------------------------
        QBasic saves the current state of the VGA before returning to
the editor, and restores it if you halt and then continue the program, so it
is not possible to change the editor to 43 line mode with W32.BAS.  To use
the editor in this mode, change before invoking QB.EXE.
        Since QBasic 4.0 does not support 132 column modes at all, and
the VGA in this mode (mode 17h) emulates 80 column mode, it is not
advisable to halt a program and try to use the editor while in the 132
column mode.  W32.BAS restores the display to 25 x 80 when "q" is
selected from the main menu.

                  -------------------------------------
        After any print statement, the values of RR and CC are updated
to reflect the new location that the cursor should be at.
Example to retrieve the cursor position when mixing PRINT and Prnt:
        LOCATE RR, CC : PRINT "String1";
        Lokate CRSLIN,  POS(0) : Prnt "String2"
        'output: String1String2
===========================================================================
ReadScreen (a$, row, column)
         Reads text from the screen into a string variable.  The
first character is at (row,column) and the number read equals the length
of the string.  It won't wrap to the next line in graphics modes.
Usage:
        a$ = SPACE$(n) : call ReadScreen (a$, row, column)
To save the entire screen:
        a$ = SPACE$(2000) : ReadScreen a$, 1, 1
===========================================================================
Registration
   I can't possibly test every combination of calls, parameters, modes and
computers, so use this library at your own risk.  If registered, you may use
the library in any program with no additional fees or aknowledgements, but not
include it in another library and market it as part of your own library.  If
in doubt, write for permission. Registration is $10, free if you have paid
for any earlier versions.  Source code is $20 on 5 1\4 discs.

               Jim Paisley                            Version W3.2
               10690 Allen Rd NW
               Washington C.H.,Oh 43160

       Name     _________________________________________

       Address __________________________________________

               __________________________________________


===========================================================================
SaveW (segment, TR, LC, BR, RC)
        Saves the contents of the screen inside the window defined by
        TopRow,Left Column,Bottom Row and Right Column into a dynamic
        numeric array.  The coordinates of the window are pushed onto
        the stack for CloseLastW and PrntW. The display
        on the screen is not erased.  The contents of the window may be
        restored by calling CloseLastW or CloseW.

       If 0 is passed as the segment, the contents of the window are
       not saved, although the data for the window is still pushed onto a
       stack.  This is used define a window for PrntW.
       Example to define a window but not save it:
             SaveW 0, 1, 1, 24, 80 : PrintW a$, 7, 1, 1

        An example to save  the entire screen:
                Rem $DYNAMIC
                REDIM a%(2000):' sets aside 4000 bytes of memory
                SaveW VARSEG(a%(1)), 1, 1, 25 ,80

        Note that in graphics modes, TR LC BR & RC are still TEXT coordinates.
        For example, in SCREEN 12  TR and BR are 1 to 30, not 0 to 479.
        To use graphics coordinates, call SaveWgra.

      -----------------------------------------------------------------
     | THE ARRAY MUST BE DYNAMIC.  Use the $DYNAMIC metacommand at the |
     | beginning of the program or sub in which the dim or redim       |
     | statement occurs.  You may also force the  array to be dynamic  |
     | by using variables for the dimensions.  This is most important  |
     | when creating .exe files because they default to static arrays. |
     | The editor\compiler defaults to dynamic.                        |
     | Example: $dynamic                                               |
     |          n=200:redim array%(n)                                  |
     |          Call OpenW(2,7, varseg(array(1)), r,c,rr,cc)           |
     | Putting 'REM $DYNAMIC' at the beginning of a program does NOT   |
     | carry over to subs so put it in each SUB or FUNCTION.           |
      -----------------------------------------------------------------

        W32 will not save windows to arrays larger than 65536 bytes.  Thus
        it is not possible to save the entire screen in some graphics modes
        unless some of the color planes are masked out or put in different
        arrays (see MapMask), or the screen is split into 2 or 3 windows.
        Screen 12 uses 153,600 bytes, and SCREEN 13 uses 64000.
        If in doubt, use REDIM a%(0 to 32767) and W32 will not be able to
        overwrite past the end of the array.


                 <<<<  If you don't want to use    >>>>
                 <<<<  these formulas, see WSize   >>>>

        Byte boundaries for:
        LC in SCREEN 1 are 0, 4, 8,  12... 316
        RC in SCREEN 1 are 3, 7, 11 15 .... 319
        LC in SCREEN 7, 8, 9, 10, 11, 12 are 0, 8, 16, 24 .... 636
        RC in SCREEN 7, 8, 9, 10, 11, 12 are 7, 15, 23, ....639
        n = 1 in the following formulas if LC & RC are aligned on byte
              boundaries and 3 if they are not.
        ColorPlanes is 4 unless changed by MapMask.
        Text coordinates apply to OpenW and SaveW in all modes.
        Graphics coordinates apply to OpenWgra and SaveWgra.
        ScrollU, ScrollD, ScrollL and ScrollR use text coordinates in
        SCREEN 0 and graphics coordinates in other modes.

        SCREEN 0
        Words = (BR - TR + 1) * (RC - LC + 1): REDIM a%(Words)

        Screen 1 with graphics coordinates
        Bytes = (BR - TR + 1) * (RC - LC + n) / 4 : REDIM a%(Bytes / 2)

        Screen 2 with graphics coordinates
        Bytes = (BR - TR + 1) * (RC - LC + n) / 8 : REDIM a%(Bytes / 2)


        Screen 2 with text coordinates
        Bytes = (BR - TR + 1) * (RC - LC + 1) * 8: REDIM a%(Bytes / 2)


        Screen 7, 8, 9, 10,12 with graphics coordinates
        Bytes = ((br - tr + 1) * (rc - lc + n))  / 8 * ColorPlanes
        : REDIM a%(Bytes / 2)


        Screen 7, 8, 9, 10,12 with text coordinates
        Lines is 8, 14, or 16, depending on the character box size.  This
        is in the QBasic manual under SCREEN.
        Bytes = ((br - tr + 1) * (rc - lc + 1))  * Lines * ColorPlanes
        : REDIM a%(Bytes / 2)

        SCREEN 13
        Bytes = (BR - TR + 1) * (RC - LC + 1): REDIM a%(Bytes / 2)

===========================================================================
SetViewPage  (page)
        Only pages 0 to 3 in SCREEN 0, 25x80 display are supported.
        Defines the active page. Page is a number from 0 to 3. The
default value is 0.  Typical usage is:
        SCREEN , , page,page : SetViewPage page
===========================================================================
SetViewW   ( TR, LC, BR, RC)      SCREEN 0 only
      Defines the active portion of the screen.  Similar to
Basic's VIEW PRINT [topline TO bottomline] statement except that
columns is also a parameter.  All the routines in QB4Windows
operate within these boundaries in text modes except ReadScreen and KLS.
Use it to lock out the top or bottom line when that line is used
for a menu.  The default values are set to the full screen by InitW.
===========================================================================
ScrollU ( lines, tr, lc, br, rc)
ScrollL ( columns, tr, lc, br, rc)

ScrollU,ScrollD,ScrollL,ScrollR scroll the window up,down,left or right.
The information scrolled off the screen is lost, the lines or columns
scrolled onto the screen are blanked using the specified Kolor.

Example:
       ScrollD(2,1,1,25,80):'scrolls the entire screen down two lines
If the number of lines or columns to scroll is greater than the number
in the window, the entire window is blanked.

     In graphics modes, Columns, LC and RC will be moved to byte boundaries
if necessary.  It will scroll left and right 8 pixels at a time (4 in
SCREEN 1) and will only scroll by a single pixel in SCREEN 13.
==============================================================================
W32.DEC
        This is an include file which contains all the DECLARE statement
        needed. Most of these include BYVAL declarations, allowing
        numbers to be expressed in just about any form and automatically
        converted to integers. It also contains two executable statements.
        Since Lokate and Prnt need the addresses of RR and CC,
        these are declared as global variables, then passed via InitW.
                COMMON SHARED RR AS INTEGER, CC AS INTEGER
                InitW  RR, CC

        I would prefer that you merge W32.DEC with any program you write.
        If you wish to use '$INCLUDE:'W32.DEC',
        COMMON SHARED statements must precede the $INCLUDE statement, and
        other executable statements may not precede it.
===========================================================================
WSize    (Bytes&, TR, LC, BR, RC)       Text coordinates in all modes
WSizeGra (Bytes&, TR, LC, BR, RC)       Graphics coordinates

        Call WSize before OpenW or SaveW to determine the size of array
        needed to save the window.  If SCREEN or MapMask are used they
        must precede the call to WSize.  Typical usage:

                '$DYNAMIC

                SCREEN 12

                MapMask 15

                TR = 8: LC = 40 : BR = 12 : RC = 60

                WSize (Bytes&, TR, LC, BR, RC)

                IF Bytes& > 65536 THEN PRINT "ARRAY TOO LARGE" : END

                REDIM A%(1 TO Bytes& / 2)

                OpenW VARSEG(A%(1), TR, LC, BR, RC
===========================================================================