home *** CD-ROM | disk | FTP | other *** search
-
- 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
- ===========================================================================
-