PD Terminfo/Curses (part 2 of 11)

[sources at genrad.UUCP]

This is part of a distribution of a public domain version of terminfo/curses
It is a rather large distribution, so I have broken it up into 11 modules
(each less than 64K long.) This code is completely public domain, originally
written by Pavel Curtis of Cornell University.  This version has some small
improvements and bug fixes.

This unit contains:

	doc/manual.tbl.ms	- curses documentaion (tbl | nroff -ms)
	doc/ncurses.3		- curses man page

Part 3 will contain the terminfo documentation

----------------- cut here ----------------
: Run this shell script with "sh" not "csh"
PATH=:/bin:/usr/bin:/usr/ucb
export PATH
if test ! -d =doc
then
    echo 'Making directory "=doc"'
    mkdir =doc
fi
echo 'x - =doc/manual.tbl.ms'
sed 's/^X//' <<'//go.sysin dd *' >=doc/manual.tbl.ms
X.po +.5i
X.TL
The Curses Reference Manual
X.AU
Pavel Curtis
X.NH
Introduction
X.LP
Terminfo is a database describing many capabilities of over 150
different terminals.  Curses is a subroutine package which
presents a high level screen model to the programmer, while
dealing with issues such as terminal differences and optimization of
output to change one screenfull of text into another.
X.LP
Terminfo is based on Berkeley's termcap database, but contains a
number of improvements and extensions.  Parameterized strings are
introduced, making it possible to describe such capabilities as
video attributes, and to handle far more unusual terminals than
possible with termcap.
X.LP
Curses is also based on Berkeley's curses package, with many
improvements.  The package makes use of the insert and delete
line and character features of terminals so equipped, and
determines how to optimally use these features with no help from the
programmer.  It allows arbitrary combinations of video attributes
to be displayed, even on terminals that leave ``magic cookies''
on the screen to mark changes in attributes.
X.NH
An Overview of the Package
X.NH 2
Terminology
X.PP
In this document,
the following terminology is kept to with reasonable consistency:
X.IP \fIwindow\fP 10
An internal representation
containing an image of what a section of the terminal screen may look like
at some point in time.
This subsection can either encompass the entire terminal screen,
or any smaller portion down to a single character within that screen.
X.IP \fIterminal\fP 10
Sometimes called \fIterminal screen\fP.
The package's idea of what the terminal's screen currently looks like,
i.e., what the user sees now.
This is a special \fIscreen\fP:
X.IP \fIscreen\fP 10
This is a subset of windows which are as large as the terminal screen,
i.e., they start at the upper left hand corner
and encompass the lower right hand corner.
One of these, \fIstdscr\fP,
is automatically provided for the programmer.
X.NH 2
Compiling Programs using the Package
X.PP
In order to use the library,
it is necessary to have certain types and variables defined.
Therefore, the programmer must have a line:
X.DS
X.B "#include <ncurses.h>"
X.DE
at the top of the program source.
The header file
X.B <ncurses.h>
needs to include
X.B <sgtty.h> ,
so the one should not do so oneself.\u*\d
X.FS
\u*\dThe screen package also uses the Standard I/O library,
so \fB<ncurses.h>\fP includes \fB<stdio.h>\fP.
It is redundant (but harmless) for the programmer to do it, too.
X.FE
Also,
compilations should have the following form:
X.DS
\fBcc\fR [ \fIflags\fR ] file ... \fB\-lbcurses\fR
X.DE
X.NH 2
Updating the Screen
X.PP
In order to update the screen optimally,
it is necessary for the routines to know what the screen currently looks like
and what the programmer wants it to look like next.
XFor this purpose, a data type (structure) named \fIWINDOW\fP
is defined which describes a window image to the routines,
including its starting position on the screen
(the (y, x) coordinates of the upper left hand corner)
and its size.
One of these (called \fIcurscr\fP, for \fIcurrent screen\fP)
is a screen image of what the terminal currently looks like.
Another screen (called \fIstdscr\fP, for \fIstandard screen\fP)
is provided by default to make changes on.
X.PP
A window is a purely internal representation.
It is used to build and store
a potential image of a portion of the terminal.
It doesn't bear any necessary relation
to what is really on the terminal screen.
It is more like an array of characters on which to make changes.
X.PP
When one has a window which describes
what some part of the terminal screen should look like,
the routine \fIrefresh()\fP (or \fIwrefresh()\fP if the window is not
\fIstdscr\fP) is called.
\fIRefresh()\fP in the area covered by the window,
look like that window.
Note, therefore, that changing something on a window
\fIdoes not change the terminal\fP.
Actual updates to the terminal screen are made only by calling
\fIrefresh()\fP or \fIwrefresh()\fP.
This allows the programmer to maintain several different ideas
of what a portion of the terminal screen should look like.
Also, changes can be made to windows in any order,
without regard to motion efficiency.
Then, at will, the programmer can effectively say
``make it look like this,''
and let the package worry about the best way to do this.
X.NH 2
Naming Conventions
X.PP
As hinted above, the routines can use several windows,
but two are automatically given:
\fIcurscr\fP, which knows what the terminal looks like,
and \fIstdscr\fP,
which is what the programmer wants the terminal to look like next.
The user should never really access \fIcurscr\fP directly.
Changes should be made to the appropriate screen,
and then the routine \fIrefresh()\fP (or \fIwrefresh()\fP)
should be called.
X.PP
Many functions are set up to deal with \fIstdscr\fP as a default screen.
XFor example, to add a character to \fIstdscr\fP,
one calls \fIaddch()\fP with the desired character.
If a different window is to be used, the routine \fIwaddch()\fP
(for `w'indow-specific \fIaddch()\fP) is provided.\u*\d
X.FS
\u*\dActually, \fIaddch()\fP is really a ``#define'' macro with arguments,
as are most of the ``functions'' which deal with \fIstdscr\fP
as a default.
X.FE
This convention of prepending function names with a ``w''
when they are to be applied to specific windows is consistent.
The only routines which do \fInot\fP do this are those
to which a window must always be specified.
X.PP
In order to move the current (y, x) coordinates from one point to another,
the routines \fImove()\fP and \fIwmove()\fP are provided.
However, it is often desirable to first move and then perform some I/O
operation.
In order to avoid clumsyness, most I/O routines can be preceded by the prefix
``mv'' and the desired (y, x) coordinates then can be added to the arguments
to the function.
XFor example, the calls
X.DS
move(y, x);
addch(ch);
X.DE
can be replaced by
X.DS
mvaddch(y, x, ch);
X.DE
and
X.DS
wmove(win, y, x);
waddch(win, ch);
X.DE
can be replaced by
X.DS
mvwaddch(win, y, x, ch);
X.DE
Note that the window description pointer (\fIwin\fP)
comes before the added (y, x) coordinates.
If such pointers are need, they are always the first parameters passed.
X.NH 1
Variables
X.PP
Many variables which are used to describe the terminal environment
are available to the programmer. They are:
X.TS
expand;
lw(6m) lw(8n) lw(50n).
type	name	description
_
WINDOW *	curscr	T{
X.fi
current version of the screen (terminal screen).
T}
WINDOW *	stdscr	T{
standard screen.  Most updates are usually done here.
T}
int	LINES	T{
number of lines on the terminal
T}
int	COLS	T{
number of columns on the terminal
T}
int	ERR	T{
error flag returned by routines on a fail.
T}
int	OK	T{
error flag returned by routines when things go right.
T}
X.TE
X.LP
There are also several ``#define'' constants and types
which are of general usefulness:
X.ta 11n
X.DS L
bool		boolean type, actually a ``char'' (e.g., \fIbool doneit;\fR\|)
TRUE		boolean ``true'' flag (1).
XFALSE		boolean ``false'' flag (0).
X.DE
X.NH 1
Usage
X.PP
This is a description of how to actually use the screen package.
In it, we assume all updating, reading, etc. is applied to
\fIstdscr\fP.
All instructions will work on any window,
with changing the function name and parameters as mentioned above.
X.NH 2
Starting up
X.PP
In order to use the screen package,
the routines must know about terminal characteristics, and the space for
\fIcurscr\fP and \fIstdscr\fP must be allocated.
These functions are performed by \fIinitscr()\fP.
Since it must allocate space for the windows,
it can overflow core when attempting to do so.
On this rather rare occasion, \fIinitscr()\fP
returns ERR.
\fIinitscr()\fP must \fIalways\fP
be called before any of the routines which affect windows are used.
If it is not, the program will core dump as soon as either
\fIcurscr\fP or \fIstdscr\fP are referenced.
However, it is usually best to wait to call it
until after you are sure you will need it,
like after checking for startup errors.
Terminal status changing routines like \fInl()\fP and \fIcbreak()\fP
should be called after \fIinitscr()\fP.
X.PP
Now that the screen windows have been allocated,
you can set them up for the run.
If you want to, say, allow the window to scroll, use \fIscrollok()\fP.
If you want the cursor to be left after the last change, use
\fIleaveok()\fP.
If this isn't done, \fIrefresh()\fP
will move the cursor to the window's current (y, x) coordinates
after updating it.
New windows of your own can be created, too, by using the functions
\fInewwin()\fP and \fIsubwin()\fP.
\fIdelwin()\fP will allow you to get rid of old windows.
X.NH 2
Output
X.PP
Now that we have set things up, we will want to actually update the terminal.
The basic functions used to change what will go on a window are \fIaddch()\fP
and \fImove()\fP.
\fIaddch()\fP adds a character at the current (y, x) coordinates,
returning ERR if it would cause the window to illegally scroll,
i.e., printing a character in the lower right-hand corner
of a terminal which automatically scrolls if scrolling is not allowed.
\fImove()\fP changes the current (y, x) coordinates to whatever you want
them to be.
It returns ERR if you try to move off the window.
As mentioned above, you can combine the two into \fImvaddch()\fP
to do both things at once.
X.PP
The other output functions, such as \fIaddstr()\fP
and \fIprintw()\fP, all call \fIaddch()\fP to add characters to the window.
X.PP
After you have put on the window what you want there,
when you want the portion of the terminal covered by the window
to be made to look like it, you must call \fIrefresh()\fP.
In order to optimize finding changes, \fIrefresh()\fP
assumes that any part of the window not changed since the last
\fIrefresh()\fP of that window has not been changed on the terminal, i.e.,
that you have not refreshed a portion of the terminal
with an overlapping window.
If this is not the case, the routine \fItouchwin()\fP
is provided to make it look like the entire window has been changed,
thus making \fIrefresh()\fP check the whole subsection of the terminal for
changes.
X.PP
If you call \fIwrefresh()\fP with \fIcurscr()\fP,
it will make the screen look like \fIcurscr\fP thinks it looks like.
This is useful for implementing a command
which would redraw the screen in case it get messed up.
X.NH 2
Input
X.PP
Input is essentially a mirror image of output.
The complementary function to \fIaddch()\fP is \fIgetch()\fP which,
if echo is set, will call \fIaddch()\fP to echo the character.
Since the screen package needs to know what is on the terminal at all times,
if characters are to be echoed, the tty must be in raw or cbreak mode.
If it is not, \fIgetch()\fP sets it to be cbreak, reads in the character,
and then sets it back the way it was.
X.NH 2
Miscellaneous
X.PP
A plethora of other functions exist for maintaining and changing information
about the windows.
XFor the most part, the descriptions in section 5 should suffice.
X.NH 2
XFinishing Up
X.PP
In order to do certain optimizations, and, on some terminals,
to work at all, some things must be done before the screen routines start up.
In order to clean up after the routines, the routine \fIendwin()\fP
is provided.
It restores tty modes to what they were when \fIinitscr()\fP
was first called, moves the cursor down to the lower-left corner, etc.
Thus, anytime after the call to initscr, \fIendwin()\fP
should be called before exiting.
X.NH
Descriptions of the Functions
X.de Lp
X.sp
X.LP
X..
X.LP
This section describes all the functions available to the
programmer in the curses package.  For an alphabetical list, see the
manual page \fIncurses\fP(3).
X.NH 2
Initialization
X.LP
These functions are called when initializing a program.
X.Lp
\fBinitscr\fP()
X.br
The first function called should always be \fBinitscr\fP.  This will
determine the terminal type and initialize curses data
structures.  \fBinitscr\fP also arranges that the first
call to \fBrefresh\fP will clear the screen.
X.Lp
\fBendwin\fP()
X.br
A program should always call \fBendwin\fP before exiting.  This
function will restore tty modes, move the cursor to the lower left
corner of the screen, reset the terminal into the proper
nonvisual mode.
X.Lp
\fBnewterm\fP(type, fp)
X.br
A program which outputs to more than one terminal should use
\fBnewterm\fP instead of \fBinitscr\fP.  \fBnewterm\fP should be called once for
each terminal.  It returns a variable of type \fBstruct\fP \fBscreen\fP \fB*\fP
which should be saved as a reference to that terminal.  The
arguments are the type of the terminal (a string) and a stdio FILE
pointer for output to the terminal.  The FILE pointer
should be open for both reading and writing, if input from the
terminal is desired.
The program should also call \fBendwin\fP for each terminal being used.
X.Lp
\fBset_term\fP(new)
X.br
This function is used to switch to a different terminal.  The
screen reference for the new terminal is passed as the parameter.
The previous terminal is returned by the function.  All other
calls affect only the current terminal.
X.Lp
\fBlongname\fP()
X.br
This function returns a pointer to a static area containing a
verbose description of the current terminal.  It is defined only
after a call to \fBinitscr\fP or \fBnewterm\fP.
X.NH 2
Option Setting
X.LP
These functions set options within curses.  In each case, \fIwin\fP is
the window affected, and \fIbf\fP is a boolean flag with value \fBTRUE\fP or
\fBFALSE\fP indicating whether to enable or disable the option.  All
options are initially \fBFALSE.\fP  It is not necessary to turn these
options off before calling \fBendwin\fP.
X.Lp
\fBclearok\fP(win,bf)
X.br
If set, the next call to \fBwrefresh\fP with this window will clear the
screen and redraw the entire screen.  If \fIwin\fP is \fBcurscr\fP, the next
call to \fIwrefresh\fP with any window will cause the screen to be
cleared.  This is useful when the contents of the screen are
uncertain, or in some cases for a more pleasing visual effect.
X.Lp
\fBidlok\fP(win,bf)
X.br
If enabled, curses will consider using the hardware insert/delete
line feature of terminals so equipped.  If disabled, curses will
never use this feature.  The insert/delete character feature is
always considered.  Enable this option only if your application
needs insert/delete line, for example, for a screen editor.  It
is disabled by default because insert/delete line is visually
annoying when used in applications where it isn't really needed.
X.Lp
\fBkeypad\fP(win,bf)
X.br
This option enables the keypad of the users terminal.  If
enabled, the user can press a function key (such as an arrow key)
and \fBgetch\fP will return a single value representing the function
key.  If disabled, curses will not treat function keys specially.
If the keypad in the terminal can be turned on (made to transmit)
and off (made to work locally), turning on this option will turn
on the terminal keypad.
X.Lp
\fBleaveok\fP(win,bf)
X.br
Normally, the hardware cursor is left at the location of the
window cursor being refreshed.  This option allows the cursor to be
left wherever the update happens to leave it.  It is useful for
applications where the cursor is not used, since it saves cursor
motions.  If possible, the cursor is made invisible when this
option is enabled.
X.Lp
\fBmeta\fP(win,bf)
X.br
If enabled, characters returned by \fBgetch\fP are transmitted with all
8 bits, instead of stripping the highest bit.  It is useful for
extending the non-text command set in applications where the
terminal has a meta shift key, such as EMACS.  \fINOTE\fP: This function
is currently unsupported, due to lack of support in current
teletype drivers for 8 bit input in non-raw mode.
X.Lp
\fBnodelay\fP(win,bf)
X.br
This option causes \fBgetch\fP to be a non-blocking call.  If no input
is ready, \fBgetch\fP will return -1.
If disabled, \fBgetch\fP will hang until a key is pressed.
X.Lp
\fBscrollok\fP(win,bf)
X.br
This option controls what happens when the cursor of a window is
moved off the edge of the window, either from a newline on the
bottom line, or typing the last character of the last line.  If
disabled, the cursor is left on the bottom line.  If enabled,
\fBwrefresh\fP is called on the window, and then the physical terminal
and window are scrolled up one line.
X.Lp
\fBsetscrreg\fP(t,b)
X.br
\fBwsetscrreg\fP(win,t,b)
X.br
These functions allow the user to set a software scrolling region
in a window \fIwin\fP or \fBstdscr\fP.
\fIt\fP and \fIb\fP are the line numbers of the
top and bottom margin of the scrolling region.  (Line 0 is the
top line of the screen.) If this option and \fBscrollok\fP are enabled,
an attempt to move off the bottom margin line will cause all
lines in the scrolling region to scroll up one line.  Note that
this has nothing to do with use of a physical scrolling region
capability in the terminal, like that in the VT100.  Only the
text of the window is scrolled.
X.LP
The scrolling region really acts as a sort of barrier, limiting the
area of a window over which changes take place.  For this reason, an
attempt to create a scrolling region in an area of the screen which
does not contain the current (y, x) coordinates for that window is an
error.
Similarly, attempts to move the (y, x) coordinates out of the region will
also fail with an ERR return.
X.LP
When a scrolling region is in place, all changes are limited to the region.
XFor example, \fIerase()\fP will only erase the area inside the region;
\fIinsertln()\fP will only shift lines down to the bottom of the region,
etc.  It is anticipated that this method of controlling the area of change
will prove quite handy in a number of applications.
X.LP
To disable the scrolling region, once defined, simply redefine it to be
the whole window.  For example, to disable the scrolling region on
\fIstdscr\fP, the following call would be used:
X.DS
\fBsetscrreg(0, LINES - 1)\fP
X.DE
XFor other windows, the height of the window should be used instead of
(LINES - 1).
X.NH 2
Terminal Mode Setting
X.LP
These functions are used to set modes in the tty driver.  The
initial mode usually depends on the setting when the program was
called: the initial modes documented here represenet the normal
situation.
X.Lp
\fBcbreak\fP()
X.br
\fBnocbreak\fP()
X.br
\fBcrmode\fP()
X.br
\fBnocrmode\fP()
X.br
These functions put the terminal into and out of \fBCBREAK\fP mode.
In this mode, characters typed by the user are immediately
available to the program.  When out of this mode, the teletype driver
will buffer characters typed until newline is typed.  Interrupt
and flow control characters are unaffected by this mode. 
Initially the terminal is not in \fBCBREAK\fP mode.  Most interactive
programs using curses will set this mode.
X.LP
The functions \fBcrmode\fP() and \fBnocrmode\fP() are the result of an
accident in the first version of curses and are retained solely for
upward compatibility.  \fBcrmode\fP() is the same as \fBcbreak\fP() and
\fBnocrmode\fP() is the same as \fBnocbreak\fP().
X.Lp
\fBraw\fP()
X.br
\fBnoraw\fP()
X.br
These functions put the terminal into and out of \fBRAW\fP mode.
\fBRAW\fP mode is just like \fBCBREAK\fP mode except that \fIno\fP
special character processing is done (e.g. the interrupt character will
be passed through to the program, uninterpreted, as will the kill
character, etc.) and all 8 bits of the input character are retained;
in \fBCBREAK\fP mode, the eighth bit is stripped off before it is
given to the program.  Because of the lack of interpretation of
special characters, it is not recommended that programs use this
mode.
X.Lp
\fBecho\fP()
X.br
\fBnoecho\fP()
X.br
These functions control whether characters typed by the user are
echoed as typed.  Initially, characters typed are echoed by the
teletype driver.  Authors of most interactive programs prefer to
do their own echoing in a controlled area of the screen, or not
to echo at all, so they disable echoing.
X.Lp
\fBnl\fP()
X.br
\fBnonl\fP()
X.br
These functions control whether newline is translated into
carriage return and linefeed on output, and whether return is
translated into newline on input.  Initially, the translations do
occur.  By disabling these translations, curses is able to make
better use of the linefeed capability, resulting in faster cursor
motion.
X.Lp
\fBresetty\fP()
X.br
\fBsavetty\fP()
X.br
These functions save and restore the state of the tty modes.
\fBsavetty\fP saves the current state in a buffer, \fBresetty\fP restores the
state to what it was at the last call to \fBsavetty\fP.
X.NH 2
Window Manipulation
X.LP
\fBnewwin\fP(num_lines, num_cols, begy, begx)
X.br
Create a new window with the given number of lines and columns.
The upper left corner of the window is at line \fBbegy\fP column \fBbegx\fP.
If either \fInum_lines\fP or \fInum_cols\fP is zero,
they will be defaulted
to \fBLINES\fP-\fIbegy\fP and \fBCOLS\fP-\fIbegx\fP.
A new full-screen window is
created by calling \fBnewwin\fP(0,0,0,0).
X.Lp
\fBsubwin\fP(orig, num_lines, num_cols, begy, begx)
X.br
Create a new window with the given number of lines and columns.
The window is at position (\fIbegy\fP, \fIbegx\fP) on the screen.  (It is
relative to the screen, not \fIorig\fP.) The window is made in the
middle of the window \fIorig\fP, so that changes made to one window
will affect both windows.  When using this function, often it
will be necessary to call \fItouchwin\fP before calling \fIwrefresh\fP.
X.Lp
\fBdelwin\fP(win)
X.br
Deletes the named window, freeing up all memory associated with
it.  In the case of sub-windows, they should be deleted before the main
window.
X.Lp
\fBmvwin\fP(win, by, bx)
X.br
Move the window so that the upper left corner will be at position
(\fIby\fP, \fIbx\fP).  If the move would cause the window to be off the
screen, it is an error and the window is not moved.
X.Lp
\fBtouchwin\fP(win)
X.br
Throw away all optimization information about which parts of the
window have been touched, by pretending the entire window has
been drawn on.  This is sometimes necessary when using
overlapping windows, since a change to one window will affect the other
window, but the optimization records of the other window will not
reflect the change.
X.Lp
\fBoverlay\fP(win1, win2)
X.br
\fBoverwrite\fP(win1, win2)
X.br
These functions overlay \fIwin1\fP on top of \fIwin2\fP, that is, all text in
\fIwin1\fP is copied into \fIwin2\fP, after lining up the two windows'
origins.
The difference between the functions is that \fBoverlay\fP is
nondestructive (blanks are not copied) while \fBoverwrite\fP is
destructive.
X.NH 2
Causing Output to the Terminal
X.LP
\fBrefresh\fP()
X.br
\fBwrefresh\fP(win)
X.br
These functions must be called to actually get any output on the
terminal, as other routines merely manipulate data structures.
\fBwrefresh\fP copies the named window to the physical terminal screen,
taking into account what is already there in order to do
optimizations.
\fBrefresh\fP is the same, using \fBstdscr\fP as a default screen.
Unless \fBleaveok\fP has been enabled, the physical cursor of the
terminal is left at the location of the window's cursor.
X.Lp
\fBdoupdate\fP()
X.br
\fBwnoutrefresh\fP(win)
X.br
These two functions allow multiple updates with more efficiency
than \fBwrefresh.\fP  To use them, it is important to understand how
curses works.  In addition to all the window structures, curses
keeps two data structures representing the terminal screen: a
\fIphysical\fP screen, describing what is actually on the screen, and a
\fIvirtual\fP screen, describing what the programmer \fIwants\fP to have on
the screen.  \fBwrefresh\fP works by first copying the named window to
the virtual screen (\fBwnoutrefresh\fP), and then calling the routine
to update the screen (\fBdoupdate\fP).  If the programmer wishes to
output several windows at once, a series of calls to \fBwrefresh\fP
will result in alternating calls to \fBwnoutrefresh\fP and \fBdoupdate\fP,
causing several bursts of output to the screen.  By calling
\fBwnoutrefresh\fP for each window, it is then possible to call
\fBdoupdate\fP once, resulting in only one burst of output, with probably
fewer total characters transmitted.
X.NH 2
Writing on Window Structures
X.LP
These routines are used to ``draw'' text on windows.  In all
cases, a missing \fIwin\fP is taken to be \fBstdscr\fP.
\fIy\fP and \fIx\fP are the row
and column, respectively.  The upper left corner is always (0, 0) not (1, 1).
The \fBmv\fP functions imply a call to \fBmove\fP before the call to the
other function.
X.NH 3
Moving the Cursor
X.LP
\fBmove\fP(y, x)
X.br
\fBwmove\fP(win, y, x)
X.br
The cursor associated with the window is moved to the given
location.  This does not move the physical cursor of the terminal
until \fBrefresh\fP is called.
X.NH 3
Writing One Character
X.LP
\fBaddch\fP(ch)
X.br
\fBwaddch\fP(win, ch)
X.br
\fBmvaddch\fP(y, x, ch)
X.br
\fBmvwaddch\fP(win, y, x, ch)
X.br
The character \fIch\fP is put in the window at the current cursor
position of the window.  If \fIch\fP is a tab, newline, or backspace, the
cursor will be moved appropriately in the window.  If \fIch\fP is a
different control character, it will be drawn in the ^X notation.
The position of the window cursor is advanced.  At the right
margin, an automatic newline is performed.  At the bottom of the
scrolling region, if \fBscrollok\fP is enabled, the scrolling region
will be scrolled up one line.
X.NH 3
Writing a String
X.LP
\fBaddstr\fP(str)
X.br
\fBwaddstr\fP(win,str)
X.br
\fBmvaddstr\fP(y,x,str)
X.br
\fBmvwaddstr\fP(win,y,x,str)
X.br
These functions write all the characters of the null terminated
character string \fIstr\fP on the given window.  They are identical to
a series of calls to \fBaddch\fP.
X.NH 3
Clearing Areas of the Screen
X.LP
\fBerase\fP()
X.br
\fBwerase\fP(win)
X.br
These functions copy blanks to every position in the window.
X.Lp
\fBclear\fP()
X.br
\fBwclear\fP(win)
X.br
These functions are like \fBerase\fP and \fBwerase\fP but they also call
\fBclearok\fP, arranging that the screen will be cleared on the next
\fBrefresh\fP.
X.Lp
\fBclrtobot\fP()
X.br
\fBwclrtobot\fP(win)
X.br
All lines below the cursor in this window are erased.  Also, the
current line to the right of the cursor is erased.
X.Lp
\fBclrtoeol\fP()
X.br
\fBwclrtoeol\fP(win)
X.br
The current line to the right of the cursor is erased.
X.NH 3
Inserting and Deleting Text
X.LP
\fBdelch\fP()
X.br
\fBwdelch\fP(win)
X.br
\fBmvdelch\fP(y,x)
X.br
\fBmvwdelch\fP(win,y,x)
X.br
The character under the cursor in the window is deleted.  All
characters to the right on the same line are moved to the left
one position.  This does not imply use of the hardware delete
character feature.
X.Lp
\fBdeleteln\fP()
X.br
\fBwdeleteln\fP(win)
X.br
The line under the cursor in the window is deleted.  All lines
below the current line are moved up one line.  The bottom line of
the window is cleared.  This does not imply use of the hardware
delete line feature.
X.Lp
\fBinsch\fP(c)
X.br
\fBwinsch\fP(win, c)
X.br
\fBmvinsch\fP(y,x,c)
X.br
\fBmvwinsch\fP(win,y,x,c)
X.br
The character \fIc\fP is inserted before the character under the
cursor.  All characters to the right are moved one space to the
right, possibly losing the rightmost character on the line.  This
does not imply use of the hardware insert character feature.
X.Lp
\fBinsertln\fP()
X.br
\fBwinsertln\fP(win)
X.br
A blank line is inserted above the current line.  The bottom line
is lost.  This does not imply use of the hardware insert line
feature.
X.NH 3
XFormatted Output
X.LP
\fBprintw\fP(fmt, args)
X.br
\fBwprintw\fP(win, fmt, args)
X.br
\fBmvprintw\fP(y, x, fmt, args)
X.br
\fBmvwprintw\fP(win, y, x, fmt, args)
X.br
These functions correspond to \fIprintf\fP.  The characters which would
be output by \fIprintf\fP are instead output using \fIwaddch\fP on the given
window.
X.NH 3
Miscelaneous
X.LP
\fBbox\fP(win, vert, hor)
X.br
A box is drawn around the edge of the window.  \fIvert\fP and \fIhor\fP are
the characters the box is to be drawn with.
X.Lp
\fBscroll\fP(win)
X.br
The window is scrolled up one line.  This involves moving the
lines in the window data structure.
X.NH 2
Querying the Contents of a Window
X.LP
\fBgetyx\fP(win,y,x)
X.br
The cursor position of the window is placed in the two integer
variables \fIy\fP and \fIx\fP.  Since this is a macro, no & is necessary.
X.Lp
\fBinch\fP()
X.br
\fBwinch\fP(win)
X.br
\fBmvinch\fP(y,x)
X.br
\fBmvwinch\fP(win,y,x)
X.br
The character at the current position in the named window is
returned.
X.NH 2
Input from the Terminal
X.LP
\fBgetch\fP()
X.br
\fBwgetch\fP(win)
X.br
\fBmvgetch\fP(y,x)
X.br
\fBmvwgetch\fP(win,y,x)
X.br
A character is read from the terminal associated with the window.
In nodelay mode, if there is no input waiting, the value -1 is
returned.  In delay mode, the program will hang until a character is typed.
X.Lp
If \fIkeypad\fP mode is enabled, and a function key is pressed, the
code for that function key will be returned instead of the raw
characters.  Possible function keys are defined with integers
beginning with 0401, whose names begin with KEY_, defined in
<ncurses.h>.  If a character is received that could be the
beginning of a function key (such as escape), curses will set a one
second timer.  If the remainder of the sequence does not come in
within one second, the character will be passed through,
otherwise the function key value will be returned.  For this reason,
on many terminals, there will be a one second delay after a user
presses the escape key.  (Use by a programmer of the escape key
for a single character function is discouraged.)
X.Lp
\fBgetstr\fP(str)
X.br
\fBwgetstr\fP(win,str)
X.br
\fBmvgetstr\fP(y,x,str)
X.br
\fBmvwgetstr\fP(win,y,x,str)
X.br
A series of calls to \fIgetch\fP is made, until a newline is received.
The resulting value is placed in the area pointed at by the
character pointer \fIstr\fP.  The users erase and kill characters are
interpreted, and the string is echoed.
X.Lp
\fBscanw\fP(fmt, args)
X.br
\fBwscanw\fP(win, fmt, args)
X.br
\fBmvscanw\fP(y, x, fmt, args)
X.br
\fBmvwscanw\fP(win, y, x, fmt, args)
X.br
This function corresponds to \fIscanf\fP.  \fIwgetstr\fP is called on the
window, and the resulting line is used as input for the scan.
X.NH 2
Video Attributes
X.LP
\fBattroff\fP(at)
X.br
\fBwattroff\fP(win, attrs)
X.br
\fBattron\fP(at)
X.br
\fBwattron\fP(win, attrs)
X.br
\fBattrset\fP(at)
X.br
\fBwattrset\fP(win, attrs)
X.br
\fBstandout\fP()
X.br
\fBstandend\fP()
X.br
\fBwstandout\fP(win)
X.br
\fBwstandend\fP(win)
X.br
These functions set the \fIcurrent\fP \fIattributes\fP of the named window.
These attributes can be any combination of \fBA_STANDOUT\fP, \fBA_REVERSE\fP,
\fBA_BOLD\fP, \fBA_DIM\fP, \fBA_BLINK\fP, \fBA_BLANK\fP, \fBA_UNDERLINE\fP,
\fBA_PROTECT\fP, and \fBA_ALTCHARSET\fP.
These constants are defined in <ncurses.h> and can
be combined with the C | (or) operator.
X.LP
The current attributes of a window are applied to all characters
that are written into the window.  Attributes are a
property of the character, and move with the character through
any scrolling and insert/delete line/character operations.  To
the extent possible on the particular terminal, they will be
displayed as the graphic rendition of characters put on the
screen.
X.LP
\fIattrset\fP(at) sets the current attributes of the given window to
\fIat\fP.  \fIattroff\fP(at) turns off the named attributes without affecting
any other attributes.  \fIattron\fP(at) turns on the named attributes
without affecting any others.  \fIstandout\fP is the same as
\fIattrset\fP(A_STANDOUT) \fIstandend\fP is the same as \fIattrset\fP(0),
that is, it turns off all attributes.
X.NH 2
Bells and Flashing Lights
X.LP
\fBbeep\fP()
X.br
\fBflash\fP()
X.br
These functions are used to signal the programmer.  \fIbeep\fP will
sound the audible alarm on the terminal, if possible, and if not,
will flash the screen (visible bell), if that is possible.  \fIflash\fP
will flash the screen, and if that is not possible, will sound
the audible signal.  If neither signal is possible, nothing will
happen.  Nearly all terminals have an audible signal (bell or
beep) but only some can flash the screen.
X.NH 2
Portability Functions
X.LP
These functions do not have anything to do with terminal
dependent character output, but tend to be needed by programs that use
curses.  Unfortunately, their implemention varies from one
version of UNIX\u*\d to another.  They have been included here to
enhance the portability of programs using curses.
X.FS
\u*\d UNIX is a trademark of Bell Laboratories.
X.FE
X.Lp
\fBbaudrate\fP()
X.br
\fIbaudrate\fP returns the output speed of the terminal.  The number
returned is the integer baud rate, for example, 9600, rather than
a table index such as \fBB9600\fP.
X.Lp
\fBerasechar\fP()
X.br
The erase character chosen by the user is returned.  This is the
character typed by the user to erase the character just typed.
X.Lp
\fBkillchar\fP()
X.br
The line kill character chosen by the user is returned.  This is
the character typed by the user to forget the entire line being
typed.
X.Lp
\fBflushinp\fP()
X.br
\fIflushinp\fP throws away any typeahead that has been typed by the
user and has not yet been read by the program.
X.NH 2
Debugging
X.LP
These functions are useful when debugging a program with curses.
X.Lp
\fBunctrl\fP(ch)
X.br
This macro expands to a character string which is a printable
representation of the character \fIch\fP.  The program must include the
file <unctrl.h>.  Control characters are displayed in the ^x
notation.  Printing characters are displayed as is.
X.Lp
\fBtraceoff\fP()
X.br
\fBtraceon\fP()
X.br
It is possible to compile a debugging version of curses with
tracing turned on, and with the -g option for sdb.  This library
may be available on your system as -ldcurses.  When using this
version, the file ``trace'' will be created each time the program
is run, containing verbose information showing each step done by
curses.  This output is useful for finding bugs in curses, and
may be useful for finding bugs in user programs.  Since the
output is so verbose, with any bug that cannot be easily and quickly
reproduced, it may be necessary to turn the debugging output off
in some parts of the program.  These functions can be used to
turn tracing off and back on.  When \fIinitscr\fP is first called,
tracing is automatically turned on.
X.NH 2
Lower Level Functions
X.LP
These functions are provided for programs not needing the screen
optimization capabilities of curses.  Programs are discouraged
from working at this level, since they must handle various
glitches in certain terminals.  However, a program can be smaller
if it only brings in the low level routines.
X.NH 3
Cursor Motion
X.Lp
\fBgettmode\fP()
X.br
\fBsetterm\fP(type)
X.br
These two initialization routines are provided for upward
compatibility with the old curses.  \fIgettmode\fP does nothing.
\fIsetterm\fP
results in a call to \fIsetupterm\fP with appropriate arguments.
X.Lp
\fBmvcur\fP(oldrow, oldcol, newrow, newcol)
X.br
This routine optimally moves the cursor from (oldrow, oldcol) to
(newrow, newcol).  The user program is expected to keep track of
the current cursor position.  Note that unless a full screen
image is kept, curses will have to make pessimistic assumptions,
sometimes resulting in less than optimal cursor motion.  For
example, moving the cursor a few spaces to the right can be done
by transmitting the characters being moved over, but if curses
does not have access to the screen image, it doesn't know what
these characters are.
X.LP
If either of oldcol or oldrow are negative, \fImvcur()\fP will refrain
from using any relative motions.  This is handy for occasions when
a program is unsure as to the current cursor location.
X.NH 3
Terminfo Level
X.LP
These routines are called by low level
programs that need access to specific capabilities of terminfo.
A program working at this level should include both <ncurses.h>
and <term.h>.  After a call to \fIsetupterm\fP, the
capabilities will be available with macro names defined in
<term.h>.  See \fBterminfo\fP(5) for a detailed description of the
capabilies.  If the program only needs to handle one terminal,
the definition \fB-DSINGLE\fP can be passed to the C compiler,
resulting in static references to capabilities instead of dynamic
references.  This can result in smaller code, but prevents use of
more than one terminal at a time.  Very few programs use more
than one terminal, so almost all programs can use this flag.
X.Lp
\fBsetupterm\fP(term, filenum, errret)
X.br
This routine is called to initialize a terminal.  \fIterm\fP is the
character string representing the name of the terminal being
used.  \fIfilenum\fP is the UNIX file descriptor of the terminal being
used for output.  \fIerrret\fP is a pointer to an integer, in which a
success or failure indication is returned.  The values returned
can be 1 (all is well), 0 (no such terminal), or -1 (some problem
locating the terminfo database).
X.LP
The value of \fIterm\fP can be given as 0, which will cause the value
of TERM in the environment to be used.  The \fIerrret\fP pointer can
also be given as 0, meaning no error code is wanted.  If \fIerrret\fP
is defaulted, and something goes wrong, \fIsetupterm\fP will print an
appropriate error message and exit, rather than returning.  Thus,
a simple program can call \fIsetupterm\fP(0, 1, 0) and not worry about
initialization errors.
X.LP
\fIsetupterm\fP will check the tty driver mode bits, and change any
that might prevent the correct operation of other low level
routines.  Currently, the mode that expands tabs into spaces is
disabled, because the tab character is sometimes used for different
functions by different terminals.  (Some terminals use it to move
right one space.  Others use it to address the cursor to row or
column 9.) If the system is expanding tabs, \fIsetupterm\fP will remove
the definition of the \fBtab\fP and \fBbacktab\fP functions, assuming that
since the user is not using hardware tabs, they may not be
properly set in the terminal.
X.LP
After the call to \fIsetupterm\fP, the global variable \fIcur_term\fP is set
to point to the current structure of terminal capabilities.  By
calling \fIsetupterm\fP for each terminal, and saving and restoring
\fIcur_term\fP, it is possible for a program to use two or more
terminals at once.  \fISetupterm\fP also stores the names section of the
terminal description in the global character array \fIttytype[]\fP.
Subsequent calls to \fIsetupterm\fP will overwrite this array, so you'll
have to save it yourself if need be.
X.LP
The mode that turns newlines into CRLF on output is not disabled.
Programs that use \fBcud1\fP or \fBind\fP should avoid these capabilities if
their value is linefeed unless they disable this mode.  \fIsetupterm\fP
calls \fIfixterm\fP after any changes it makes.
X.Lp
\fBfixterm\fP()
X.br
\fBresetterm\fP()
X.br
\fBsaveterm\fP()
X.br
These routines can be used to change the tty modes between the
two states: \fInormal\fP (the mode they were in before the program was
started) and \fIprogram\fP (the mode needed by the program).  \fIfixterm\fP
puts the terminal into program mode, and \fIresetterm\fP puts the
terminal into normal mode.  These functions are useful for shell
escapes and control-Z suspensions.  In addition, all programs
must call \fIresetterm\fP before they exit.
X.LP
The routine \fBsaveterm\fP saves the current state of the tty modes
so that the next time \fBfixterm\fP is called, the same modes will be
used.  This is useful for programs which use some of the functions
described in section 2.3 to tailor the modes.
X.LP
Normal mode is stored in \fIcur_term\fP->\fIOttyb\fP, and program mode is in
\fIcur_term\fP->\fINttyb\fP.  These structures are both of type SGTTYB (which
varies depending on the system).  Currently the only possible type
is \fBstruct\fP \fBsgttyb\fP.
X.Lp
\fBvidattr\fP(newmode)
X.br
\fBvidputs\fP(newmode, outc)
X.br
\fInewmode\fP is any combination of attributes, defined in <ncurses.h>.
The proper string to put the terminal in the given video mode is
output. The routine \fBvidattr\fP() sends the output characters to
\fBputchar\fP; \fBvidputs\fP sends them to the given routine \fIoutc\fP,
one character at a time.  That routine should therefore expect one
\fBchar\fP parameter.
The previous mode is remembered by this routine.
X.Lp
\fBtparm\fP(instring, p1, p2, p3, p4, p5, p6, p7, p8, p9)
X.br
\fItparm\fP is used to instantiate a parameterized string.  The
character string returned is suitable for \fItputs\fP.  Up to 9
parameters can be passed, in addition to the parameterized string.
X.Lp
\fBtputs\fP(cp, affcnt, outc)
X.br
A string capability, possibly containing padding information, is
processed.  Enough padding characters to delay for the specified
time replace the padding specification, and the resulting string
is passed, one character at a time, to the routine \fIoutc\fP, which
should expect one character parameter.  (This routine often just
calls \fIputchar\fP.) \fIcp\fP is the capability string.  \fIaffcnt\fP is the
number of units affected by the capability, which varies with the
particular capability.  (For example, the \fIaffcnt\fP for \fIinsert_line\fP
is the number of lines below the inserted line on the screen,
that is, the number of lines that will have to be moved by the
terminal.) \fIaffcnt\fP is used by the padding information of some
terminals as a multiplication factor.  If the capability does not
have a factor, the value 1 should be passed.
X.Lp
\fBputp\fP(str)
X.br
This is a convenient function to output a capability with no
\fIaffcnt\fP.
The string is output to \fIputchar\fP with an \fIaffcnt\fP of 1.
It can be used in simple applications that do not need to process
the output of \fItputs\fP.
//go.sysin dd *
echo 'x - =doc/ncurses.3'
sed 's/^X//' <<'//go.sysin dd *' >=doc/ncurses.3
X.TH NCURSES 3
X.UC 4
X.SH NAME
ncurses \- terminal-independent screen management package
X.SH SYNOPSIS
#include <ncurses.h>
X.sp
X.B cc
[ flags ] files
X.B \-lncurses
[ libraries ]
X.SH DESCRIPTION
These routines give the user a method
of updating screens with reasonable optimization and terminal independence.
They keep an image of the current screen,
and the user sets up an image of a new one.
Then the
X.I refresh()
call tells the routines to make the current screen look
like the new one.
In order to initialize the routines,
the routine
X.I initscr()
must be called before any of the other routines
that deal with windows and screens
are used.
The routine
X.I endwin()
should be called before exiting.
X.SH SEE ALSO
X.I "The Curses Reference Manual",
Curtis
X.br
terminfo(5)
X.SH AUTHOR
Pavel Curtis
X.SH FUNCTIONS
X.nf
X.ds w \fIwin\fR
X.ds s \fIstdscr\fR
X.ta 3i
addch(ch)	add a character to \*s
addstr(str)	add a string to \*s
attroff(at)	turn off video attributes on \*s
attron(at)	turn on video attributes on \*s
attrset(at)	set video attributes on \*s
baudrate()	return baudrate of current terminal
beep()	sound audible bell
box(win,vert,hor)	draw a box around a window
cbreak()	set cbreak mode
crmode()	set cbreak mode
clear()	clear \*s
clearok(scr,boolf)	set clear flag for \fIscr\fR
clrtobot()	clear to bottom on \*s
clrtoeol()	clear to end of line on \*s
delch()	delete a character
deleteln()	delete a line
delwin(win)	delete \*w
doupdate()	update the physical screen
echo()	set echo mode
endwin()	end window modes
erase()	erase \*s
erasechar()	return erase character of current terminal
fixterm()	set terminal into program mode
flash()	execute visible bell
flushinp()	flush outstanding input on current terminal
getch()	get a char through \*s
getcap(name)	get terminal capability \fIname\fR
getstr(str)	get a string through \*s
gettmode()	no-op
getyx(win,y,x)	get (y,x) coordinates
idlok(win,flag)	enable insert/delete lines operations
inch()	get char at current (y,x) coordinates
initscr()	initialize screens
insch(c)	insert a char
insertln()	insert a line
keypad(win,flag)	enable keypad-sequence mapping
killchar()	return kill character of current terminal
leaveok(win,boolf)	set leave flag for \*w
longname(termbuf,name)	get long name from \fItermbuf\fR
meta(win,flag)	enable use of the `meta' key
move(y,x)	move to (y,x) on \*s
mvcur(lasty,lastx,newy,newx)	actually move cursor
newterm(type,fp)	initialise a new terminal
newwin(lines,cols,begin_y,begin_x)\ 	create a new window
nl()	set newline mapping
nocbreak()	unset cbreak mode
nocrmode()	unset cbreak mode
nodelay(win,flag)	make getch() non-blocking
noecho()	unset echo mode
nonl()	unset newline mapping
noraw()	unset raw mode
overlay(win1,win2)	overlay win1 on win2
overwrite(win1,win2)	overwrite win1 on top of win2
printw(fmt,arg1,arg2,...)	printf on \*s
putp(string)	tputs() with affcnt=1 and outc=putchar
raw()	set raw mode
refresh()	make current screen look like \*s
resetterm()	set terminal into normal mode
resetty()	reset tty flags to stored value
savetty()	store current tty flags
saveterm()	save current state of tty
scanw(fmt,arg1,arg2,...)	scanf through \*s
scroll(win)	scroll \*w one line
scrollok(win,boolf)	set scroll flag
setscrreg(top,bottom)	set up scrolling region on \*s
setterm(name)	set term variables for name
set_term(new)	change current terminal
setupterm(term,fd,errret)	initialise terminal capabilities
standend()	end standout mode
standout()	start standout mode
subwin(win,lines,cols,begin_y,begin_x)\ 	create a subwindow
touchwin(win)	\*(lqchange\*(rq all of \*w
tparm(string,p1..p9)	instantiate a parameterised string
tputs(string,affcnt,outc)	process a capability string
traceoff()	turn off debugging output
traceon()	turn on debugging output
unctrl(ch)	printable version of \fIch\fR
vidattr(newmode)	set terminal's video attributes
vidputs(newmode,outc)	set video attributes into a function
waddch(win,ch)	add char to \*w
waddstr(win,str)	add string to \*w
wattroff(win,at)	turn off video attributes on \*w
wattron(win,at)	turn on video attributes on \*w
wattrset(win,at)	set video attributes on \*w
wclear(win)	clear \*w
wclrtobot(win)	clear to bottom of \*w
wclrtoeol(win)	clear to end of line on \*w
wdelch(win,c)	delete char from \*w
wdeleteln(win)	delete line from \*w
werase(win)	erase \*w
wgetch(win)	get a char through \*w
wgetstr(win,str)	get a string through \*w
winch(win)	get char at current (y,x) in \*w
winsch(win,c)	insert char into \*w
winsertln(win)	insert line into \*w
wmove(win,y,x)	set current (y,x) co-ordinates on \*w
wnoutrefresh(win)	copy \*w to virtual screen
wprintw(win,fmt,arg1,arg2,...)\ 	printf on \*w
wrefresh(win)	make screen look like \*w
wscanw(win,fmt,arg1,arg2,...)\ 	scanf through \*w
wsetscrreg(win,top,bottom)	set up scrolling region on \*w
wstandend(win)	end standout mode on \*w
wstandout(win)	start standout mode on \*w
//go.sysin dd *
exit