WINDOWS
Copyright 1987, 1988 Robert Kline

This is a package of functions which can be used in C programs for
windowed display and data-entry techniques on the IBM PC family and
compatible machines. A linked list is used to keep track of the windows
which have been opened at any point in the program, and the programmer has
control not only of which windows are visible, but which of overlapping
windows are in front, which in back. The package was developed as a
teaching tool for the Advanced C classes taught at the Alexandria campus of
the Northern Virginia Community College, and was used to show the students
how to build and use projects of moderate size. The calls to external
functions are restricted to the ANSI standard library, with the exception
of int86(), (which is widely available on C compilers for the 8086 family of
machines), and three functions written in assembly language, for which the
source code is provided. The package should be usable on just about every
serious compiler available for these machines. Two libraries have been
built, containing the object modules for the functions in the package,
one for the Borland and Microsoft C compilers ("WINDOWS.LIB"), and the
other for use with Lattice C ("LATTICE.LIB"). With a single exception
(w_printf()), both Turbo C (from Borland) and Microsoft C 5.x can use the
same library. If you will be using Microsoft C and calling w_printf(), you
will need to re-compile the function (see further explanation later in this
file). Unfortunately, I haven't been able to compile w_printf under the
version of Lattice C to which I have access, since it is missing va_start()
and vsprintf(). The libraries provided are set for use with the SMALL model.

Permission is granted to incorporate these functions in your
programs, commercial or otherwise. Copying and distribution of the package
is encouraged, provided no fee is charged for it.

Included in this package are the following files:
windows.doc this file
windows.h header file needed to compile or use these functions
w_init.c C source code files
w_open.c (8 altogether)
w_putc.c
w_center.c
w_close.c
w_cursor.c
w_fields.c
w_printf.c
w_putw.asm assembly-language code for three of the
w_memcpy.asm routines used
w_beep.asm
windows.lib library for Microsoft C & Turbo C
lattice.lib same for Lattice C
winddemo.c a driver to demonstrate the routines
winddemo.exe executable demonstration program
customio.c another demo
customio.exe

To compile and link winddemo with Turbo C, Command Line Version:
tcc -ms winddemo windows.lib

To compile and link winddemo with Turbo C, Environment Version:
create project file winddemo.prj to look like this--
winddemo
windows.lib
from the menu select Project, then winddemo.prj, then
press F9 key

To compile and link with Microsoft Quick C:
qcl /AS winddemo.c windows.lib;

To compile and link with Microsoft C 5.1:
cl winddemo.c windows.lib

To compile and link with Lattice C:
lc winddemo
link cs winddemo,winddemo,,lcs lattice

Same procedure will work with any other program. Just
substitute your file for winddemo.

Here are the functions in the package, with very brief descriptions:

w_init() sets up main_w, top_w; must be called before anything else
w_create() creates Window structure with passed parameters as settings
w_draw()copies data from window storage to screen
w_error() exits from program with message when malloc runs out of memory
w_clear()sets window's storage to spaces; does not affect screen display
w_show()calls w_draw() and w_border() to display window
w_border()draws single- or double-line border for window if it has one
w_title()puts window's title on screen if it has one
w_open() adds window to linked list (with w_link()) and displays window
w_link()adds window to top of linked list
w_select()moves open window to top of list
w_putc() displays character and saves it in window's storage
w_puts() displays string and puts it in window's storage
w__scroll()scrolls data in window storage without changing screen
w_scroll()scrolls data in window storage and on screen
w_center()centers a string on a given row of a given window
w_close()closes a window (does not destroy structure)
w_unlink()removes window from linked list
w_refresh()redraws screen from the bottom window up
w_dispose()releases the storage for a Window structure
w_putcrs()moves the hardware cursor to the window's current location
crs_off()turns off the cursor display
crs_on()turns on the cursor display
showField()display prompt and data area for field
getField()very sophisticated version of gets()
clearToEnd()delete from current field position to end of field
fieldStart()move to beginning of field
fieldEnd()move to end of field data
fieldLeft()move left one position in field, if possible
fieldRight()move right one position in field, if possible
toggleInsert()toggle value of insert flag
delChar()remove character at current position and close up string
backspace()destructive backspace, closing up string from right
addChar()adds character to string if it meets field specifications
fatCursor()sets large cursor display, used to indicate insert mode
thinCursor()sets normal cursor display, used when insert mode is off
w_putw()moves character & attribute to video memory; handles snow
w_memcpy()moves blocks of data to video memory; handles snow
w_printf()printf in the context of a window
beep()less obnoxious sound than with putchar('\a');

In addition to these globally available functions, the programmer has access to
the following external variables:
vidMemsegment address for video display; set by w_init
main_wpointer to the Window structure for the whole screen
top_wpointer to the Window structure for the active (top) window
layers_wnumber of windows in the linked list
colsnumber of columns (80/40) on physical screen; set by w_init()
insertFlagkeeps track of whether insert mode is on
beepFlagtells whether to beep when field size is exceeded
snowFlagset by w_init, depending on current video mode; can be turned
off by application program if set by w_init if snow is not a
problem

Most of the C source files group more than one function in a single file:
w_init.c:w_init, w_create, w_draw, w_error, w_clear, w_show, w_border,
w_title (also definitions of global variables)
w_open.c:w_open, w_link, w_select
w_putc.c:w_putc, w_puts, w__scroll, w_scroll
w_center.c:w_center
w_close.c:w_close, w_unlink, w_refresh, w_dispose
w_cursor.c:w_putcrs, crs_off, crs_on
w_fields.c:showField, getField, clearToEnd, fieldStart, fieldEnd,
fieldLeft, fieldRight, toggleInsert, delChar, addChar,
backspace, fatCursor, thinCursor
w_printf.c:w_printf

Note that w_printf has to be compiled separately for Microsoft & Borland
compilers: this is the only function in the package which doesn't work
exactly the same way for the two compilers -- the underlying globals used
by the ANSI functions called by w_printf (va_start() & vsprintf()) are
not the same. The library supplied has this function set up to work with
Borland's Turbo C.

The skeletal structure of a program using the package consists of the
following steps:

1. call w_init();
2. create window with w_create();
3. open the window with w_open();
4. write to the window with w_puts(), w_putc(), or w_center();
5. repeat steps 2-4 as needed; for a window which is already
open, simply call w_select to bring it to the top if it
is obscured by other windows;
6. when a window should disappear, call w_close();
7. if there is any possibility of running out of space,
call w_dispose() to free up space for any windows
no longer needed.


For data entry, set up Field structures with appropriate values, call showField()
to display the prompts and fields, then call getField() to read the strings
from each field. The field's structure has space for indicating whether the
field accepts letters, digits, or special characters as listed in a string
pointed to by the "specials" member. If you only want some letters or digits
and want to screen out the others, turn off the alpha or num flags and put
the ones you want in the specials string. Since getFields() returns the value
of the key the user pressed to leave the field, the caller can use this return
value to determine which action to take next (move to succeeding/previous
field, store the whole record, etc.). It can be instructive to look at the
source code for the two examples provided: winddemo.c and customio.c.