The IBM-PC WINDOWING library
A PC Character Based Windowing Library
for Stand-Alone 8086 applicatons
using MICRO-C.
Copyright 1989-2000 Dave Dunfield
All rights reserved.
DK86 WINDOWING LIBRARY Page: 1
1. IBM-PC WINDOWING Library
The MICRO-C WINDOWING LIBRARY is a set of powerful, very fast,
compact, text based windowing functions for use with the MICRO-C
compiler, on the IBM Personal Computer. Features of the library
include multiple open windows, overlaid windows with automatic
save/restore of screen underneath, scrolling within windows, optional
window borders, menu and form entry functions, and more.
The library is organized into two parts, the first is a set of
assembly language routines which provides the basic "low level"
functions to open/close windows, and to output data in them. The
second part of the library provides a set of 'C' functions which
provide "high level" functions such as menu and form entry, formatted
printing, etc.
To add these functions to the 8086 Developers Kit library (TINY
and SMALL) models, CD to the LIB86 directory, and use the following
commands:
cc86 winrtns -afop
slib i=tiny a=winrtns a=wprintf a=window
slib i=small a=winrtns a=wprintf a=window
I have compiled the window demonstration program from the standard
DOS compiler using the 8086 Developers Kit with these functions added
to its library. Run WINDEMO.COM to see the windowing functions in
action.
DK86 WINDOWING LIBRARY Page: 2
1.1 Window Control Block
Whenever a new window is opened, the windowing library sets up
a WINDOW CONTROL BLOCK (WCB) which contains information needed to
access and control the window. The format of the WCB is:
Offset: 0 - Current video attribute *
1 - Window flags (High 8 bits of w_open attrs) **
2 - Absolute 'X' position of top left corner of
active region. ***
3 - Absolute 'Y' position of top left corner of
active region. ***
4 - Width in characters of active region ***
5 - Height in characters of active region ***
6 - Current 'X' cursor coordinate
7 - Current 'Y' cursor coordinate
8,9 - Pointer to previous window buffer
10 - Previous cursor ENDING line
11 - Previous cursor STARTING line
12 - Previous cursor absolute 'X' position ****
13 - Previous cursor absolute 'Y' position ****
14..- Save area for SAVE/RESTORE function
* You may dynamically alter the video attribute of data
written to the window by writing to this byte.
** You may dynamically alter the properties of the window by
setting or clearing the flag bits with these exceptions:
-DO NOT enable SAVE/RESTORE unless opened with it
(It is Ok to disable SAVE/RESTORE).
-DO NOT change the state of the BORDER bits.
*** For windows opened with a BORDER, this reflects the size
of the active region (not including the border). Otherwise,
this is the size of the entire window.
**** For full screen window which does not SAVE/RESTORE, you can
set these values to zero to home cursor on exit.
DK86 WINDOWING LIBRARY Page: 3
1.2 External Variables
In addition to the functions decribed on the following pages,
the windowing library provides the following external variables
which may be accessed from within your 'C' program:
1.2.1 W_BASE
extern int W_BASE;
This variable contains the base address of the video screen,
which may be used to determine the type of display present:
B000 = Monochrome
B800 = Color
1.2.2 W_OPEN
extern char *W_OPEN;
This variable contains a pointer to the WCB for the "active"
window, and controls which window is manipulated by certain
library functions. This automatically set up by "wopen" to
point to the last window opened, but may be changed at any time
with:
W_OPEN = window;
NOTE, when the active window is closed, W_OPEN is reset to
point to the window which was active at the time that it (the
active window) was opened. If windows are closed in other than
the reverse order of which they were opened, W_OPEN may be left
pointing to a window which has already been closed. If this
happens, YOU MUST NOT USE THE "ACTIVE" WINDOW FUNCTIONS WITHOUT
RESETTING W_OPEN TO POINT TO AN OPEN WINDOW. It is your (the
programmer's) responsibility to insure that you know what
window will be accessed through W_OPEN at all times throughout
your program.
1.3 Window Library Functions
The following pages contain a description of each function
available in the IBM-PC windowing library.
WCLEOL WCLEOL
W_CLEOL W_CLEOL
PROTOTYPE:
wcleol()
w_cleol(char *window)
ARGUMENTS:
window - Pointer to WCB for an open window
RETURN VALUE:
None
DESCRIPTION:
The "wcleol" function clears the active window from the current
cursor position to the end of a line.
The "w_cleol" function clears the specified window fromt the
current position to the end of the line.
EXAMPLES:
wputs("Input> "); /* Display a prompt */
wcleol(); /* Clear remainder of input line */
WCLEOW WCLEOW
W_CLEOW W_CLEOW
PROTOTYPE:
wcleow()
w_cleow(char *window)
ARGUMENTS:
window - Pointer to WCB for an open window
RETURN VALUE:
None
DESCRIPTION:
The "wcleow" function clears the active window from the current
position to the end of the window.
The "w_cleow" function clears the specified window from the
current position to the end of the window.
EXAMPLES:
wgotoxy(0, 10); /* position at line 11 */
wcleos(); /* Clear lower part of screen */
WCLOSE WCLOSE
W_CLOSE W_CLOSE
PROTOTYPE:
wclose()
w_close(char *window)
ARGUMENTS:
window - Pointer to WCB for an open window
RETURN VALUE:
None
DESCRIPTION:
The "wclose" function closes the "active" window, and de-activates
it.
The "w_close" function closes the specified window, and
de-activates it.
If the window being closed is the "active" window, the "active"
window will revert to the window which was "active" at the time that
the window being closed was opened.
EXAMPLES:
wclose(); /* Close active window */
w_close(title); /* Close the title window */
WCLWIN WCLWIN
W_CLWIN W_CLWIN
PROTOTYPE:
wclwin()
w_clwin(char *window)
ARGUMENTS:
window - Pointer to WCB for an open window
RETURN VALUE:
None
DESCRIPTION:
The "wclwin" function clears the entire active window and resets
the cursor position to the top left hand corner.
The "w_clwin" function clears the entire specified window, and
resets the cursor position to the top left hand corner.
EXAMPLES:
if(c = 0x1b) { /* Escape command */
wclwin(); /* Clear the screen */
wputs("Exiting back to main menu");
return; }
WCURSOR_BLOCK WCURSOR_BLOCK
PROTOTYPE:
wcursor_block()
ARGUMENTS:
None
RETURN VALUE:
None
DESCRIPTION:
This function enables (turns on) display of the cursor on the IBM
PC video display. The cursor is shown as flashing block, occupying
the entire character window.
EXAMPLES:
if(insert) /* Test insert mode flag */
wcursor_block(); /* Indicate inserting with block cursor */
else
wcursor_line(); /* Indicate overwrite with line cursor */
WCURSOR_LINE WCURSOR_LINE
PROTOTYPE:
wcursor_line()
ARGUMENTS:
None
RETURN VALUE:
None
DESCRIPTION:
This function enables (turns on) display of the cursor on the IBM
PC video display. The cursor is shown as a single flashing line, at
the bottom of the character window.
EXAMPLES:
wcursor_line(); /* Re-enable the cursor */
exit(0); /* And terminate */
WCURSOR_OFF WCURSOR_OFF
PROTOTYPE:
wcursor_off()
ARGUMENTS:
None
RETURN VALUE:
None
DESCRIPTION:
This function inhibits (turns off) display of the cursor on the
IBM PC video display. This affects the cursor display only, screen
output will continue to be displayed at the correct cursor position.
EXAMPLES:
wclscr(); /* Clear screen */
wcursor_off(); /* Inhibit cursor */
wmenu(10, 10, 0x6007, main_menu, &index); /* Present main menu */
WFORM WFORM
PROTOTYPE:
register wform(int x, int y, int attrs, char *prompts[],
char *strings, ...)
ARGUMENTS:
x - Absolute COLUMN of upper left corner of form window
y - Absolute ROW of upper left corner of form window
attrs - Attributes for form window (See WOPEN)
prompts - Prompt string for form entries
strings - Destination string to receive form data
... - Additional arguments may be required
RETURN VALUE:
None
DESCRIPTION:
The "wform" function opens a window, which contains a "form"
consisting of prompts and data areas. Each data area is shown beside
its corresponding prompt, and may be edited using the keys supported
by WGETS. the UP and DOWN ARROW keys may be used to move the editing
cursor between the various fields in the input form.*
The "attrs" argument contains the open attributes (see WOPEN) for
the menu window, and may be used to control the color, border,
clearing, etc.
The "prompts" argument is an array of pointers to strings, which
define the prompts and input fields in the form. The first two
characters of each string define the 'X' and 'Y' coordinates within
the window of the prompt string. The third character contains the
length of the destination string, and the remainder of the string
contains the text prompt. The destination string is positioned in the
window directly following the prompt string. This list of prompts
must end with a NULL (0) element.
The first (0) element of "prompts" does not actually point to an
input definition, but contains the X and Y sizes for the window to be
opened (High byte = X, Low byte = Y).
Following the "prompts" argument, there must be one destination
"string" argument for each prompt defined. The strings must be long
enough to contain the number of characters specified in the third
byte of the coresponding "prompt" string.
Only the lower seven bits of the field length are used (length =
1-127), the high bit indicates that the field is to contain numbers
only. In this case, the corresponding argument is NOT a pointer to a
string, but must be a pointer to an "int" variable.
The form is exited by pressing the ESCAPE key.
EXAMPLES:
/* Sample input form */
char *form[] = {
50<<8|6, /* Place in 50 by 6 window */
"\x01\x00\x20Software :",
"\x01\x01\x20Author :",
"\x01\x02\x20Directory :",
"\x01\x03\x20Filename :",
0 };
/* Data areas for input form */
char software[0x21] = "MICRO-C",
author[0x21] = "Dave Dunfield",
direct[0x21] = "C:\\MC",
filename[0x21] = "MC*.*";
/* Simple main program to display the form */
main()
{
wform(15, 9, 0xE007, form, software, author, direct, filename);
}
WGETC WGETC
W_GETC W_GETC
PROTOTYPE:
int wgetc()
int w_getc(char *window)
ARGUMENTS:
window - Pointer to WCB for an open window
RETURN VALUE:
0-127 - ASCII value of key pressed
< 0 - Special function key as defined in "window.h"
DESCRIPTION:
The "wgetc" function waits until a key is pressed on the system
console, and returns its value. The cursor is updated to be placed at
the current cursor position in the active window.
The "w_getc" function waits until a key is pressed on the system
console, and returns its value. The cursor is updated to be placed at
the current cursor position in the specified window.
Note that due to the buffering of the IBM-PC keyboard, every
keypress will be reported, even if the WGETC or W_GETC function is
called after a key is pressed and released.
EXAMPLES:
switch(wgetc()) { /* Handle input keys
. . .
}
WGETS WGETS
PROTOTYPE:
int wgets(int x, int y, char *string, int length)
ARGUMENTS:
x - COLUMN position for input
y - ROW position for input
string - Destination string
length - Length of string (High bit set = Numbers only)
RETURN VALUE:
Character causing exit
DESCRIPTION:
The "wgets" function positions the cursor at the specified X and Y
coordinates, and displays the contents of "string" (in a field of
"length" characters), and waits for input, which may be used to edit
the string.
Any normal ASCII characters which are input will be entered into
the string, The following function keys are recognized:
LEFT ARROW - Position cursor one space to the left
RIGHT ARROW - Position cursor one space to the right
BACKSPACE - Backup cursor & delete previous character
DELETE - Delete character under cursor
INSERT - Toggle between INSERT/OVERWRITE
HOME - Position cursor at start of string
END - Position cursor at end of scring
PAGE UP - Clear entire field
PAGE DOWN - Clear from cursor to end of field
Any other special function keys will cause "wgets" to terminate,
and return the value of the offending key. (See "window.h" for key
definitions).
When INSERT mode is enabled, all entered text will be inserted
into the string, with the remainder of the string shifting to the
right. This mode is indicated by a flashing BLOCK cursor.
When OVERWRITE mode is enabled, all entered text will overwrite
the existing string. This mode is indicated by a flashing LINE
cursor.
EXAMPLES:
wgets(2, 5, name, 25);
WGOTOXY WGOTOXY
W_GOTOXY W_GOTOXY
PROTOTYPE:
wgotoxy(int x, int y)
w_gotoxy(int x, int y, char *window)
ARGUMENTS:
x - New COLUMN
y - New ROW
window - Pointer to WCB for an open window
RETURN VALUE:
None
DESCRIPTION:
The "wgotoxy" function positions the cursor within the active
window. Any further display output to that window will occur at the
new ROW and COLUMN positions.
The "w_gotoxy" function positions the cursor within the specified
window. Any further display output to that window will occur at the
new ROW and COLUMN positions.
EXAMPLES:
for(i=0; i<10; ++i) { /* Draw a diagonal line of 'X's */
wgotoxy(i, i);
wputc('X'); }
WMENU WMENU
PROTOTYPE:
wmenu(int x, int y, int attrs, char *names[], int &index)
ARGUMENTS:
x - Absolute COLUMN of top left corner of menu window
y - Absolute ROW of top left corner of menu window
attrs - Attributes for menu window (see WOPEN)
names - Array to menu selection text (last entry = 0)
index - Address of message selection index variable
RETURN VALUE:
0 - Selection was made and ENTER pressed.
!0 - Menu was aborted via ESCAPE key.
DESCRIPTION:
The "wmenu" function opens a window containing a list of menu
items at the specified ROW and COLUMN address. The user may use the
UP, DOWN, HOME and END keys to select an entry by moving the INVERSE
VIDEO selection cursor. Pressing an alpha-numeric key will position
the selection bar to the first entry which begins with that
character.
When the desired selection is under the cursor, the selection is
made by pressing the ENTER key.
At any time the menu selection may be canceled by pressing the
ESCAPE key.
The "attrs" argument contains the open attributes (see WOPEN) for
the menu window, and may be used to control the color, border,
clearing, etc.
The "names" argument must be a pointer to an array of character
strings which are the selections to display. This array MUST end with
a NULL (0) element to indicate the end of the list.
The "index" argument is the address of an "int" variable which
contains the position of the selection cursor. It controls where the
selection cursor will appear when the function is first invoked (0 =
first entry), and also is assigned the position of the selection
cursor when the selection is made.
Once a selection is made, the first character of that selection
will be hilighted in reverse video.
EXAMPLES:
char *names[] = { "One", "Two", "Three", "Four", "Five", 0 };
. . .
index = 0;
if(wmenu(10, 10, 0xE007, names, &index))
return; /* Aborted, exit to higher level */
switch(index) { /* Handle selection */
. . .
}
WOPEN WOPEN
PROTOTYPE:
char *wopen(int x, int y, int width, int height, int attrs)
ARGUMENTS:
x - Absolute COLUMN of top left corner of window
y - Absolute ROW of top left corner of window
width - The width of the window in characters
height - The height of the window in characters
attrs - The window attributes, BIT definitions:
15 - Enable SAVE/RESTORE screen under window
* 14 - Enable SINGLE line BORDER
* 13 - Enable DOUBLE line BORDER
12 - Enable CLEAR on OPEN
** 11 - Enable CLEAR on CLOSE
*** 10 - Disable NEWLINE (LF only)
9 - Enable SCROLLING in window
8 - Enable LINE WRAP in window
7-0 - Video attributes for window
* When BORDER is selected, window will include an enclosing
BOX. In this case, the effective height and width of the
active region (where text data can be written) will be
reduced by 2.
** Has no visual effect when SAVE/RESTORE is enabled.
*** If this BIT is set, CTRL-J will behave as LINEFEED only,
and will not return the cursor to the left margin.
RETURN VALUE:
A pointer to the WCB for the newly opened window
0 if the window could not be opened
DESCRIPTION:
The "wopen" function creates a new window on the PC video screen.
This newly created window is also made the "active" window, which is
automatically accessed by many of the windowing functions.
If "wopen" is unable to allocate enough memory for the window
control block (WCB), it will fail and return a value of zero (0).
EXAMPLES:
/* Create a title window at top of screen */
titlewin = wopen(0, 0, 80, 3, 0x6047);
WPRINTF WPRINTF
W_PRINTF W_PRINTF
PROTOTYPE:
register wprintf(char *format, arg, ...)
register w_printf(char *window, char *format, arg, ...)
ARGUMENTS:
window - Pointer to WCB for an open window
format - Pointer to format string
arg - Argument as determined by format string
... - Additional arguments may be required
RETURN VALUE:
None
DESCRIPTION:
The "wprintf" function performs exactly as the "PRINTF" function
in the standard function library, except that it outputs directly to
the active window using the low level windowing library functions.
The "w_printf" function behaves similar to "wprintf", except that
the window to receive the output is specified as the first parameter.
These functions should be used in preference to "PRINTF" when
using the windowing function library since "PRINTF" will not move the
windowing librarys cursor, will not use the attributes from the WCB,
and will not respect the boundarys of the window.
NOTE: This function uses a variable number of arguments, and must
be declared as "register" (See "window.h").
EXAMPLES:
wgotoxy(0, 0);
wprintf("Window %u", screen);
WPUTC WPUTC
W_PUTC W_PUTC
PROTOTYPE:
wputc(int c)
wputc(int c, char *window)
ARGUMENTS:
c - Character to be written to window
RETURN VALUE:
None
DESCRIPTION:
This "wputc" function displays a character in the active window at
the current cursor position.
The "w_putc" functino displays a character in the specified window
at the current cursor position.
Characters are output in "tty" fashion, with proper handling of
control codes such as CARRIAGE-RETURN, LINE-FEED and BELL. The screen
will scroll upwards when a NEWLINE is printed on the bottom line of
the screen, or when the bottom line wraps around to the next
(Assuming those options are enabled in the window).
Although only the lower 8 bits of a passed value are used, "vputc"
will not perform ANY output translations if any of the upper 8 bits
are set. This provides a method of displaying the video characters
represented by control codes such as NEWLINE, and BACKSPACE.
The first byte of the window control block (WCB) for the window
contains the attributes which will be used to display the character.
This value is written to the attribute location associated with the
character on the video display hardware. Its effect is dependant on
the video adapter in use. The "window.h" header file contains
definitions of the attribute bits for use on "standard" monochrome
and color displays.
EXAMPLES:
w_putc(0x0A, window1); /* Line-feed, advance cursor */
wputc(0x0A | 0xff00); /* Display 0x0A character code */
WPUTF WPUTF
PROTOTYPE:
wputf(char *string, int width)
ARGUMENTS:
string - Pointer to character string
width - Width of output field
RETURN VALUE:
None
DESCRIPTION:
The "wputf" function outputs a character string to the active
window screen using the video library functions.
The string is left justified in a field of the specified width. If
the string is shorter than "width", the field is padded with blanks.
If the string is longer than "width", the output is truncated.
EXAMPLES:
wputf(message, 10);
WPUTS WPUTS
W_PUTS W_PUTS
PROTOTYPE:
wputs(char *string)
w_puts(char *string, char *window)
ARGUMENTS:
string - Pointer to character string
window - Pointer to WCB for an open window
RETURN VALUE:
None
DESCRIPTION:
The "wputs" function outputs a character string to the active
window.
The "w_puts" function output a character string to the specified
window.
EXAMPLES:
wputs(message);
w_puts(message, window1);
WTSTC WTSTC
W_TSTC W_TSTC
PROTOTYPE:
int wtstc()
int w_tstc(char *window)
ARGUMENTS:
window - Pointer to WCB for an open window
RETURN VALUE:
0 - No key pressed
1-127 - ASCII value of key pressed
< 0 - Special function key as defined in "window.h"
DESCRIPTION:
The "wtstc" function tests for a key pressed on the system
console, and returns its value. If a character is found, the cursor
is updated in the active window.
The "w_tstc" function tests for a key pressed on the system
console, and returns its value. If a character is found, the cursor
is updated in the specified window.
A returned value of zero (0) indicates that no key was found to be
pressed.
Note that due to the buffering of the IBM-PC keyboard, every
keypress will be reported, even if the WTSTC or W_TSTC function is
called after a key is pressed and released.
EXAMPLES:
if(wtstc() == 0x1B) /* exit loop on ESCAPE key */
break;
WUPDATEXY WUPDATEXY
W_UPDATEXY W_UPDATEXY
PROTOTYPE:
wupdatexy()
w_updatexy(char *window)
ARGUMENTS:
window - Pointer to WCB for an open window
RETURN VALUE:
None
DESCRIPTION:
The "wupdatexy" function updates the real X/Y cursor position on
the video screen to reflect the "logical" position where the next
character will be output in the active window.
The "w_updatexy" function updates the real X/Y cursor position on
the video screen to reflect the "logical" position where the next
character will be output in the specified window.
The MICRO-C Windowing library uses a BIOS interrupt (INT 10) to
position the cursor, which is quite slow, compared to the speed of
the library video routines. To prevent this from slowing down the
video output, the cursor is only physically re-positioned when a
"wgotoxy" or a "wgetc" is executed.
This allows the library routines to run at full speed, and still
put the cursor in the right place when output stops and an input
request is made.
A side effect of this is that the cursor on the screen will not
appear to move unless you call "wgotoxy" or "wgetc". This only
affects the physical cursor on the screen, MICRO-C maintains its own
internal cursor location which it uses to determine where on the
screen the next write will occur.
Some applications which run in real time (Such as a terminal
emulator) do not call "wgetc", but use "wtstc" to poll the keyboard
on a regular basis. In this case, the "wupdatexy" routine should be
called any time that the visual position of the cursor is important.
EXAMPLES:
wupdatexy(); /* position the cursor *
c = wtstc(); /* Test for a character */
DK86 WINDOWING LIBRARY
TABLE OF CONTENTS
Page
1. IBM-PC WINDOWING Library 1
1.1 Window Control Block 2
1.2 External Variables 3
1.3 Window Library Functions 3
Code: