Simtel MSDOS - Coast to Coast

home *** CD-ROM | disk | FTP | other *** search

/ Simtel MSDOS - Coast to Coast / simteldosarchivecoasttocoast2.iso / c / quikc21.zip / QWIKC21.DOC < prev next >

Wrap

Text File | 1989-07-06 | 79KB | 2,118 lines

QWIKC SCREEN UTILITIES USER'S GUIDE Version 2.1 June 1, 1989 Conversion to Turbo C / MS C by Jordan Gallagher / Wisdom Research Copyright (C) 1988,1989 Eagle Performance Software All Rights Reserved. _______ ____|__ | (tm) --| | |------------------- | ____|__ | Association of | | |_| Shareware |__| o | Professionals -----| | |--------------------- |___|___| MEMBER QWIKC Screen Utilities User's Guide, Version 2.1 T A B L E O F C O N T E N T S 1. INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 3 Features . . . . . . . . . . . . . . . . . . . . . . 3 Using the Manuals . . . . . . . . . . . . . . . . . . 3 Licensing . . . . . . . . . . . . . . . . . . . . . . 4 Customer Service . . . . . . . . . . . . . . . . . . 4 ASP . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. GETTING STARTED . . . . . . . . . . . . . . . . . . . . 6 Distribution Files . . . . . . . . . . . . . . . . . 6 Demonstration . . . . . . . . . . . . . . . . . . . . 6 Simple Programming . . . . . . . . . . . . . . . . . 7 Functions . . . . . . . . . . . . . . . . . . . . . . 9 3. BASIC TECHNIQUES . . . . . . . . . . . . . . . . . . . 12 Cursor Mode Routines . . . . . . . . . . . . . . . . 12 Cursor Location Routines . . . . . . . . . . . . . . 13 EOS Marker . . . . . . . . . . . . . . . . . . . . . 13 Scrolling . . . . . . . . . . . . . . . . . . . . . . 15 Pop-Up Windows . . . . . . . . . . . . . . . . . . . 15 Memory Models and Libraries . . . . . . . . . . . . . 16 4. ADVANCED TECHNIQUES . . . . . . . . . . . . . . . . . . 18 Virtual Screens . . . . . . . . . . . . . . . . . . . 18 Video Pages . . . . . . . . . . . . . . . . . . . . . 19 Video Modes . . . . . . . . . . . . . . . . . . . . . 20 Multi-tasking Environments . . . . . . . . . . . . . 21 Interrupts . . . . . . . . . . . . . . . . . . . . . 21 5. HARDWARE DETECTION . . . . . . . . . . . . . . . . . . 22 Display Combination Code . . . . . . . . . . . . . . 22 Snow Checking . . . . . . . . . . . . . . . . . . . . 23 System Hardware . . . . . . . . . . . . . . . . . . . 24 APPENDIX A: Video Mode Table . . . . . . . . . . . . . . . 25 APPENDIX B: Cursor Mode Data . . . . . . . . . . . . . . . 27 Cursor Mode Tables . . . . . . . . . . . . . . . . . 27 Cursor Emulation . . . . . . . . . . . . . . . . . . 27 APPENDIX C: Performance . . . . . . . . . . . . . . . . . 30 Code Size . . . . . . . . . . . . . . . . . . . . . . 30 Speed . . . . . . . . . . . . . . . . . . . . . . . . 30 APPENDIX D: Application Products . . . . . . . . . . . . . 32 APPENDIX E: Revision History . . . . . . . . . . . . . . . 34 APPENDIX F: References . . . . . . . . . . . . . . . . . . 35 2 QWIKC Screen Utilities User's Guide, Version 2.1 1. I N T R O D U C T I O N FEATURES Welcome to QWIKC Screen Utilities! You have just obtained a copy of the highest performance screen writing tools available today for Turbo C 2.0 (TC2), MicroSoft C 5.x and QuickC 1.x. Both novice and professional programmers will appreciate these simple and very powerful utilities that give you absolute control over your CRT displays in all text modes. Here are some of the features you will discover: . Writes on all IBM compatible computers, displays and adapters including MDA, CGA, EGA, MCGA, VGA, 8514/A, Hercules and 3270 PC. . Superior video detection routine. . Eliminates snow and flicker. . Writes directly to the screen in absolute rather than relative coordinates. . Writes in all text modes and column modes. . Writes on all video pages. . Writes on virtual screens in RAM. . Writes text and attribute, text only, or attribute only. . Reads strings, characters and attributes. . Uses end-of-string (EOS) marker for quick string chaining. . Provides standardized cursor control for all adapters. . Enhanced cursor movement. . Compatible with DESQview and similar multitasking environments. . Up to 2300% faster than TC2 cprintf direct video writing. . Only 2.7k bytes of code if all 41 utilities are used. . Optimized by the linker and drops unused code. . Used in all other Eagle products. QWIKC is a library providing capabilities not offered in the standard writing routines that come with most C compilers. In contrast to TC2's standard library functions which do window-relative writing, QWIKC knows how to write directly to the screen in absolute screen coordinates for any video configuration. USING THE MANUALS Disk Based Guides - The manuals for QWIKC are on disk so that you can conveniently scan for the topic you are seeking. You can do this with any list or search utility with a search function. You can also make a printed copy. If you have not already printed this manual, refer to the READ.ME file for instructions. At the present time, no bound manuals are being offered with registration. User's Guide - This manual, the one you are reading now, assumes that as a programmer you are already familiar with your C compiler, and that you have a working knowledge of your disk operating system (DOS). It will provide 3 QWIKC Screen Utilities User's Guide, Version 2.1 you the basic principles of direct screen writing and powerful tips on some previously unavailable techniques. Reference Guide - This manual describes in detail all functions and variables used in QWIKC. It is alphabetically arranged for easy access in a format similar to the TC2 manual. Use this manual when you have become familiar with the basic principles in the User's guide. LICENSING Registration - These utilities and the documentation have been released for distribution as Shareware. You have been given the chance to sample the full capability of QWIKC without risk! If you find that QWIKC is a valuable tool, then you are expected to register. You will find a reasonable licensing schedule found in LICENSE.ARC to meet private or commercial needs. Source Code - All registered users will receive source code when the signed license agreement is returned with the registration. CUSTOMER SERVICE If you have questions, comments, or suggestions, the Eagle can be contacted by four means - (1) CompuServe, (2) The Eagle BBS, (3) telephone, or (4) mail. CompuServe - The most dependable way to contact the Eagle is through CompuServe. Jordan Gallagher has converted QWIKC from Turbo Pascal to C. He can be contacted on the Borland Forum by typing GO BPROGB from the CompuServe main menu. You will enter the Forum for Turbo C. You can contact Jordan with his PPN number of 73557,2342. Messages can also be left through EasyPlex. The Eagle BBS - Our bulletin board system operates 24 hours a day, 7 days a week at 1200 baud, using 8N1 at (214) 539-9878. You can access our Pascal and C products, and leave any questions or messages. Telephone - Jordan can also be reached by phone at (214) 539-7855 on weekdays and Saturday from 10:00 a.m. to 9:00 p.m. CST. Mail - For registration or problems, please write: Eagle Performance Software P.O. Box 292786 Lewisville, Texas 75029-2786 In your written request for resolving problems, be sure to include: . A 5 1/4 inch diskette of compilable source code of the problem. . The Eagle product and version number. . The computer make and model. . The type of video card, video monitor and keyboard. 4 QWIKC Screen Utilities User's Guide, Version 2.1 ASP QWIKC is a Shareware program conforming to the standards of the Association of Shareware Professionals (ASP). You can get more information about ASP by writing to: Association of Shareware Professionals P.O. Box 5786 Bellevue, WA 98006. This program is produced by a member of the Association of Shareware Professionals (ASP). ASP wants to make sure that the shareware principle works for you. If you are unable to resolve a shareware-related problem with an ASP member by contacting the member directly, ASP may be able to help. The ASP Ombudsman can help you resolve a dispute or problem with an ASP member, but does not provide technical support for member's products. Please write to: ASP Ombudsman P.O. Box 5786 Bellevue,WA 98006 or send a CompuServe message via EasyPlex to ASP Ombudsman 70007,3536. 5 QWIKC Screen Utilities User's Guide, Version 2.1 2. G E T T I N G S T A R T E D This section will acquaint you with the files on disk and show you a brief demonstration. You will also run your first program with QWIKC and then become familiar with all of the utilities. DISTRIBUTION FILES In this version, QWIKC21.ARC contains: QWIKC21S.LIB: Small model QWIKC21 library file containing the object files. There are 2000 lines of assembler code for the Small model, and 12000 lines total for all models. Only the small model is supplied with the distribution copy. All models will be supplied upon registration. QWIKC21 .H : Header file for QWIKC21S.LIB. Contains external declarations of QWIKC's variables, macro definitions, and function prototypes. QWIKC21 .DOC: This document - a user's guide to QWIKC. QWIKDEMO.C : A demonstration program showing the features and speed of all functions and is written primarily for color cards, but also works on mono cards. QWIKDEMO.PRJ: Project file for compiling QWIKDEMO.C. QWIKREF .DOC: QWIKC Reference Guide document covering each function and variable in detail. QINITEST.C : A program that verifies the equipment detected by the qinit() function. QINITEST.PRJ: Project file for compiling QINITEST.C. QBENCH .C : A timing program that shows "screens/second" for typical QWIKC functions. QBENCH .PRJ: Project file for compiling QBENCH.C. TIMERD12.C : Source file for routine to measure elapsed time. TIMERD12.H : Header file for routine to measure elapsed time. LICENSE .ARC: ARC file containing license agreements. * .BAT: Batch files for compiling demo programs using MicroSoft C or QuickC. Registered users who have the source code will also have the following files: QWIKC21T.LIB: Tiny model QWIKC21 library. QWIKC21C.LIB: Compact model QWIKC21 library. QWIKC21M.LIB: Medium model QWIKC21 library. QWIKC21L.LIB: Large model QWIKC21 library. QWIKC21H.LIB: Huge model QWIKC21 library. There will also be six subdirectories containing the .ARC files for the source on the disk for registered users. DEMONSTRATION To get an overview of the speed and features of QWIKC, let's run a 6 QWIKC Screen Utilities User's Guide, Version 2.1 demonstration program that came with the utilities. Do the following steps: 1. Using the small model, compile the QWIKDEMO program. If you have Turbo C, this is done using the project file QWIKDEMO.PRJ. If you have MicroSoft C or QuickC, use either CLQDEMO.BAT or QCLQDEMO.BAT, respectively. You must specify a parameter to these batch files indicating the model size. 2. If you are running programs in a multi-tasking environment, instruct the environment that you are NOT writing direct to the screen. Also set text pages to 2. 3. Run QWIKDEMO. 4. Press any key when the screen prompts you to continue with "... press any key". Before doing the same thing with QINITEST.C, read the comments at the top of the source file to see if you want to test for a computer submodel ID. The batch files for QINITEST are CLQTEST.BAT and QCLQTEST.BAT. SIMPLE PROGRAMMING Batch file or makefile (MSC/QC) - You should create either a batch file or a makefile to compile your program. A batch file should simply execute your compiler and instruct it to link QWIKC21S.LIB. Be sure to use the small model. For instructions on creating a makefile, see your compiler's instructions. Project File (Turbo C) - All example programs in this manual assume that QWIKC21S.LIB is being linked. Your first project file may look like this: myqwik1 qwikc21s.lib First Program - Let's write a short program to see how simple it is to write with QWIKC. While in your editor, enter the following code: #include <stdio.h> #include <conio.h> #include "qwikc21.h" main() { qinit(); qfill( 1, 1, crt_rows, crt_cols, LIGHTGRAY, ' ' ); qwrite( 5, 1, YELLOW+BLUE_BG, "QWIK writing" ); qwrite( 5, 13, YELLOW+BLUE_BG, " is easy!" ); getch(); return; } Save the file, then compile and run the program. You can then see the text "QWIK writing is easy!" starting on row 5, column 1. On color monitors, the text is a yellow foreground with a blue background while monochrome monitors show high intensity on black. 7 QWIKC Screen Utilities User's Guide, Version 2.1 Row/Col vs. X/Y - You probably noticed that the row parameter is first and the column parameter is second. Since QWIKC is entirely for text modes, it is more intuitive to specify the row first and the column second just like any word processor. The X/Y scheme is better suited for graphics. Attributes - Notice that our example uses the macro BLUE_BG. QWIKC provides eight convenient background color macros to use along with the 16 foreground color macros. The same names are used, but the "_BG" suffix is added: BLACK_BG RED_BG BLUE_BG MAGENTA_BG GREEN_BG BROWN_BG CYAN_BG LIGHTGRAY_BG These allow QWIKC to make the most of C's macros. By simply adding the foreground and background macros together, the compiler saves the result as a single word. And, by simply reading the qwrite statement, what you see is what you get (WYSIWYG). Readable Code - As an added benefit, QWIKC was designed with human factors in mind and was made so that it is very easy to read the code you create. With the row, column, and attribute parameters first and the string last, you can see that the two qwrite statements were easily aligned. WYSIWYG to the rescue again! Chaining - Notice that we had to calculate the string length of "QWIK writing" before we could locate the string " is easy". Let's modify the last statement to indeed make it easier to locate the last string: #include <stdio.h> #include <conio.h> #include "qwikc21.h" main() { qinit(); qfill( 1, 1, crt_rows, crt_cols, LIGHTGRAY, ' ' ); qwrite( 5, 1, YELLOW+BLUE_BG, "QWIK writing" ); qwriteeos( YELLOW+BLUE_BG, " is easy!" ); getch(); return; } Now that was really easy! How did qwriteeos() know where to write? QWIKC internally keeps track of an end-of-string (EOS) marker so that any subsequent "eos" function like qwriteeos() will chain the next string right there - no rows or columns to calculate! And you can chain as many as you want on to any other QWIKC function. Same Attribute - But suppose we did not want to change the attribute that was already on the screen and don't even know what it is. How is that done? Just modify the attributes to the following: #include <stdio.h> 8 QWIKC Screen Utilities User's Guide, Version 2.1 #include <conio.h> #include "qwikc21.h" main() { qinit(); qfill( 1, 1, crt_rows, crt_cols, LIGHTGRAY, ' ' ); qwrite( 5, 1, SAMEATTR, "QWIK writing" ); qwriteeos( SAMEATTR, " is easy!" ); getch(); return; } The macro SAMEATTR (which is negative) tells QWIKC to simply enter the text on the screen without changing the attribute. The result of the program shows the text with LIGHTGRAY on BLACK attributes. This macro works on all QWIKC utilities so that, when assigned to a variable, the attribute can even be switched at runtime. Centering - Rather than having the text left-justified, let's center the text on the screen by modifying a portion of the code: ... qfill( 1, 1, crt_rows, crt_cols, LIGHTGRAY, ' ' ); qwritec( 5, 1, 80, SAMEATTR, "QWIK writing is easy!" ); return; } This will place the text on row 5 centered between columns 1 and 80 which is perfect for an 80 column text mode. But what if other text or column modes are used? How can we ensure that it is always centered? Only one simple change is needed: ... qfill( 1, 1, crt_rows, crt_cols, LIGHTGRAY, ' ' ); qwritec( 5, 1, crt_cols, SAMEATTR, "QWIK writing is easy!" ); return; } The variable crt_cols always has the value of the column width that is currently being used. How does it know? QWIKC is initialized at startup by executing a function called qinit(). It detects a host of information about your video configuration, everything from the type of video card you are using to the shape of the cursor being used. You can see a list of all these variables available for your use in QWIKREF.DOC. qinit() - You probably have noticed that qinit() is the first function called in every program. This is essential before using any QWIKC functions so that all CRT information can be correctly initialized. If you forget this, you can be certain your program will either crash or at least misbehave! FUNCTIONS Now that you have a basic idea of what QWIKC can do, let's make a brief 9 QWIKC Screen Utilities User's Guide, Version 2.1 survey of all the functions in QWIKC21S.LIB to just know what is available: One initializing function: qinit() - Initializing function which sets the global variables for the QWIKC functions. It should be called at the top of your program before calling any QWIKC functions. qreinit() - Should be called after a change from one text mode to another. Three quick direct screen writing functions, all work with or without attribute change: qwrite() - For any string. qwritec() - For any string; self-centering. qwrite_sub() - For any substring or part of a byte array. Four quick direct screen filling functions in rows-by-cols block parameters: qfill() - Repetitive filling with the same character; with or without attribute change. qfillc() - Same as qfill(), but self-centering. qattr() - Repetitive filling with an attribute only. qattrc() - Same as qattr(), but self-centering. Two quick screen storing functions: qstoretomem() - Saves a rows-by-cols block to memory. qstoretoscr() - Restores a rows-by-cols block to any screen page. Two quick screen storing functions for copying blocks between a screen (scr) and a virtual screen (vscr - a screen in memory): qscrtovscr() - Copies a rows-by-cols block from QWIKC screen to virtual screen. qvscrtoscr() - Restores a rows-by-cols block from a virtual screen to the QWIKC screen. Three quick screen reading functions for reading data from any screen: qreadstr() - Reads a string of text. qreadchar() - Reads a single character. qreadattr() - Reads an attribute. Two quick scrolling functions work on any video page and also virtual screens without flicker or snow: qscrollup() - Scroll affected rows-by-cols block up. qscrolldown() - Scroll affected rows-by-cols block down. Two quick video page changing functions: 10 QWIKC Screen Utilities User's Guide, Version 2.1 qviewpage() - Changes the page to be displayed - up to 8! qwritepage() - Sets the page on which the QWIKC functions are writing. You don't have to write just on the displayed page! Three quick cursor functions which work on any video page. They now work on the page being written rather than viewed: gotorc() - Move cursor to absolute row and column coordinates rather than relative to a window. wherer() - Returns absolute cursor row. wherec() - Returns absolute cursor column. Eight quick EOS (end-of-string) marker functions that alter its position and/or the cursor. The marker can be moved on the CRT and virtual screens, while the cursor movement is only on the page being written: gotoeos() - Moves cursor to EOS marker (like printf). eosr() - Returns absolute row of EOS marker. eosc() - Returns absolute col of EOS marker. eostorc() - Sets EOS to a given row and column. eostorcrel() - Relatively shifts EOS by a number of rows and columns, and can be negative or positive. eostocursor() - Matches EOS to the cursor position. eosln() - Moves EOS to column 1 of the next row. qeosln() - Like eosln(), but scrolls up if past last row. Three cursor routines alter the cursor mode: getcursor() - Get current cursor mode from low memory. setcursor() - Sets new cursor mode. modcursor - Modifies cursor mode to on, off or erratic blink saving current scan lines. Four quick EOS writing function that chain write at the EOS marker: qwriteeos() - like qwrite(). qwriteeos_sub() - like qwrite_sub(). qfilleos() - like qfill(). qattreos() - like qattr(). A submodel identification routine: get_submodel_id() - Optional function to find IBM submodel ID. A routine to set screen pointers to multi-tasking video buffers: setmultitask - Alters QWIKC to write to the multi-tasking buffer. For a full description of each utility with its parameters, please refer to QWIKREF.DOC for a summary of details and examples. 11 QWIKC Screen Utilities User's Guide, Version 2.1 3. B A S I C T E C H N I Q U E S CURSOR MODE ROUTINES Three Routines - If you have ever struggled with controlling the shape of the cursor, your life is about to be made easier. With just three routines, setcursor(), getcursor(), and modcursor(), you can consistently and reliably control the cursor mode (shape and visibility) on any video card! Four Standard Modes - To make it even easier, four standard cursor mode variables are initialized at startup to fit the exact requirements of the detected video card. They are: cursor_underline - The standard underline cursor. cursor_half_block - The half block shape usually used for insert editing. cursor_block - An easy to find full cell cursor. cursor_initial - The mode detected at start up. So, if we wanted a full block cursor, only one line of code is needed: setcursor( cursor_block ); And that's it! There's nothing else to figure out - even if you are using something like 43-row mode on an EGA card. When ending your programs, you can get back to the original cursor mode by using: setcursor( cursor_initial ); Hidden Cursor - Many programs need to hide the cursor altogether. This can be done with modcursor(): modcursor( cursor_off ); Why use modcursor() instead of setcursor()? modcursor() leaves the shape of the cursor alone, and only alters bits 13 and 14 of the cursor mode to turn it on or off. In fact there are three macros that are useful with modcursor(): cursor_off (0x2000) - To turn the cursor off. cursor_on (0x0000) - To turn the cursor back on with the same shape. cursor_blink (0x6000) - To create erratic blinking on MDA/CGA. (On EGA/VGA, it turns the cursor off.) Using your imagination, you can also mix and match the macros and variables by logically summing them. Let's say we want to change the shape of the cursor to a block while it is still turned off: setcursor( cursor_block | cursor_off ); So, the next time modcursor( cursor_on ) is used, the cursor will be a full block. As a suggestion for terminating your program, be sure to restore the cursor when exiting your program with: 12 QWIKC Screen Utilities User's Guide, Version 2.1 setcursor( cursor_initial ); getcursor() - This function simply returns the current cursor mode value stored in low memory allowing you to save it for later use. CURSOR LOCATION ROUTINES QWIKC has three routines that complement routines found in Turbo C - gotorc(), wherer(), and wherec(). They correspond with Turbo C's gotoxy(), wherex(), and wherex(). However, there are some important differences: . The QWIKC routines are absolute to the screen and are not restricted by the Turbo C text window. . The suffixes "r" and "c" mean row and column, so the parameters of gotorc() are reversed from gotoxy(). . The QWIKC routines will also work on any video page. This is explained in the Advanced Techniques section later. This is not the only way to move the cursor. The EOS marker is also a very powerful aid, as you will see in the next topic. EOS MARKER Invisible Alternate Cursor - From the examples in the Simple Programming topic, we found that we could easily chain two strings together using the EOS marker. In fact, this marker is so versatile, the EOS marker utilities can be made interchangeable with the cursor, but much faster. You could think of it as an alternate cursor that is invisible. Keeping Track - Any time a QWIKC writing function is used, the EOS marker is updated. It is actually saved as the global variable qeosofs. Technically, the value is the offset from the screen base and is a 0-based byte count. For example, if the following function was called: qwrite( 6, 5, YELLOW, "important data" ); the EOS would be at row 6, column 19, right after the word "data". The value of qeosofs on an 80 column screen would be: qeosofs = ((row-1)*crt_cols + (col-1)) * 2 = 836 QWIKC does not need to calculate this value, but simply saves it after writing, so it is very efficient. From the overview, you are already aware of the four routines that will start writing at this marker - qwriteeos(), qwriteeos_sub(), qfilleos(), and qattreos(). But what about changing the location of the marker itself? Keep reading. Moving the Marker - QWIKC has four routines that will manually move the EOS marker: eostorc() - Sets EOS to a given row and column. eostorcrel() - Relatively shifts EOS by a number of rows and columns, and can be negative or positive. 13 QWIKC Screen Utilities User's Guide, Version 2.1 eosln() - Moves EOS to column 1 of the next row. qeosln() - Like eosln, but scrolls up if past last row. The basic function eostorc() moves the EOS marker exactly like gotorc does for the cursor. But there are also several ways to move the marker rela- tively. Let's test a short program: #include <stdio.h> #include <conio.h> #include "qwikc21.h" main() { qinit(); textcolor( YELLOW ); qfill( 1, 1, crt_rows, crt_cols, LIGHTGRAY, ' ' ); qwrite( 1, 1, YELLOW+BLUE_BG, "first row "); eosln(); /* Jump to (2,1) */ qwriteeos( YELLOW+BLUE_BG, "second row "); eostorc( 3, 1 ); /* Jump to (3,1) */ qwriteeos( YELLOW+BLUE_BG, "third row "); eostorcrel( 1, -4 ); /* Jump to (4,8) */ qwriteeos( YELLOW+BLUE_BG, "etc." ); eostorc( eosr()+1, 8 ); /* Jump to (5,8) */ qwriteeos( YELLOW+BLUE_BG, "etc." ); getch(); return; } Save the file, then compile and run the program. You should see "row" and "etc." all aligned in one column. So, you can see that there are several simple ways to move the marker! EOS and the Cursor - You can also interface the EOS marker and the cursor with two functions: gotoeos() - Moves cursor to match the EOS marker. eostocursor() - Sets the EOS marker to match the cursor position. It can't get any simpler than that! Now you can see that: qwrite( 1, 1, YELLOW, "test line" ); gotoeos(); and, textcolor( YELLOW ); gotoxy( 1, 1 ); cprintf( "test line" ); produce identical results. But QWIKC is much faster! SCROLLING Improved Control - With your compiler's routines, you can only control the 14 QWIKC Screen Utilities User's Guide, Version 2.1 full screen size with printf() or cprintf(). But with the two QWIKC routines, qscrollup() and qscrolldown(), you can define any area to be scrolled: qscrollup( 2, 2, crt_rows-2, crt_cols-2, myattr ); This example scrolls a portion of the screen starting at (2,2) leaving a one character border. In a 25x80 text mode, it clears row 24 from column 2 to 79. In addition, the cleared row attribute is myattr. Improved Performance - With qscrolldown() and qscrollup() (called qscroll* for brevity), your programs can overcome the BIOS problems on many machines. Transparent to you, these functions work on all cards and machines without flicker or snow and operate at three speeds: Maximum - for video cards without snow Fast CGA - for CGA cards on 80286 machines or better Slow CGA - for CGA cards on 8086/8088 machines qinit() detects the CPU ID and video card to select the fastest algorithm. All speeds use 16-bit transfers rather than 8-bit. So, you can be assured of the highest performance. Cursor Location - These routines do not move the cursor. However, EOS is pointing to the first column of the blank line and gotoeos() will move the cursor there if needed. qeosln - This function is another alternative to full screen scrolling. It has the same function as eosln(), but will additionally scroll the screen up if the EOS marker is past the last row. Then it simply calls qscrollup(). The attribute of the cleared row is the global variable scroll_attr. You must set this prior to using qeosln(). POP-UP WINDOWS QWIKC has the basic tools to create and remove pop-up windows. Let's try to create one. While in your editor, enter the following code: #include <stdio.h> #include <conio.h> #include <dos.h> #include "qwikc21.h" int mywindow[250],myunderlay[250]; main() { qinit(); /* -- Fill the screen with a hatch character. -- */ qfill( 1, 1, crt_rows, crt_cols, LIGHTGRAY+BLACK_BG, 176 ); /* -- Create a pop-up window. -- */ qstoretomem( 5, 12, 10, 25, myunderlay ); /* Save area to be covered */ 15 QWIKC Screen Utilities User's Guide, Version 2.1 qfill( 5, 12, 10, 25, BLACK+LIGHTGRAY_BG, ' ' ); /* Clear area */ qwritec( 9, 12, 36, SAMEATTR, "Pop-up window" ); /* Label window */ suspend( 1000 ); /* Wait a sec */ qstoretomem( 5, 12, 10, 25, mywindow ); /* Save a copy */ qstoretoscr( 5, 12, 10, 25, myunderlay ); /* Restore screen */ /* -- Move window some where else. -- */ qstoretomem( 8, 25, 10, 25, myunderlay ); /* Save area underneath */ qstoretoscr( 8, 25, 10, 25, mywindow ); /* Move window */ suspend( 1000 ); /* Wait a sec */ /* -- Remove window. -- */ qstoretoscr( 8, 25, 10, 25, myunderlay ); /* Restore screen */ getch(); return; } Save the file. You will see a 10 row by 25 column window located at (5,12) which is row 5, column 12. After one second, it will be moved to (8,25). Then after another second, it is removed from the screen. We did a lot of work with very little code! Rows-by-Cols - qstoretoscr() and qstoretomem() are screen saving and restoring functions that conveniently work in row-by-column blocks. They accommodate any column mode, so there is no need to be concerned about screen width. Memory Requirements - Notice that qstoretomem() wrote the data direct to memory in mywindow. It is important that the memory allocated to that variable is correct to prevent it from overwriting any other variables. The array size chosen was a 250 word array which is a perfect fit since one word is needed for each character and attribute on the screen. If you prefer, the heap can also be used such as: int *myunderlay; main() { myunderlay=malloc(500); qstoretomem( 5, 12, 10, 25, myunderlay ); /* ... */ free( myunderlay ); } MEMORY MODELS AND LIBRARIES Separate Library Files - QWIKC comes with several .LIB (library) files. The correct .LIB file for your memory model must be linked with your program. Here is a list of the .LIB files and their corresponding models: QWIKC21T.LIB - Tiny model QWIKC21S.LIB - Small model QWIKC21M.LIB - Medium model QWIKC21C.LIB - Compact model 16 QWIKC Screen Utilities User's Guide, Version 2.1 QWIKC21L.LIB - Large model QWIKC21H.LIB - Huge model Linking - If you have Turbo C, the library's name must be listed in your project file. For MicroSoft C or QuickC, instruct your compiler to link the library when executing it. You must also include QWIKC21.H in your program so that the macros and function prototypes for QWIKC will be set correctly. Libraries and Object Files - The library files that come with QWIKC contain the object code for QWIKC's modules. If it is necessary to extract an object file, such as QWRITES from the Small model library, enter the following at the DOS prompt: tlib qwikc21s *qwrites The file QWRITES.OBJ will be extracted and placed in the current directory. Since the linker optimizes the code anyway, this procedure will probably not be necessary. 17 QWIKC Screen Utilities User's Guide, Version 2.1 4. A D V A N C E D T E C H N I Q U E S This section will acquaint you with the powerful virtual screen writing features already built into QWIKC. You will also find out how easy it is to work on multiple video pages and accommodate video mode changes. VIRTUAL SCREENS This topic will show you how to create and use powerful virtual screens. Virtual Screen - Just what is a virtual screen? It is a screen maintained in RAM of any dimensions that can be reproduced on the CRT in full or in part. The advantages are: . Variable row-by-column screen . Large video buffer up to 64k . High speed in RAM . Unlimited number of screens Screen Structure - QWIKC uses seven variables to define any screen. When you call qinit() at the top of your program, QWIKC initializes them to the video system detected: crt_rows - Number of rows crt_cols - Number of columns crt_size - Byte allocation for screen qsnow - True if snow checking needed qeosofs - EOS offset qscrofs - Screen offset qscrseg - Screen segment qscrptr - Far pointer to screen memory or virtual screen To make data access even easier, all these variables are contained in the structure qscr of type vscr_t. In addition, qscrseg and qscrofs are actually macros pointing to the segment and offset of qscrptr. This gives QWIKC a true far pointer, so screens can be anywhere in memory and not just paragraph aligned! Creating Virtual Screens - In three easy steps, you can easily create a virtual screen: 1. Allocate memory for the screen. 2. Save the current screen structure. 3. Modify the screen structure for the virtual screen. Let's write some code that does just that: #include <stdio.h> #include <stdlib.h> #include <conio.h> #include "qwikc21.h" vscr_t crt,vscr; 18 QWIKC Screen Utilities User's Guide, Version 2.1 main() { qinit(); /* set up specs for virtual screen */ vscr.vrows=80; /* let's choose 80 rows */ vscr.vcols=100; /* let's choose 100 columns */ vscr.vsize=vscr.vrows*vscr.vcols << 1; vscr.vsnow=0; /* flag can always be 0 on virtuals */ vscr.veosofs=0; /* be safe and start at the base */ vscr.vscrptr=malloc(vscr.vsize); /* allocate heap space for vscr */ crt=qscr; /* save CRT specs */ qscr=vscr; /* set current screen to our screen */ /* ... */ /* write to the virtual screen */ qscr=crt; /* restore CRT specs when done! */ return; } Now, when you use any QWIKC routine, they can be directed to the virtual screen - writing, reading, scrolling, wrapping, and everything you would expect. qsnow can always be 0 when writing to virtual screens since RAM is used and not video card memory. Cursor Control - One thing not available to virtual screens is cursor movement, because the cursor location is reserved by DOS for just video pages. That means there is no cursor available for virtual screens. So, how can we get around this? The EOS marker comes to the rescue as an indispensable cursor! All EOS routines can still be used as before. Taking a Peek - At some time, we will need to take a look at all or a portion of the virtual screen by copying it to the CRT. Two inter-screen functions do this by blocks at high speed - qscrtovscr() and qvscrtoscr(). Here are the parameters of qvscrtoscr: qvscrtoscr( row, col, rows, cols, vrow, vcol, vwidth, vscrptr ); Just like qstoretoscr(), row, col, rows, and cols describe the position and size on the screen (scr). This screen is specified by qscr which is usually the CRT. vscrptr points to the virtual screen (vscr). Now, where is the same size block on vscr? It's at vrow and vcol. But the vscr may have a different column width than crt_cols. So you specify that with vwidth. Only the scr side checks for possible snow. These functions are extremely fast, making virtual screens very practical. See qscrtovscr() and qvscrtoscr() in QWIKREF.DOC for more examples. Multiple Virtual Screens - By changing qscr, you can even copy blocks from one virtual screen to another! These routines do not affect qeosofs. VIDEO PAGES Multi-page Cards - Turbo C functions such as window and gotoxy, and C's printf are dedicated to just page 0, but many video cards have more than one page. If you have a CGA or better, you already have memory on your 19 QWIKC Screen Utilities User's Guide, Version 2.1 card for 4 to 8 pages. Since the BIOS recognizes them as well, QWIKC gives you access to these extra pages. Page Control - qwritepage() and qviewpage() give you the power to use QWIKC on all video pages and display which ever you choose. On a multiple-video page card like the CGA, you can simply code: qwritepage( mypage ); to make all QWIKC routines be directed to your selected video page even though you could be viewing another page. To view a page, you can in turn simply code: qviewpage( mypage ); Tips About Pages - Here are some tips to keep in mind when using several video pages: . The highest valid video page is detected by qinit() and saved in the variable maxpage. . Invalid page parameters are just ignored. . The BIOS reserves a separate cursor location for each of up to 8 video pages. . There is only one possible cursor mode, which is always displayed on the CRT. . The cursor location routines operate on the page being written rather than viewed. . The current video page viewed is in the variable videopage. . The current video page set by qwritepage() is saved in qvideo_page. . Be sure to end your programs with "qviewpage(0);". VIDEO MODES Changing Text Modes - Your application may require a change in video modes for different row or column modes. If so, after the mode is changed, run qreinit() so the video variables will be correct. Text color - Be advised that a change of text modes with the textmode() function will also change your text color setting. It is reset to normal, corresponding to a call to normvideo(). Graphic Modes - If you need to alternate with a graphics mode, qreinit() does not need to be called provided you return back to the same text mode. Of course you may want to save the screen with qstoretomem() before switching to graphics. Changing Monitors - The technique to change monitors is to simply change the text mode. This means qreinit() should be called. Be sure to toggle the video mode bits in the equipment list byte at 0040h:0010h so other applications can behave properly. cursor_initial - When you call qinit() at the top of your program, cursor_initial saves what it detects for the current video mode. When you call qrenit() after a text mode change, cursor_initial is also changed. 20 QWIKC Screen Utilities User's Guide, Version 2.1 This may affect how you restore the cursor when terminating. If needed, the value should be saved before using qreinit(). MULTI-TASKING ENVIRONMENTS Multi-Tasking - QWIKC works very well with multi-tasking environments such as DESQview. For examples on how to let QWIKC work in DESQview specifically, see a file called DESQC20.ARC (CIS: DSQC20.ARC) or a later version. setmultitask - A simple procedure has been included that generically detects the presence of DESQview, TopView, TaskView, OmniView, MS Windows or IBM 3270 PC multi-tasking video buffers (MTVB). If they are being used, setmultitask will alter qscrptr, page0seg, and qsnow correctly. This is a very simple task. All of the *.C files included with the code show where the setmultitask declaration is to be placed early in the program. If you are unsuccessful in getting it to work as you would expect, give us a call. inmultask - If setmultitask did indeed alter qscrptr for the MTVB, then inmultitask is set to 1. Multiple Video Pages - Be sure to instruct the multi-tasking environment of the number of video pages that are being used for your program. Since some environments cannot correctly use multiple pages with the MTVB such as DESQview 2.01, it has been disabled in the demos with the use of inmultask. Cursor Routines and the BIOS - All cursor routines that change the mode and location use the BIOS. This way multi-tasking environments can handle redirection properly. INTERRUPTS Within QWIKC - QWIKC only uses video interrupt 10h for qinit(), qreinit() and the cursor routines, so there no problem with DOS reentry. Please read about "System Hardware" in Chapter 5 for more information on get_submodel_id() which uses INT 15h. Creating Handlers - If you use interrupt calls (like a clock display) within your program that use QWIKC routines, be sure to save and restore the value of qscr in the call so it won't return to the main program with unexpected results. You should also be aware that main program may be writing to a virtual screen during the interrupt, so it is best that you initialize a copy of qscr solely for the interrupt. 21 QWIKC Screen Utilities User's Guide, Version 2.1 5. H A R D W A R E D E T E C T I O N DISPLAY COMBINATION CODE qinit() function - qinit() initializes all the variables needed for the QWIKC functions, and specifically checks for ALL IBM video equipment including dual monitors. qinit() MUST BE CALLED by your program before calling any QWIKC functions! If you do not, you will get unexpected results. Display Combination Code (DCC) - The PS/2 video BIOS has a new function that simplifies equipment detection called the Read/Write Display Combination Code. Using interrupt 10h with AH = 1A00h, the call will return the Active Display Device in BL and the Alternate Display Device in BH. If the function is supported, it also returns 1Ah to AL. For the possible Display Device codes which have been assigned by IBM, see QWIKREF.DOC. Conforming to DCC - No results are obtained for the DCC on anything other than PS/2 equipment. However, to be consistent, qinit() was reprogrammed to conform to the DCC for ALL equipment. To see if a CGA is in use, simply check to see if active_disp_dev=cga_color. qinit() only sets the parameters for the active display. Dual Monitors - qinit() detects dual monitors and saves both the active and alternate display device codes. The alternate display device code is for testing purposes only. If you change monitors in a running program, qreinit() should be called. Testing for Dual Monitors - qinit() makes an attempt to detect for a second monitor by several means. If no alternate cards like EGA or VGA are found, an alternate 6845 video chip (CGA, MDA, or Hercules) is checked. If the chip is found, then further tests are made to find which card it could be. The chip existence test is highly reliable. If no alternate display device is found, then alt_disp_dev=no_display. have_ps2 - qinit() sets have_ps2 to 1 if the DCC is supported. This means that the program has detected a PS/2 video card whether it is integrated in a Model 30, a PS/2 Display Adapter installed on an IBM XT, or the like. It also means that either MCGA or VGA is present, but not necessarily active. To know which, just check the DCC. have_3270 - If qinit() detects 3270 PC equipment/software, this variable is set to true. In addition, the active_disp_dev is either mda_mono or cga_color. Note: There may or may not be graphics capability in either case; qinit() is not meant to detect graphics. If have_3270 is 1, then active_disp_dev_3270 will be set to the proper code. On the 3270 PC, dual monitors are not possible as they use the same physical buffer space. In addition, even though a color monitor may be used, there is only one video page unless there is a special adapter. However, qinit() will determine if more than just one page is available. The 3270 PC also does not support 40 column modes. EGA Switches - By checking the value of this byte, you can determine the 22 QWIKC Screen Utilities User's Guide, Version 2.1 monitor connected to the EGA, the alternate video system, and the start up default. The byte is a copy of how the dip switches are set on the card where on=0 and off=1. The primary is the default. When the ECD is set for 640x200, it is emulating the CD including the cursor mode. qinit() directly tests for the alternate device rather than assuming it. EGA Information - The byte located at 0040h:0087h has hardware status information when the EGA (or VGA) is present. PC Convertible (PCC) - Since the PCC also does not support the DCC, a separate code is used. If the 5140 LCD is used in mode 7, the Active Display Device is set to mda_mono which is close enough. This set up can be verified by testing if maxpage=3. The alternate display is found by using interrupt 10h with AH=15h. The result is saved in alt_disp_dev_pcc. Of course the variable is undefined if a PCC is not used. Hercules - Hercules cards are also detected. If either the active or alternate DCC is mda_mono, which is found by verifying a responsive 6845 video chip at the mono register port, then an attempt is made to find if any Hercules card is attached. If no Hercules card is found, then herc_model is no_herc; it is then assumed that just an MDA card is attached. Because the test can take up to 1/3 of a second on slower computers, this test is only run once, even if you call qreinit(). The tests for the Hercules cards are the ones recommended by Hercules Computer Technology, which also admits that sometimes the tests will fail during multi-tasking activity. Hercules clones may not be detected by these tests, but the DCC will be correct. SNOW CHECKING CGA Snow - QWIKC is conservative with CGA cards and uses snow checking when the card is detected. However, it is not needed in 40 column modes 0 and 1. qinit() was programmed to accommodate this. For other hardware, you can change qsnow to suit your needs, but cardsnow should be left unchanged to save what qinit() detected. Zenith CGA - Zenith CGAs do not need wait-for-retrace. If you would like to accommodate this, you can execute the following function after calling qinit() and after each qreinit(): void check_zenith(void) { char tmp[10]; movedata( 0xF000u, 0x800Cu, (unsigned)(((char far *)tmp)+1), (unsigned)((char far *)tmp), 8 ); if(qsnow && (strncmp( tmp, "ZDS CORP", 8 )) == 0) { qsnow=0; cardsnow=0; } } Critical Timing - The timing on the IBM PC (Intel 8088 at 4.77MHz) with a CGA is critical for storing characters and attributes with 16-bit transfers 23 QWIKC Screen Utilities User's Guide, Version 2.1 because of the CPU architecture and slow speed. Although previous versions kept the timing as tight as possible, there still remained a hint of snow in column 1. This is due to the problem that RAM runs a little slower than BIOS ROM. This problem has now been solved with a minor code change. So the routines still run at the same speed, but there is absolutely no snow! I am not aware of any other routines that have done this as closely. (Computers with slower access RAM chips may still show up some variations from time to time. Feedback is requested.) SYSTEM HARDWARE System ID - The basic computer system identification (or model) for IBM computers can be found by directly accessing the byte in memory at F000h:FFFEh. SubModel ID - After production of the AT, models were also given Submodel IDs. To get both the model and submodel ID, you must use interrupt 15h with AH=C0h which only works on some computers. A few PC and XT clones like the AT&T 6300 will actually crash when this interrupt is executed due to BIOS bugs. So to prevent this from happening, the function only lets system IDs of FCh or less get the submodel_id. In addition, it is a separate function called get_submodel_id() and is not a part of qinit(). So you will have to execute it yourself to get a result. The routine is entirely optional and is not required by QWIKC. CPU Identification - A CPU detection routine has been included for Intel processors. It is useful for clones that do not recognize IBM's system ID scheme. The idea came from Juan Jimenez as it appeared in Jan/Feb '88 Turbo Technix magazine. The routine has been simplified for reduced code (only 42 bytes) and enables use of simple macros. This routine is required for qscrollup/down(). 24 QWIKC Screen Utilities User's Guide, Version 2.1 A P P E N D I X A : V I D E O M O D E T A B L E Video Modes - To help you figure out how all the IBM video systems are configured, it is helpful to have a table of all the possible Alphanumeric (A/N or text) modes. QWIKC was not designed for the All Points Addressable (APA or graphics) modes. TABLE 1: Hardware Specific Video Mode Characteristics ------------------------------------------------------------------------------- Mode Format Segment Display Box MDA CGA EGA MCGA VGA PCjr PCC 3270 HGC maxpage ---- ------ ------- ------- ---- --- --- --- ---- --- ---- --- ---- --- ------- 0,1 40x25 B800:0 320x200 8x8 x x x x x x 7 320x350 8x14 x x 7 320x400 8x16 x 7 360x400 9x16 x 7 2,3 80x25 B800:0 640x200 8x8 x x x 3 640x200 8x8 x x 7 * 640x350 8x14 x x 7 * 640x400 8x16 x 7 720x350 9x14 x 0+ 720x400 9x16 x 7 7 80x25 B000:0 720x350 9x14 x x x x 0 720x350 9x14 x x 7 * 720x400 9x16 x 7 640x200 8x8 x 3 ------------------------------------------------------------------------------- Legend: Format - Characters per row by the number of rows in the data area. Segment - Address of the first character on page 0 of the display buffer. Display - The pixel resolution for the data area excluding the border, horizontal by vertical. Box - The pixel resolution for each character, horizontal by vertical. MDA - Monochrome Display and Printer Adapter CGA - Color Graphics Adapter EGA - Enhanced Graphics Adapter PGC - Professional Graphics Controller MCGA - Multi-Color Graphics Array VGA - Video Graphics Array PCjr - PC Junior PCC - PC Convertible HGC - Hercules Graphics Cards - HGC, HGC Plus, and InColor Card 3270 - All IBM 3270 PC adapters maxpage - 0-based highest page number; e.g. 7 means there are 8 pages. MD - 5151 Monochrome Display CD - 5153 Color Display ECD - 5154 Enhanced Color Display Notes: 1. The 0 and 2 modes suppress color burst only on composite displays (not RGB) only for CGA and EGA. 25 QWIKC Screen Utilities User's Guide, Version 2.1 2. The PS/2 model 25 and 30 have an integrated MCGA. The model 30/286, model 50 and above have an integrated VGA. 3. The 8514 High Content Color Display along with the 8514/A adapter produces a superset of the VGA for APA, but there are no differences in the A/N modes to the VGA when the adapter is in "VGA" mode. See IBM documentation for Advanced Function Mode. 4. maxpage is reduced to 3 if EGA only has 64K graphics memory installed for modes marked "*". maxpage of 7 is for 128K or more. 5. The PCC can have either an alternate MDA or CGA. The LCD (model 5140) can emulate either the MDA or CGA modes, but the MDA mode is 640x200. 6. No information is provided on the PGC. 26 QWIKC Screen Utilities User's Guide, Version 2.1 A P P E N D I X B : C U R S O R M O D E D A T A Each video card differs in character cell size and cursor emulation in different video modes. The following data will show you the specific differences between modes and cards, and how QWIKC handles them. CURSOR MODE TABLES Cursor Mode Word - The cursor mode is saved in low memory at 0040h:0060h after each mode change. Using hex is the easiest way to analyze the word. The shape of the cursor is defined by horizontal scan lines in the character cell where the top row of any cell is 0. TABLE 2: Cursor Mode Word ------------------------------------------------- Hi byte Lo byte ----------------------- ----------------------- Bit #: 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00 Bit #: 07 06 05 04 03 02 01 00 07 06 05 04 03 02 01 00 Symbol: $ $ * * * * * @ @ + + + + + Key: $ - controls cursor on/off and erratic blinking * - controls top scan line (0-based) @ - controls skew to the right + - controls bottom scan line (0-based) Skew - Bits 5 and 6 control the skew or shift to the right of the cursor on EGA/VGA cards. Consistent results between video cards are not possible so it is best to leave these bits at zero. Cell Sizes - Because of different cells sized with different video cards, the top and bottom scan lines are also different for each card. See TABLE 1 in Appendix A for specific cell sizes. TABLE 2: Cursor Mode Defaults ---------------------------------------------------------- Adapter Default Comments -------- ------- --------------------------------------- MDA 0B0Ch CGA,MCGA 0607h EGA 0B0Ch MD, ECD (640x350 25-line) Emulation off EGA 0607h CD, ECD (640x200) VGA 0D0Eh Emulation off 3270 PC 0D0Dh And converts MDA and CGA CURSOR EMULATION Cursor Emulation - qinit() sets the four standard cursor mode variables at startup to be either MDA or CGA defaults. Almost all emulation modes can be handled by either of these two cell sizes. qinit() handles certain exceptions. If you want to handle your own exceptions, the following notes will help you. 27 QWIKC Screen Utilities User's Guide, Version 2.1 cursor_blink - This mode is hardware specific. It works on MDA and CGA while it turns the cursor off on EGA and VGA. MCGA/VGA Cursor Mode - On these two cards, you can both read and write the cursor mode direct from the CRTC. To be compatible with all video cards, QWIKC does not attempt to do this, but instead depends on the Video Display Data Area at 0040h:0060h. qinit() turns on the cursor emulation mode if PS/2 video equipment is detected. EGA Cursor Emulation - In 25-line mode on the EGA, cursor emulation works fairly well. In other line modes, the emulation falters. So qinit() forces emulation to be turned on in 25-line mode and off in other modes. On the EGA, emulation is turned off by setting bit 0 of egainfo to 1. The standard QWIKC cursor modes are still set appropriately. MCGA Cursor Emulation - Use the CGA cursor cell size even though the character cell is 8x16. The BIOS multiplies the start and end rows by 2 and then adds one to the end row before writing to the hardware video port to emulate the CGA. VGA Cursor Emulation - qinit() turns the cursor emulation mode on so you don't have to worry about special fonts and cell sizes as it emulates the MDA and CGA. The video BIOS will adjust your cursor shape to fit in the current cell size. For the algorithms specific to the VGA, refer to the "IBM Personal System/2 and Personal Computer BIOS Interface Technical Reference Manual". 3270 PC Peculiarities - The 3270 PC cursor types are limited to only three. In addition, the underline cursor is not visible on a white background on the 5272 color display and it is advisable to use a block cursor together with that attribute. Notice that half-block cursors are converted to full block: TABLE 3: 3270 PC Cursor Modes -------------------------------------------------------------- Cursor Type Comments ------------ ------------------------------------------------ Underline 0D0Dh only. CGA and MDA are emulated. Hidden (off) cursor start > cursor end. 2000h is preferred. Block anything other than the above Start Up Cursor Modes - Once QWIKC determines the cell size and the cursor emulation mode, the four standard cursor modes, cursor_initial, cursor_underline, cursor_halfblock and cursor_block are calculated: cursor_initial - This is the cursor mode detected at startup. An improper default for MDA is automatically overridden to an underline. Some early PCs have a BIOS bug that sets the MDA default incorrectly. cursor_underline - The lower scan line is set to: (bottom of cell-1). The upper scan line is set to: (lower scan-1). 28 QWIKC Screen Utilities User's Guide, Version 2.1 cursor_half_block - The top scan line is set to: (bottom of cell+1)/2. This may appear a little fat for EGAs in 25-line mode, but is just right for all other cards and modes. cursor_block - Produces a block cursor by setting the top scan line to zero of cursor_underline. 29 QWIKC Screen Utilities User's Guide, Version 2.1 A P P E N D I X C : P E R F O R M A N C E CODE SIZE If you use a QWIKC function, only the corresponding object file containing that function will be linked, thus optimizing the code. Even if all func- tions are used, QWIKC is still quite small at a total of approx. 2681 bytes. Here's the linked code size for the small model (size varies slightly between models): FILE NAME BYTES FUNCTIONS ------------ ----- ------------------------------------------------- qinit .obj 608 qinit, qreinit qwrites .obj 282 qwrite, qwritec, qwriteeos qfills .obj 451 qfill, qattr, qfillc, qattrc, qfilleos, qattreos qstores .obj 321 qstoretoscr, qstoretomem, qscrtovscr, qvscrtoscr qreads .obj 131 qreadstr, qreadchar, qreadattr qscrolls.obj 271 qscrollup, qscrolldown qpages .obj 59 qwritepage, qviewpage cursor .obj 92 gotorc, wherer/c, setcursor, getcursor, modcursor eos .obj 124 gotoeos, eosr/c, eostorc/rel, eostocursor, eosln qeosln .obj 38 qeosln cpuident.obj 42 getcpuid getsubid.obj 27 get_submodel_id setmulti.obj 29 setmultitask qwrsub .obj 206 qwrite_sub, qwriteeos_sub SPEED How fast is fast? To have a basis for comparison, a unit of "screens/second" is used to get a feeling for speed. To make one screen, a function is repeated with a FOR loop to fill several 80x25 pages and timed. The qwrite*() functions use 80 character strings, and qattr() and qfill() use 25 rows and 80 cols. Here are some samples from the systems that have been tested. 16-bit video cards such as the one in the Compaq 386/20 will be much faster than 8-bit cards. --------------------- S C R E E N S / S E C O N D --------------------- Chng XT(4.77 MHz) M30 M50 M70 ATT+ Compaq Function Attr MDA CGA MCGA VGA VGA CGA 386/20 --------- ---- ------------ ----- ----- ----- ---- ------ qwrite- Yes 29.1 9.5 64.4 83.7 103.7 16.8 383.1 No 34.1 9.6 77.4 128.5 157.7 16.8 403.8 qfill- Yes 100.5 12.0 164.5 146.7 151.4 21.5 585.3 No 78.2 7.5 143.9 230.9 256.7 13.9 587.5 qattr- Yes 78.2 7.5 143.9 230.9 256.7 14.0 576.0 qstore- n/a 67.0 7.3 124.4 137.0 140.2 13.8 355.3 qscroll- n/a 55.6 3.8 90.3 76.5 77.7 16.8 322.1 Be sure to test QBENCH.C for virtual screens and find another significant increase in speed. All routines will be at least 100 Scr/Sec, and 500 Scr/Sec is typical. 30 QWIKC Screen Utilities User's Guide, Version 2.1 For those interested in comparisons, QWIKC's qwrite function is much faster than TC2 direct video writing routines by the following percentage: Function CGA cards All other cards --------- --------- ---------------- cprintf 225% 900% to 2300% 31 QWIKC Screen Utilities User's Guide, Version 2.1 A P P E N D I X D : A P P L I C A T I O N P R O D U C T S Eagle Performance Software has developed identical products for both Turbo C and Turbo Pascal. Our pledge is to provide you quality products with unparalleled performance and ease of use. QWIK QWIK - For direct screen video, QWIK is the highest performance screen writing tool available today for all text modes in any video configuration. QWIK provides capabilities far beyond those in the unit/library that comes with your compiler. Here are the product versions: File name CIS filename Compiler Release date ------------ ------------ -------- ------------ QWIK42B.ARC QWIK42.ARC TP4/5 10-01-88 QWIK5XA.ARC QWIK5X.ARC TP5 01-03-89 QWIKC21.ARC QWKC21.ARC TC2/MSC 06-01-89 WNDW WNDW - For multi-level virtual windows, WNDW is the highest performance window utilities package available today. It offers very powerful utilities for full window control and management you probably never thought possible. They are simple and yet very powerful with high speed and tight code. With WNDW, you can choose the absolute writing routines of QWIK, the window- relative writing routines of WNDW, and even customize your own. Here are some of the features you will discover: . Uses the powerful direct screen writing routines of QWIK. . Up to 254 fixed or virtual windows can be on the screen at one time. . Extremely high-speed virtual screens in RAM (up to 40 times faster). . Virtual windows are fully updated on screen, even if covered! . Virtual windows have virtual titles. . Fully supported hidden windows saved in RAM. . Fully supports all video pages. . Adjustable-rate moving, resizing, and scrolling. . All windows can be randomly accessed, not just stacked or tiled. . 28 window-relative writing routines. . 15 different border styles with shadow and zoom effects. . Full line drawing procedures. . Full cursor mode control for each window. . Writes in all text modes and column modes. . Only 13k bytes of code if all 69 utilities are used. . Used in all other Eagle products. 32 QWIKC Screen Utilities User's Guide, Version 2.1 Here are the product versions: File name CIS filename Compiler Release date ----------- ------------ -------- ------------ WNDW42.ARC WNDW42.ARC TP4/5 10-15-88 WNDW5XB.ARC WNDW5X.ARC TP5 01-15-88 WNDWC21.ARC WNDC21.ARC TC2/MSC TBA PULL PULL - For multi-level pull-down menus, PULL is fully featured and fully configurable. Includes execute, single, and multiple choice menus, unlimited nested submenus, data entry windows, help windows, directory windows, message system, and fully completed interfaces. Some of the features are: . Uses QWIK and WNDW. . Work window(s) and complete interface for menus . Pull-down menus with 5 menu modes and 7 line modes . Pull-down file directory . Highlighted command letters . Unlimited levels of submenus . Unlimited data entry windows for 9 types of data . Data entry for the work window(s) Full editing capability including insert cursor mode Full field selection with cursor keys Automatic NumLock for numerical data entry Right or left justification for data entry output Error messages for invalid data entries Error messages for data entries out of range . Automatic sizes and locations for menus. . Operation by cursor keys or command keys . Pull/Pop between work window and nested submenu(s) . Programmable control of pull and pop sequences . Context-sensitive help . Message lines for prompts and processing . Full working shell for user development Here are the product versions: File name CIS filename Compiler Release date ----------- ------------ -------- ------------ PULL42.ARC PULL42.ARC TP4/5 12-06-88 PULL5XB.ARC PULL5X.ARC TP5 02-15-89 PULLC21.ARC PULC21.ARC TC2 TBA ON-LINE SOURCE CompuServe - All updated files and later versions can be found on the CompuServe Borland Forums (GO BPROGA for TP and GO BPROGB for TC) or the IBM Programming Forum (GO IBMPRO). 33 QWIKC Screen Utilities User's Guide, Version 2.1 A P P E N D I X E : R E V I S I O N H I S T O R Y Version 2.0a (01-02-89): Fixed an oversight which caused videomode, videopage and crtcolumns to be inaccessible in all models except compact and huge. This occurred because they were not declared as PUBLIC in the QINIT modules. Version 2.0b (02-03-89): Row and Column sizes greater than 127 were not supported unless default char type was set to unsigned. All row/col parameters and variables are now specified as "unsigned char". Version 2.0c (03-06-89): Remedied qreadattr/char bug which trashed a function's local variables, due to the BP register not being restored correctly. Sped up qvscrtoscr and qstoretoscr by eliminating snow check. A wait-for-retrace was always done in these functions (for the Medium and Compact models only), due to an incorrect addressing method on the qsnow variable. Add setmultitask function to set variables for multitasking video buffers (MTVB). Forced null strings written to virtual buffers to leave qeosofs unchanged. Version 2.0d (03-22-89): Fixed another bug in qreadattr/char which popped SI/DI in the wrong order, thus losing local variables if optimization was turned on. Incorporated SETMULTI.C into the makefiles. Added macros for pointer variables to QWIKSCR.INC and changed QINIT.ASM so as to treat them as macros rather than variables. | Version 2.1 (06-01-89): | Converted to MicroSoft C / QuickC. SUSPEND routine added, | courtesy of Borland International. All programs now compile | under TC, MSC, or QC. 34 QWIKC Screen Utilities User's Guide, Version 2.1 A P P E N D I X F : R E F E R E N C E S REFERENCES PS/2 Systems - For more information on the new IBM PS/2 system, you can get the "Personal System/2 and Personal Computer BIOS Interface Technical Reference" manual. Other references include: IBM Personal System/2 Seminar Proceedings: Volume 5, Number 2, Displays and Adapters, publication # G360-2678. Volume 5, Number 4, Models 50, 60, 80, VGA, BIOS and Programming Considerations, publication # G360-2747. 3270 PC - For more information on the IBM 3270 PC, you can get the following publications: "3270 PC Application Development Considerations" "IBM 3270 Personal Computer Programming Guide", Pub # SA23-0221 "IBM 3270 Personal Computer Control Program Reference", Pub # GA23-0232 As always, the above information is subject to change without notice per IBM. Video Guide - An excellent guide for IBM and Hercules video card programming in text and graphics is: "Programmer's Guide to PC & PS/2 Video Systems" by Richard Wilton and published by Microsoft Press Trademarks - IBM is the trademark for International Business Machines Corp. Turbo C and Turbo Pascal are trademarks of Borland International. The SUSPEND routine called in the demonstration and example programs is used by permission of Borland International. 35