Category : C Source Code
Archive   : QWIKC21.ZIP
Filename : QWIKC21.DOC

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
#include
#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
#include
#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


8
QWIKC Screen Utilities User's Guide, Version 2.1


#include
#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
#include
#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
#include
#include
#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
#include
#include
#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