Contents of the CURSES.DOC file
The PC Curses Library
(C) Copyright 1987 Jeffrey S. Dean. All Rights Reserved.
PC CURSES LICENSE AGREEMENT
The PC Curses Library Package is a copyrighted software
package that is being distributed as shareware. It is NOT in
the public domain. By using or distributing this package, you
agree to the conditions presented below:
(1) You may use the PC Curses Library for your own personal
use; if you find it useful, you are requested to pay a $20
registration fee. If you are using PC Curses in a
commercial, professional, or governmental organization, you
are granted a limited license, valid for thirty days, to use
this package for evaluation purposes only; if you continue to
use this package, you must pay the registration fee. The
registration fee entitles you to use the PC Curses library on
one machine. It also includes one free upgrade.
(2) Source code is available to registered users only.
Source code is also copyrighted, and may NOT be freely copied
or distributed. The price of the source distribution is $20;
in addition to the source modules, it include makefiles (as
well as a version of the "make" program and other utilities).
(3) The PC Curses Library (except source) may be freely
distributed and copied; however, you may not charge anything
for the distribution. The distribution must include
everything in the original distribution, including this
agreement. You may not distribute this system with any
modifications (this includes documentation as well as
programs); additions must be placed in separate files and
must be clearly marked as such.
(4) If any part of the PC Curses Library is used in a
program, system, or service that is distributed to machines
other than the one originally licensed, there is a nominal
fee (in addition to the registration fee) and a simple
licensing agreement that must be completed. This fee may be
waived if the program or system is distributed as shareware
or by a non-profit organization (but the licensing agreement
must still be completed). There are no royalties.
PC Curses - 2 -
(5) DISCLAIMER OF WARRANTY: THE PC CURSES PACKAGE IS SOLD "AS
IS" AND WITHOUT ANY WARRANTIES, EXPRESS OR IMPLIED, AS TO
PERFORMANCE OR MERCHANTABILITY. BECAUSE OF THE DIVERSITY OF
CONDITIONS UNDER WHICH THIS PACKAGE MAY BE USED, NO WARRANTY
OF FITNESS FOR A PARTICULAR PURPOSE IS OFFERED. THE USER IS
ADVISED TO TEST THE PACKAGE THOROUGHLY BEFORE RELYING ON IT.
THE USER MUST ASSUME FULL RISK AS TO THE RESULTS AND
PERFORMANCE OF USING THE PACKAGE. ANY LIABILITY OF THE
AUTHOR OR DISTRIBUTOR WILL BE LIMITED EXCLUSIVELY TO PRODUCT
REPLACEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
DAMAGES ARISING FROM THE USE OR INABILITY TO USE THIS
Ordering PC Curses
PC Curses complete evaluation system . . . $5
PC Curses registration . . . . . . . . . . $20
The following items are available only to registered users:
PC Curses source code . . . . . . . . . . . $20
PC Curses redistribution license . . . . . $10
All payments must be in U.S. dollars. For orders outside the
U.S., please add an extra $10 per order.
Send orders and other correspondence to:
Palo Alto, CA 94306
PC Curses - 3 -
Table of Contents
Standard Curses Functions
Terminfo Curses Functions
Special PC Curses Functions
Special PC-Specific Functions
Tracing in PC Curses
PC Curses - 4 -
PC Curses is a C Library designed to provide compatibility
with the Unix curses package. It was written for Microsoft C
applications running on IBM PC compatible computers.
The Unix curses package was originally developed at the
University of California at Berkeley as a screen management
and windowing package, providing various tools for creating
and manipulating windows. Its key strength is the ability to
deal with many different types of terminals at any line speed
in a semi-optimized fashion. For many years, it was the only
generally available package that provided windowing
capabilities in the Unix environment.
PC Curses was produced to aid in porting programs from MS-DOS
to Unix, though it is also useful in writing MS-DOS software
that may need to be ported to Unix. The PC environment is
drastically different from Unix, so while this package is
meant to be functionally similar to the Unix one, there are a
few small differences externally (but many differences
This package is much simpler that the Unix version. Because
of the nature of the PC environment, there is no need for
anything like cursor motion optimization. Because of the
high screen bandwidth, little effort is spent trying to
optimize screen output. Because the PC has features not
always available in other environments, additional routines
(not in the original curses package) are provided.
The PC Curses code was developed independently, without
reference to the Unix source code. This documentation is
based on experience with the curses package, on Ken Arnold's
paper "Screen Updating and Cursor Movement Optimization: A
Library Package," and on the Unix System V curses
Arnold's paper (or the newer System V documentation) should
be considered required reading in order to understand how
this system works. The documentation included here
summarizes some of the relevant information, and points out
differences between the Unix version and the PC version.
Note that there are two major versions of curses. The
original, produced some time ago at UC Berkeley, used the
termcap database. More recently, the termcap (or termlib)
database has been recast into the terminfo database, for
efficiency and extensions. A new version of curses was
written to take advantage of this system. PC Curses derives
primarily from the earlier version, with some features of the
later version added. In this documentation, the newer
version is referred to as "terminfo curses"; elsewhere, you
PC Curses - 5 -
may hear it referred to as "System V curses."
Please let us know what you think of this package; any
feedback, positive or negative, is appreciated. If you have
any suggestions, problems, or code you would like to see
included in the distribution, please contact us. We are
planning to continue to improve and expand this package,
adding subroutines, utilities, and anything else that would
prove generally useful to curses programmers.
PC Curses - 6 -
The basic "unit" of manipulation in curses is a window.
Windows are dynamically allocated structures, and are passed
around by pointer. Windows represent a rectangular region on
the terminal screen.
The windows are, in a sense, buffered. There are a variety
of operations for writing windows, but no changes visibly
take place until a wrefresh() command is issued. At this
point, all the changes are written to the physical screen.
There are two special windows in the system, created on
startup. One is the current screen (curscr), and represents
the information that is presently on the screen. The other
is the standard screen (stdscr), which is to windows what
stdout is to buffered output. It is a window that represents
the whole screen, and when a refresh is done, the contents of
this window will be written to the physical screen. For
simple applications, stdscr may be the only window that a
For more information, refer to one of the standard Unix
curses documents and/or the curses.h include file for the PC
PC Curses - 7 -
STANDARD CURSES FUNCTIONS
This section describes functions that are part of the
original termcap curses package. The functions preceded by
'mv' are macros (except for mv*printw) that move to the
specified location first, and if that move is legal (see
move()), then the function is performed. The following
definitions are assumed:
Adds the character to the screen at the current position,
replacing whatever was there. The current position is moved
to the position after the character. Returns ERR if the
character cannot be added to screen (which should happen only
if scrolling is not allowed).
Several characters are handled specially: a tab is expanded,
assuming tabstops every 8 characters from the window's left
edge; a newline causes the rest of the line to be cleared,
and the current position to be moved down one line (and over
to the left edge if newline translation (see nl and nonl) is
on); a return causes the current position to be moved back to
the left edge; a backspace causes the current position to be
moved left one character (unless at the left edge).
Adding a character to a window will cause the cursor to move
down to the next line under one of two conditions: if the
character is the newline character, or if there is not enough
room on the line for the character (wrap). If scrolling is
enabled (see scrollok) and if adding the character would
cause the cursor to move past the last line of the window (or
past the the last line of the scrolling region -- see
setscrreg), then the window will scroll. The scrolling is
done logically (on the window) as well as physically (on the
screen). This means that wrefresh will be called, resulting
in a full screen update.
PC Curses only: No conversions are done on the characters
other than those mentioned above. Thus, control characters
and characters out the Ascii range will be displayed as the
appropriate graphics character.
Note: Adding the characters "\r\n" (return, newline) to the
end of a line will clear the entire line, since the return
moves to the beginning of the line and newline clears to the
end of the line.
PC Curses - 8 -
Adds the string to the window at the current position,
CHTYPE vert, hor;
Draws a box around the window, using 'vert' as the vertical
line character and 'hor' as the horizontal line character.
Note that the box is drawn INSIDE the window, which means
that it can be overwritten, just like anything else inside
the window. Also note that the current attribute for the
window has no effect on the box characters; if you want a box
with attributes, they must be OR'ed with the box characters.
PC Curses only: curses.h defines four constants convenient for
drawing boxes: S_HOR, S_VERT, D_HOR, D_VERT, representing the
single and double line horizontal and vertical line-drawing
characters. The box routine will automatically figure out
the right corner pieces for any combination of these
characters; it also tries to "guess" the right attribute.
Equivalent to werase(win) followed by clearok(win).
PC Curses only: All routines that clear any part of the
screen use the current attribute setting.
Sets the "clear window" flag, but only on windows that cover
the full screen. When a (full screen) window is refreshed,
if the flag is TRUE, the screen is cleared first, and then
the window is redrawn. This can be useful if the screen is
trashed by another program.
If the flag is set to TRUE on curscr, then the next call to
refresh (for any window) will cause the screen to be cleared
before redrawing the specified window.
Clears the window from the current position to the end.
Note: This implementation leaves the current position
unchanged; some implementations do not. If compatibility is
a concern, do not make any assumptions about the cursor
PC Curses - 9 -
position after the completion of this operation.
Macros for setting/clearing tty cbreak mode.
Note: crmode() and nocrmode() are from termcap curses.
cbreak() and nocbreak() are from terminfo curses. There is
no difference between these pairs, aside from name.
PC Curses only: A "read" done in cbreak mode is approximated
with the MS-DOS "filtered" read, which reads one character
and processes some control characters (such as ).
Deleted the character at the current position. Everything to
the right is moved over one position, and the rightmost
column becomes blank.
Deletes the current entire current line. Everything below is
scrolled up, and the last line of the window becomes blank.
The current coordinates remain unchanged.
Deletes the specified window, freeing up associated space in
memory. Has no effect on the screen (i.e., it does not clear
the window from the screen).
Macros for settting/clearing tty echo mode.
PC Curses only: A "read" in echo mode is approximated by
using unechoed MS-DOS reads, and then echoing the character
if echo mode is set. Echoing is done using waddch(); if
waddch() returns ERR, then the read will also return ERR.
The curses termination routine. This routine should be
called before exiting the program.
PC Curses - 10 -
Changes the contents of the specified window to all blanks.
The current position is reset to the origin.
Input character from terminal. The result depends on the
"tty mode" (see raw(), crmod(), and echo() functions) and
keypad translation (see the keypad() function). Normally,
returns the character input. If echo is set, writes the
character in the specified window; if the character cannot be
written (see waddch()), then ERR is returned.
PC Curses only: This routine attempts to emulate the Unix-
style input by using different MS-DOS input routines,
depending on the tty mode. The default modes here may be non-
standard, so be sure to set the tty modes exactly as you
would like them.
Note: The Microsoft C library also has a getch() function.
These two functions are similar but not identical. In
particular, like all other curses routines, getch() will not
work before initscr() is called. When using the curses
library, you will get the curses version, not the Microsoft
Gets a line from the terminal and places it in the argument,
which is assumed to be large enough. Works by repeatedly
calling wgetch until an ERR or a newline is received; in the
former case, ERR is returned; in the latter case, the newline
is stripped off. The erase character and the line kill
character are handled, allowing basic line editing (see
erasechar() and killchar()).
PC Curses only: This function is a no-op.
Sets (y, x) to the current coordinates. This is a macro, so
it is not necessary for the arguments to be pointers.
PC Curses - 11 -
Returns the character at the current position.
Note: These functions are implemented according to the new
(terminfo) version of curses; this means that they are
somewhat incompatible with the old (termcap) version. They
return a character which is OR'ed with its attributes (the
old versions return a character without its attributes). The
constants A_ATTRIBUTES and A_CHARSET can be AND'ed with the
character to extract the component parts.
PC Curses only: For the convenience of termcap curses users,
the macro wcinch() is defined to work like the old winch().
The variant forms (cinch, mvcinch, and mvwcinch) are also
The curses initialization routine. This routine must be
called before any other routine in the curses package.
PC Curses only: returns OK if successful, ERR otherwise. An
error almost always means that there was not enough space
(i.e., malloc failed).
IMPORTANT: The error return condition should always be
checked. Performing window operations after initscr fails is
certain to cause problems.
Inserts the character at the current position. Remaining
characters on the line are moved right one position. The
character at the rightmost edge of the window will be lost.
Inserts a blank line above the current line. Everything
below is scrolled down, and the last line of the window is
lost. The current coordinates remain unchanged.
Sets the "leave cursor alone" flag. The flag is meant to
indicate whether the cursor is being used in a window. When
FALSE (the default setting), the cursor will be moved to the
current position whenever the window is refreshed (i.e., the
cursor is being used). When TRUE, the action of the cursor
is, in general, unpredictable; in the PC Curses
implementation, the result is that the cursor is turned off
PC Curses - 12 -
while inside the window.
PC Curses only: A dummy function, macro-defined to "ibm-pc".
mvcur(lasty, lastx, newy, newx)
int lasty, lastx, newy, newx;
Moves the cursor from (lasty, lastx) to (newy, newx),
PC Curses only: The reason for requiring the present
coordinates as well as the intended ones is to allow for
cursor motion optimization. Since there is no need for this
type of optimization in the PC environment, the first two
coordinates are ignored.
Changes the location of the window so that the upper left
hand corner is at the specified position. If the window
cannot be moved to that position, then the original position
is left unchanged, and ERR is returned.
Note: This routine does not remove the window from its
current position on the screen, nor does it redisplay the
window in the new position. All it does is change the
coordinates that are stored in the window structure.
int lines, cols, begin_y, begin_x;
Creates a new window, with the specified number of lines and
columns, starting at the specified position. If any of the
parameters are zero, they are set to a default value: lines
to the maximum number of lines, cols to the maximum number of
cols, begin_y and begin_x to zero. Thus, newwin(0, 0, 0, 0)
will create a full-screen window.
PC Curses only: returns NULL if window cannot be allocated
(out of space) or if the window will not fit on the screen.
IMPORTANT: The error return condition should be checked.
Performing window operations on a nonexistent window is
certain to cause problems.
Enable/disable newline translation. On input, a carriage
return is normally translated to a newline; on output, a
newline is normally translated to a carriage return/linefeed
sequence. nonl() disables this translation.
PC Curses - 13 -
PC Curses only: The setting of this translation flag has no
effect on refresh optimization. However, for greatest
compatibility with Unix curses, nonl() is recommended.
WINDOW *from_win, *to_win;
Overlay and overwrite copy the contents of one window to
another. The copy is started at (0,0) in both windows, and
is independent of physical screen location. The only
difference between overlay and overwrite is that the former
does not copy blanks while the latter does.
If the windows are of different sizes, the copying is limited
to the size of the smaller window.
Perform printf-style output on a window. Uses waddstr to
write to the window and returns the result.
PC Curses only: The formatted string is temporarily stored in
a local buffer, which is currently set to BUFSIZ (512) bytes.
It is the caller's responsibility to make sure that no
Macros for enabling/disabling tty raw mode.
PC Curses only: A "read" done in raw mode is approximated
with the MS-DOS "unfiltered" read, which means that control
characters (such as ) are not processed. See
Screen updating in curses is done asychronously. Changes made
to a window have no effect on the physical screen until a
refresh function is called. The refresh is optimized: only
changed parts of a window are examined and compared to what
is currently on the screen; the screen is written only when
there is a discrepancy.
PC Curses - 14 -
Macros for restoring and saving current tty modes.
PC Curses only: These functions are no-ops.
Sets the scroll flag for the specified window. When adding a
character to a window would cause that character to go off
the bottom edge of the window, the window will be scrolled if
the scroll flag is set to TRUE. If the flag is set to FALSE
(the default condition), the cursor remains on the last line.
PC Curses only: This function is a no-op.
Turns off all attributes for the specified window. See the
"attr" functions for more general versions of these routines.
Sets standout mode, causing all subsequent characters added
to the window to be highlighted (defined in curses.h to be
inverse video mode). Attributes "stay" with a character,
through scrolling, insertion, deletion, etc. See the "attr"
functions for more general versions of these routines.
int lines, cols, begin_y, begin_x;
Creates a new window; the last four arguments are identical
to those of newwin(). However, this new sub-window shares
the internal character map with the window specified as the
first argument. Any changes made to the sub-window will
affect the parent, and any changes to the parent in the
shared region will affect the sub-window (it may be necessary
to use touchwin() for the changes in one window to be seen in
Note that begin_y and begin_x are relative to the whole
screen, not to the specified window. Also note that the
parent window should not be deleted (with delwin()) if the
sub-window is still to be used.
PC Curses only: Like newwin(), failure to create a new window
will result in a NULL return value. NULL is also returned if
the last four arguments do not actually form a sub-window of
the specified window.
PC Curses - 15 -
Normal screen updating is optimized so that only changed
regions are examined when updating. touchwin() modifies a
window so that on the next refresh, the entire window is
examined. This is useful when a window may have been
overwritten (e.g., by another window).
When working with overlapped windows, if a window does not
appear correctly on the screen, touching and refreshing it
may solve the problem.
PC Curses only: This function is a no-op.
Returns a string representation of a control character. The
string consists of a caret ("^") followed by the upper case
representation of the control character.
PC Curses only:  If the argument to unctrl is not a
control character, then the result string will consist of the
argument character (unchanged).  The result string is a
static buffer, and will be overwritten by subsequent calls.
 The Delete character (Ascii 127, not the delete key) is
considered to be a control character, and is mapped to "^?".
 There is no include file.
PC Curses - 16 -
TERMINFO CURSES FUNCTIONS
The original version of curses was written for use with the
termcap database. When the termcap database facility was
rewritten to improve performance and extend capability, a new
version of curses was written to accompany it. This terminfo
version of curses provides a number of new functions and
changes (or refines) the semantics of some of the old
functions. The new functions currently supported are
described below; a more complete implementation (with the
exception of the multiple terminal capability) is planned.
The functions that have been changed or refined are still
listed in the previous section.
These functions set the current attribute of the specified
window. Attributes defined in the curses.h file are:
A_REVERSE reverse video
A_UNDERLINE underlined text
A_BLINK blinking mode
A_STANDOUT currently defined as A_REVERSE
A_DIM currently defined as A_NORMAL
These definitions are for a monochrome system. Color is not
part of the standard Unix curses package, but color attribute
definitions for PC Curses can be found in the curses.h
When a character is written to a window, it is written
with the current set of attributes. wattron and wattroff can
be used to turn on and off attributes; attrset can be used to
set the attributes to any desired state.
standout() is the same as attron(A_STANDOUT). standend() is
the same as attrset(A_NORMAL).
PC Curses only:  All the modes correspond to standard PC
attributes, with the exception of zero, which PC Curses maps
to mean "normal" mode.  The current attributes are used
when clearing any portion of a window.  The functions
attrget() and wattrget(win) have been added to provide a way
to get the current window attributes.
PC Curses - 17 -
Maps an internally maintained virtual screen onto the actual
screen. See the description of wnoutrefresh() below.
Returns the current erase character.
PC Curses only: The current version of this is macro-defined
to be backspace. The only PC Curses routine that uses this
macro is getstr(). The value can be changed by redefining
the macro in curses.h and recompiling (or avoiding) getstr().
Flashes the screen.
PC Curses only: This function is a no-op.
Sets/clears the keypad translation flag. If the flag is set,
getch() translates function keys (which may actually be more
than one character) into predefined integer values (see
PC Curses only: When keypad translation is on, special keys
that are in the list below are translated. For handling of
"Alt shifted" keys, see the discussion of meta().
The PC Curses implementation is different, and more reliable,
than Unix curses. When a function key prefix character is
received, Unix curses waits for up to one second for the next
character in the function key sequence; if it does not
receive the key, it returns with the prefix character. As a
result, keypad translation in the Unix environment may appear
"jerky," and timing delays may even cause a function key to
go unrecognized. In the PC environment, the prefix character
is unique, and whenever it is seen, the rest of the function
key sequence is already there. This results in a much
KEY_BREAK 0x101 -- unused in PC Curses
KEY_DOWN 0x102 -- DOWN ARROW
KEY_UP 0x103 -- UP ARROW
KEY_LEFT 0x104 -- LEFT ARROW
KEY_RIGHT 0x105 -- RIGHT ARROW
PC Curses - 18 -
KEY_HOME 0x106 -- HOME KEY
KEY_F0 0x108 -- dummy value
KEY_F(x) (KEY_F0+(x)) -- FUNCTION KEYS
KEY_DL 0x148 -- unused in PC Curses
KEY_IL 0x149 -- unused in PC Curses
KEY_DC 0x14a -- DELETE KEY
KEY_IC 0x14b -- INSERT KEY
KEY_EIC 0x14c -- unused in PC Curses
KEY_CLEAR 0x14d -- unused in PC Curses
KEY_EOS 0x14e -- unused in PC Curses
KEY_EOL 0x14f -- unused in PC Curses
KEY_SF 0x150 -- unused in PC Curses
KEY_SR 0x151 -- unused in PC Curses
KEY_NPAGE 0x152 -- PAGE DOWN KEY
KEY_PPAGE 0x153 -- PAGE UP KEY
KEY_STAB 0x154 -- unused in PC Curses
KEY_CTAB 0x155 -- unused in PC Curses
KEY_CATAB 0x156 -- unused in PC Curses
KEY_ENTER 0x157 -- unused in PC Curses
KEY_SRESET 0x158 -- unused in PC Curses
KEY_RESET 0x159 -- unused in PC Curses
KEY_PRINT 0x15a -- unused in PC Curses
PC Curses only: The following definitions have been added for
the PC environment:
KEY_END KEY_LL -- END KEY
KEY_sF(x) (KEY_F(10)+x) -- SHIFTED FUNCTION KEYS
KEY_cF(x) (KEY_SF(10)+x) -- CONTROL FUNCTION KEYS
KEY_aF(x) (KEY_CF(10)+x) -- ALT FUNCTION KEYS
KEY_cNPAGE 0x180 -- CTRL-PGDN
KEY_cPPAGE 0x181 -- CTRL-PGUP
KEY_cHOME 0x182 -- CTRL-HOME
KEY_cEND 0x183 -- CTRL-END
KEY_cLEFT 0x184 -- CTRL-LEFTARROW
KEY_cRIGHT 0x185 -- CTRL-RIGHTARROW
KEY_cPRTSC 0x186 -- CTRL-PRTSC
KEY_sTAB 0x187 -- SHIFTED (REVERSE) TAB
Any PC function keys which are not defined above will
return the appropriate two character extended code instead.
Returns the current line kill character.
PC Curses only: The current version of this is macro-defined
to be Control-U. The only PC Curses routine that uses this
macro is getstr(). The value can be changed by redefining
the macro in curses.h and recompiling (or avoiding) getstr().
PC Curses - 19 -
Provides eight bit input through the specified window.
PC Curses only: When input is done through a window with meta
mode on, the 'Alt' key is treated like a meta key, and so
extended character codes involving the Alt key get turned
into the appropriate characters with the meta (parity) bit
set. [Note that the Alt key cannot be used in combination
with the control key.] When meta mode is off, the extended
character codes get passed through untranslated.
Note: Unlike Unix curses, PC Curses always provides 8 bit
character input, regardless of meta().
int lines, cols;
A pad is similar to a window, with two differences. First, a
pad may be of any size; it is not bounded by the size of the
screen. Second, any part of the pad may be displayed on any
part of the screen; the origin is not specified when the pad
The structure of a pad is identical to the structure of a
window. The two may be used interchangeably, except when
refreshing. Since there is no fixed relationship between the
pad and the screen, the relationship must be specified when
refreshing. This is done with the special refresh functions
prefresh() and pnoutrefresh(); wrefresh() or wnoutrefresh()
should not be called with a pad as an argument.
All of the other standard curses functions can be applied to
pads. The only difference is that certain functions which
automatically refresh a window (e.g., getch, addch) will not
refresh the pad.
PC Curses only: Returns if NULL pad cannot be allocated.
Sets/clears nodelay mode. When nodelay mode is not set,
getch() will not return until a character has been input.
When nodelay mode is set, getch() will always return
immediately. If there was input present, it will return the
character; otherwise, it will return -1.
pnoutrefresh(pad, pminy, pminx, sminy, sminx, smaxy, smaxx)
prefresh( pad, pminy, pminx, sminy, sminx, smaxy, smaxx)
WINDOW *pad; int pminy, pminx, sminy, sminx, smaxy, smaxx;
Refreshes a pad (corresponds to wnoutrefresh or wrefresh for
a window). A rectangular area of the pad, starting with the
upper left corner specified by (pminy,pminx) is mapped to a
rectangular area on the screen, specified by the upper left
corner (sminy,sminx) and the lower right corner
(smaxy,smaxx). The lower right corner is implicit.
PC Curses - 20 -
See newpad() for a description of pads.
PC Curses only: Returns ERR on failure. Failure occurs if
the argument is not a pad, or if either of the rectangular
areas exceeds the bounds of the associated object.
int top, bot;
Defines a scrolling region inside a window. The top line of
the scrolling region is set to "top" and the bottom line is
set to "bot". These values are relative to the window. If
scrolling for the window is enabled, the window will be
scrolled when adding a character would cause the cursor to
move past the bottom line of the region.
Scrolling occurs when adding a character to the last line of
a region, and when that character is a newline, or that
character would go past the end of the line. This means that
the only routine which scrolls the screen is waddch(), or any
other routine that calls it (waddstr(), wgetch(), etc.).
A window with no scrolling region is equivalent to a window
whose scrolling region is the entire window. Thus, scrolling
regions allow the creation of a window-like region within a
PC Curses only: Returns ERR if the specified scrolling region
is out of range. The scrolling region can be disabled by
setting both top and bottom values to zero.
The pair of functions (wnoutrefresh, doupdate) provide
similar functionality to the single function wrefresh().
Wnoutrefresh() writes the specified argument onto an
internally maintained virtual window, representing what
should be on the screen. Unlike wrefresh(), nothing is
actually written on the screen. Doupdate() does the actual
update, making the screen look like the virtual screen.
These functions are most useful when updating several
(possibly overlapping) windows. With wrefresh(), some
unnecessary drawing might be done in this case. By calling
wnoutrefresh() for each window, then doupdate() at the end,
redundant screen updates would be eliminated.
PC Curses only: Wrefresh() is equivalent to wnoutrefresh()
followed by doupdate(). For efficiency reasons, wrefresh has
not been written exactly this way (although it acts exactly
like it was implemented this way). Unless the power of
wnoutrefresh is needed, wrefresh is a better choice.
PC Curses - 21 -
SPECIAL PC CURSES FUNCTIONS
The following functions are additions to the normal curses
package. They are provided for programming convenience.
These functions are coded on top of curses and are designed
to be source-code compatible with Unix curses.
These routines are experimental, and subject to change.
drawbox(win, vert, hor, begin_y, begin_x, end_y, end_x)
CHTYPE vert, hor; int begin_y, begin_x, end_y, end_x;
Generalized version of box(). Draws a box anywhere in the
specified window. The box is specified by the "begin" and
"end" coordinates. If both coordinates specify the same
point, or if the coordinates are out of range, nothing is
drawn. See box() for a further discussion of how boxes are
box(win, vert, hor) is equivalent to
drawbox(win, vert, hor, 0, 0, 0, 0)
WINDOW *shadow(win, shadow)
Creates a "shadow" of a window. A window's shadow is the
part of the current screen that is replaced when the window
is displayed. The concept of shadows is useful when dealing
with pop-up windows, which need to appear and disappear
without permanently disturbing what is on the screen.
The first argument is the window whose shadow is to be taken.
The second argument is the shadow window, which will hold the
shadow. If the second argument is NULL, a new window is
allocated for the shadow. The routine returns the shadow
window, or NULL on error. Possible errors are inability to
allocate a window, or if the window and its shadow are not
the same size.
A shadow is no different than any other window. All the
standard routines for dealing with windows can be applied,
though generally only a small number of routines are really
To pop-up a window, save its shadow with this function before
displaying the pop-up window on the screen (unless this is
the first time the pop-up is displayed, it will probably be
necessary to invoke touchwin on the pop-up). To remove the
pop-up window, redisplay the shadow with wrefresh(), thereby
restoring the previous contents of the screen.
PC Curses - 22 -
SPECIAL PC-SPECIFIC FUNCTIONS
The following functions are PC specific functions, and have
may have no meaning on other systems.
Sets the screen update method. Legal values for "flag" are
T_BIOS for bios updates, and T_DIRECT for direct video memory
updated. Note that in either case, any screen driver is
bypassed; thus, an ansi screen driver (e.g., ANSI.SYS) is not
required for applications written with this library.
The default method is T_BIOS updating, which is compatible
across a much wider range of machines. It also reduces or
eliminates flicker on certain types of monitors. However, it
is significantly slower than direct video memory updates.
Setting the update method to T_DIRECT forces direct updates.
pc_uptype() attempts to automatically figure out the address
of video memory. The current algorithm for this is
experimental. To provide a backup in case of failure,
pc_uptype() can be called with flag set to the segment
address of video memory. This feature may go away in the
This function is experimental, and is subject to change.
PC Curses - 23 -
TRACING IN PC CURSES
PC Curses has a built-in tracing facility. The libraries
"sdcurses" and "ldcurses" are the debugging/tracing versions
of the curses, corresponding to the standard libraries
"scurses" and "lcurses".
The tracing facility records most function calls and
parameters in a log file. Since high frequency functions,
such as waddch() and wmove() are logged, tracing tends to
slow down things considerably. It also causes the log to
grow very rapidly. To prevent the log file from growing too
large, it is cleared out each time the program is run.
Why is tracing useful? Tracing is a simple way of seeing
what your program is doing. It is easy to use and does not
require the source code to be available. Tracing is most
commonly used to track down program bugs. It is also useful
for analyzing performance, since it provides a picture of
which routines are invoked (and some idea of what they are
To create a traced version of your program, link with one of
the tracing libraries instead of the regular curses
libraries. To start tracing, create a file named "trace.log"
in the directory in which the program runs. When you exit
your program, the output will be in trace.log. Note that the
log file is closed by a call to endwin(); if the call to
endwin() is omitted, the log file may be truncated.
In looking at trace.log, pay special attention to messages
flagged by two exclamation marks "!!". These indicate an
error condition (note that not all error conditions are
For finer control of tracing, the functions traceon() and
traceoff() can be used. The "trace.log" file must still be
set up as described above (if it does not exist, these
functions will have no effect). Since tracing can be quite
slow, judicious use of these functions will result in
considerable speedup as well as a much smaller trace.log
While most versions of curses provide tracing facilities,
they all differ in implementation. This description of
tracing should be considered specific to PC Curses.
Turns tracing on and off. Tracing is initialized by
initscr(). The file "trace.log" must exist in the starting
directory when initscr() is called; if not, these functions
have no effect. These functions also have no effect before
PC Curses - 24 -
initscr() is called.
When tracing is initialized, a warning message is printed out
on the screen, to warn that things may be very slow.
Closes the trace log file. This forces any output that might
be buffered out to the log file. This routine is normally
called by endwin(). Subsequent tracing will cause the file
to be reopened automatically.
Dumps the window to the trace log file. If flag is 0, only
the window parameters are dumped; if flag is non-zero, the
entire character map of the window is also dumped.
Performs printf-style output to the trace log file. This is
the routine that is used internally to log all function
calls. It can be used to log your own information in the
trace log file.
PC Curses - 25 -
The current version of PC Curses contains most of the
functions from the Unix termcap and terminfo versions of
curses. There are three groups of functions that are not
scanf functions - will not be supported unless Microsoft
starts supporting a varargs version of
multiple terminal functions - will not be supported.
terminfo level functions
PC Curses - 26 -
The important changes between versions of PC Curses are
described below; there may be other fixes, enhancements, and
additions not mentioned.
Version 0.4 (3/87)
- Added pads.
- Added tracing.
- Added scrolling regions.
- Added meta character translation (using the Alt key).
- Added shadow windows for pop-up support.
- Added #ifdef's to allow custom versions.
- Added support for color attributes.
- Fixed addch to physically scroll windows.
- Fixed the case sensitivity problem in the assembly module.
- Fixed problem with deallocation of scrolled windows.
- Removed the PC-specific scrolling functions.
Version 0.3 (2/87)
- Added terminfo-style screen updating (wnoutrefresh and doupdate).
- Added unctrl() for handling control characters.
- Fixed getstr to handle erase and kill characters.
Version 0.2 (1/87)
- Added leaveok(), so that cursor can be turned off.
- Added sub-windows.
- Modified screen clearing code to use current attribute.
Version 0.1 (1/87)
- Added unix.h for porting programs to Unix.
- Added support for direct screen updates.
- Added keypad() and function key recognition to wgetch().
- Recoded critical routines in assembly.
- Made internal names start with underscore (unless static).
Version 0.0 (12/86)
- First release of PC Curses.