talexander
/
freebsd_amp_hwpstate
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
freebsd_amp_hwpstate/lib/libncurses/doc/manual.doc

1362 lines
53 KiB
Plaintext
Raw Blame History

The Curses Reference Manual
Pavel Curtis 1982
Zeyd M. Ben-Halim 1993
zmbenhal@netcom.com
Caveat Emptor:
I'm slowly but surely updating the documentation of
ncurses to reflect the current status of the code. The text
below may refer to yet to be implemented functions or
missing functionality. Description of functions may be
missing or out of date. ncurses is aimed at being compatible
with AT&T curses as defined in SysVR4.
There is no ?roff sources for this document. I may one day
go nuts and create one, but don't hold your breath :-)
1. Introduction
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.
Terminfo is based on Berkeley's termcap database, but con-
tains 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.
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.+
2. An Overview of the Package
2.1. Terminology
In this document, the following terminology is kept
to with reasonable consistency:
window 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.
terminal Sometimes called terminal screen. The package's
idea of what the terminal's screen currently looks
like, i.e., what the user sees now. This is a
special screen.
screen 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, stdscr, is automati-
cally provided for the programmer.
2.2. Compiling Programs using the Package
In order to use the library, it is necessary to have
certain types and variables defined. Therefore, the pro-
grammer must have a line:
#include <ncurses.h>
at the top of the program source. The screen package
uses the Standard I/O library, so <ncurses.h> includes
<stdio.h>. Ncurses also includes <termios.h>, <termio.h>, or
<sgtty.h> depending on your system. It is redundant (but
harmless) for the programmer to do it, too. In linking with
ncurses you need to have `-lncurses' in your LDFLAGS or on
the command line. There is no need for any other libraries.
2.3. Updating the Screen
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. For this purpose, a data type (structure) named WINDOW
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 curscr, for current screen) is a screen
image of what the terminal currently looks like. Another
screen (called stdscr, for standard screen) is provided by
default to make changes on.
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.
When one has a window which describes what some part of
the terminal screen should look like, the routine refresh()
(or wrefresh() if the window is not stdscr) is called.
Refresh() in the area covered by the window, look like that
window. Note, therefore, that changing something on a win-
dow does not change the terminal. Actual updates to the
terminal screen are made only by calling refresh() or wre-
fresh(). 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.
2.4. Naming Conventions
As hinted above, the routines can use several windows,
but two are automatically given: curscr, which knows what
the terminal looks like, and stdscr, which is what the pro-
grammer wants the terminal to look like next. The user
should never really access curscr directly. Changes should
be made to the appropriate screen, and then the routine
refresh() (or wrefresh()) should be called.
Many functions are set up to deal with stdscr as a
default screen. For example, to add a character to stdscr,
one calls addch() with the desired character. If a differ-
ent window is to be used, the routine waddch() (for
`w'indow-specific addch()) is provided. This convention of
prepending function names with a ``w'' when they are to be
applied to specific windows is consistent. The only rou-
tines which do not do this are those to which a window must
always be specified.
In order to move the current (y, x) coordinates from
one point to another, the routines move() and wmove() are
provided. However, it is often desirable to first move and
then perform some I/O operation. In order to avoid clumsy-
ness, 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. For example, the calls
move(y, x);
addch(ch);
can be replaced by
mvaddch(y, x, ch);
and
wmove(win, y, x);
waddch(win, ch);
can be replaced by
mvwaddch(win, y, x, ch);
Note that the window description pointer (win) comes before
the added (y, x) coordinates. If such pointers are need,
they are always the first parameters passed.
3. Variables
Many variables which are used to describe the terminal
environment are available to the programmer. They are:
type name description
------------------------------------------------------------------
WINDOW *curscr current version of the screen (terminal screen).
WINDOW *stdscr standard screen. Most updates are done here.
int LINES number of lines on the terminal
int COLS number of columns on the terminal
There are also several `#define' constants and types which
are of general usefulness:
bool boolean type, actually a `char' (e.g., bool doneit;)
TRUE boolean `true' flag (1).
FALSE boolean `false' flag (0).
ERR -1 error flag returned by routines on a fail.
OK 0 error flag returned by routines when things
go right.
4. Usage
This is a description of how to actually use the screen
package. In it, we assume all updating, reading, etc. is
applied to stdscr. All instructions will work on any win-
dow, with changing the function name and parameters as men-
tioned above.
4.1. Starting up
In order to use the screen package, the routines must
know about terminal characteristics, and the space for
curscr and stdscr must be allocated. These functions are
performed by initscr(). Since it must allocate space for the
windows, it can overflow memory when attempting to do so. On
this rather rare occasion, initscr() returns ERR.
initscr() must always 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 curscr or stdscr 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 nl() and cbreak() should be called after
initscr().
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 scrollok(). If you want the cursor to
be left after the last change, use leaveok(). If this isn't
done, refresh() 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 newwin(),
derwin(), and subwin(). delwin() will allow you to get rid
of old windows.
4.2. Output
Now that we have set things up, we will want to actu-
ally update the terminal. The basic functions used to
change what will go on a window are addch() and move().
addch() 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. move() 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 mvaddch() to do both things at
once.
The other output functions, such as addstr() and
printw(), all call addch() to add characters to the window.
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 refresh().
In order to optimize finding changes, refresh() assumes that
any part of the window not changed since the last refresh()
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
touchwin() is provided to make it look like the entire win-
dow has been changed, thus making refresh() check the whole
subsection of the terminal for changes.
If you call wrefresh() with curscr(), it will make the
screen look like curscr thinks it looks like. This is use-
ful for implementing a command which would redraw the screen
in case it get messed up.
4.3. Input
Input is essentially a mirror image of output. The
complementary function to addch() is getch() which, if echo
is set, will call addch() 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. Since initially the terminal has echo-
ing enable and is in nocreak mode, one or the other has to
changed before calling getch(). The result of not doing this
is unpredictable output.
4.4. Miscellaneous
A plethora of other functions exist for maintaining and
changing information about the windows. For the most part,
the descriptions in section 5 should suffice.
4.5. Finishing Up
In order to do certain optimizations, and, on some ter-
minals, 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 endwin() is provided. It restores tty
modes to what they were when initscr() was first called,
moves the cursor down to the lower-left corner, etc. Thus,
anytime after the call to initscr, endwin() should be called
before exiting.
5. Descriptions of the Functions
This section describes all the functions available to the
programmer in the curses package. For an alphabetical list,
see the manual page ncurses(3).
5.1. Initialization
These functions are called when initializing a program.
initscr()
The first function called should always be initscr. This
will determine the terminal type and initialize curses data
structures. initscr also arranges that the first call to
refresh will clear the screen. If an error occurs a message
is writen to standard error and the program exits. Otherwise
it returns a pointer to stdscr. Some function may be called
before initscr (slk_init, filter, ripofflines, use_env, and
if you are using multiple terminals newterm.)
endwin()
A program should always call endwin before exiting or
shelling out of the program. 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.
Calling refresh() or doupdate() after a temporary escape
from the program will restore the screen to its original
status.
newterm(type, ofp, ifp)
A program which outputs to more than one terminal should use
newterm instead of initscr. newterm should be called once
for each terminal. It returns a variable of type SCREEN
* which should be saved as a reference to that terminal. The
arguments are the type of the terminal (a string) and FILE
pointers for the output and input of the terminal. If type
is NULL then the environment variable $TERM is used. endwin
must called for each terminal opened using this function.
set_term(new)
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 func-
tion. All other calls affect only the current terminal.
delscreen(sp)
longname()
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 initscr or newterm.
termattrs()
termname()
5.2. Option Setting
These functions set options within curses. In each case,
win is the window affected, and bf is a boolean flag with
value TRUE or FALSE indicating whether to enable or disable
the option. All options are initially FALSE. It is not
necessary to turn these options off before calling endwin.
clearok(win,bf)
If set, the next call to wrefresh with this window will
clear the screen and redraw the entire screen. If win is
curscr, the next call to wrefresh 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.
idlok(win,bf)
If enabled, curses will consider using the hardware
insert/delete line feature of terminals so equipped. If
disabled, curses will not use this feature. 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.
idcok(win,bf)
This option allows curses will use inset/delete character
capabilities if any are defined. This option is on be
default.
immedok(win,bf)
If this option is enabled any change in the window's image
causes a call to wrefresh. Enabling this option can degrade
performance; it is disabled by default.
keypad(win,bf)
This option enables the keypad of the users terminal. If
enabled, the user can press a function key (such as an arrow
key) and getch 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), turn-
ing on this option will turn on the terminal keypad. All the
possible function keys are defined in ncurses.h as KEY_*.
leaveok(win,bf)
Normally, the hardware cursor is left at the location of the
window cursor being refreshed. This option allows the cur-
sor 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.
meta(win,bf)
If enabled, characters returned by getch are transmitted
with all 8 bits, instead of stripping the highest bit. It
is useful for extending the non-text command set in applica-
tions where the terminal has a meta shift key, such as
EMACS. NOTE: This function is currently unsupported.
notimeout(win,bf)
This option controls whether a timer is set when wgetch is
trying to interpret an input sequence. See keypad.
scrollok(win,bf)
This option controls what happens when the cursor of a win-
dow is moved off the edge of the window, either from a new-
line 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, wrefresh is called on the window, and then
the physical terminal and window are scrolled up one line.
setscrreg(t,b)
wsetscrreg(win,t,b)
These functions allow the user to set a software scrolling
region in a window win or stdscr. t and b are the line num-
bers of the top and bottom margin of the scrolling region.
(Line 0 is the top line of the screen.) If this option and
scrollok are enabled, an attempt to move off the bottom mar-
gin 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 termi-
nal, like that in the VT100. Only the text of the window is
scrolled.
The scrolling region really acts as a sort of barrier, lim-
iting 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.
When a scrolling region is in place, all changes are limited
to the region. For example, erase() will only erase the
area inside the region; insertln() 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.
To disable the scrolling region, once defined, simply rede-
fine it to be the whole window. For example, to disable the
scrolling region on stdscr, the following call would be
used:
setscrreg(0, LINES - 1)
For other windows, the height of the window should be used
instead of (LINES - 1).
5.3. Terminal Mode Setting
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.
cbreak()
nocbreak()
crmode()
nocrmode()
These functions put the terminal into and out of CBREAK
mode. In this mode, characters typed by the user are immedi-
ately available to the program. When out of this mode, the
device 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 CBREAK mode.
Most interactive programs using curses will set this mode.
The functions crmode() and nocrmode() are the result of an
accident in the first version of curses and are retained
solely for upward compatibility. crmode() is the same as
cbreak() and nocrmode() is the same as nocbreak(). See 4.3
for a important note on using these functions.
raw()
noraw()
These functions put the terminal into and out of RAW mode.
RAW mode is just like CBREAK mode except that no 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 CBREAK 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.
echo()
noecho()
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 pro-
grams prefer to do their own echoing in a controlled area of
the screen, or not to echo at all, so they disable echoing.
halfdelay(t)
This options is similar to cbreak mode except that if after
blocking for t tenth of a seconds no input is received ERR
is returned. t must between 1 and 255. Use nocbreak to leave
this mode.
nodelay(win,bf)
This option causes getch to be a non-blocking call. If no
input is ready, getch will return ERR. If disabled, getch
will hang until a key is pressed.
timeout(t)
wtimeout(win,t)
These functions offer control over the blocking action of a
read. If t is negative, reading will block until there is
input. If t is zero, no blocking will occur, read returns
ERR if no input is available. If t is posistive, the read
will block for t milliseconds and return ERR if there is
still no input.
These routines offer better and finer control than nodelay()
and halfdelay() and their use is recommended.
nl()
nonl()
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 trans-
lations do occur. By disabling these translations, curses
is able to make better use of the linefeed capability,
resulting in faster cursor motion.
savetty()
resetty()
These functions save and restore the state of the tty modes.
savetty saves the current state in a buffer, resetty
restores the state to what it was at the last call to save-
tty.
5.4. Window Manipulation
newwin(num_lines, num_cols, begy, begx)
Create a new window with the given number of lines and
columns. The upper left corner of the window is at line
begy column begx. If either num_lines or num_cols is zero,
they will be defaulted to LINES-begy and COLS-begx. A new
full-screen window is created by calling newwin(0,0,0,0).
subwin(orig, num_lines, num_cols, begy, begx)
Create a new window with the given number of lines and
columns. The window is at position (begy, begx) on the
screen. (It is relative to the screen, not orig.) The win-
dow is made in the middle of the window orig, so that
changes made to one window will affect both windows. When
using this function, often it will be necessary to call
touchwin before calling wrefresh.
derwin(orig, num_lines, num_cols, begy, begx)
Is similar to subwin only the new window is created relative
to the original window, not the screen.
delwin(win)
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.
dupwin(win)
mvderwin(win,y,x)
syncok(win,bf)
wsyncup(win)
wcursyncup(win)
wsyncdown(win)
mvwin(win, by, bx)
Move the window so that the upper left corner will be at
position (by, bx). If the move would cause the window to be
off the screen, it is an error and the window is not moved.
touchline(win,start,count)
touchwin(win)
Throw away all optimization information about which parts of
the window have been touched, by pretending the entire win-
dow 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.
wtouchln(win,y,n,changed)
Throw away optimization information, or mark as unchanged,
n lines starting at y, depending on the value of changed.
untouchwin(win)
Mark the whole window as unchcnged since the lat wrefresh.
is_linetouched(win,line)
is_wintouched(win)
These routines are used to check if the given line/window
has been modified since the last wrefresh. They will return
TRUE is that is the case, FALSE otherwise. is_linetouched
will return ERR if there is no such line.
overlay(win1, win2)
overwrite(win1, win2)
These functions overlay win1 on top of win2, that is, all
text in win1 is copied into win2, after lining up the two
windows' origins. The difference between the functions is
that overlay is nondestructive (blanks are not copied) while
overwrite is destructive.
copywin(win,win,sminrow,smincol,dminrow,dmincol,dmaxrow,
dmaxcol,overlay)
Low level function used to implement overlay/overwrite.
5.5. Causing Output to the Terminal
refresh()
wrefresh(win)
These functions must be called to actually get any output on
the terminal, as other routines merely manipulate data
structures. wrefresh copies the named window to the physi-
cal terminal screen, taking into account what is already
there in order to do optimizations. refresh is the same,
using stdscr as a default screen. Unless leaveok has been
enabled, the physical cursor of the terminal is left at the
location of the window's cursor.
doupdate()
wnoutrefresh(win)
These two functions allow multiple updates with more effi-
ciency than wrefresh. 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 physical screen, describing what is
actually on the screen, and a virtual screen, describing
what the programmer wants to have on the screen. wrefresh
works by first copying the named window to the virtual
screen (wnoutrefresh), and then calling the routine to
update the screen (doupdate). If the programmer wishes to
output several windows at once, a series of calls to wre-
fresh will result in alternating calls to wnoutrefresh and
doupdate, causing several bursts of output to the screen.
By calling wnoutrefresh for each window, it is then possible
to call doupdate once, resulting in only one burst of out-
put, with probably fewer total characters transmitted.
redrawwin(win)
wredrawln(win,start,count)
5.6. Writing on Window Structures
These routines are used to ``draw'' text on windows. In all
cases, a missing win is taken to be stdscr. y and x are the
row and column, respectively. The upper left corner is
always (0, 0) not (1, 1). The mv functions imply a call to
move before the call to the other function.
5.6.1. Moving the Cursor
move(y, x)
wmove(win, y, x)
The cursor associated with the window is moved to the given
location. This does not move the physical cursor of the
terminal until refresh is called.
5.6.2. Writing One Character
addch(ch)
waddch(win, ch)
mvaddch(y, x, ch)
mvwaddch(win, y, x, ch)
The character ch is put in the window at the current cursor
position of the window. If ch is a tab, newline, or
backspace, the cursor will be moved appropriately in the
window. If ch 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 scrol-
lok is enabled, the scrolling region will be scrolled up one
line.
5.6.3. Writing a String
addstr(str)
addnstr(str,n)
waddstr(win,str)
waddnstr(win,str,n)
mvaddstr(y,x,str)
mvaddnstr(y,x,str,n)
mvwaddstr(win,y,x,str)
mvwaddnstr(win,y,x,str,n)
These functions write all the characters of the null termi-
nated character string str on the given window. They are
identical to a series of calls to addch. Routines with 'n'
write n characters of str. If n is -1 then the entire string
is written.
addchstr(chstr)
addchnstr(chstr,n)
waddchstr(win,chstr)
waddchnstr(win,chstr,n)
mvaddchstr(y,x,chstr)
mvaddchnstr(y,x,chstr,n)
mvwaddchstr(win,y,x,chstr)
mvwaddchnstr(win,y,x,chstr,n)
These functions copy chstr onto the window image starting at
the current cursor position. Routines with 'n' write at most
n characters of chstr (as many as will fit on the line). If
n is -1 then the entire string is written. The cursor is not
advanced and no checking for control characters is done.
These routines are faster than the addstr() group. chstr is
a pointer to an array of chtype.
5.6.4. Clearing Areas of the Screen
erase()
werase(win)
These functions copy blanks to every position in the window.
clear()
wclear(win)
These functions are like erase and werase but they also call
clearok, arranging that the screen will be cleared on the
next refresh. The result can visually annoying.
clrtobot()
wclrtobot(win)
All lines below the cursor in this window are erased. Also,
the current line to the right of the cursor is erased.
clrtoeol()
wclrtoeol(win)
The current line to the right of the cursor is erased.
5.6.5. Inserting and Deleting Text
delch()
wdelch(win)
mvdelch(y,x)
mvwdelch(win,y,x)
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 hard-
ware delete character feature.
deleteln()
wdeleteln(win)
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.
insch(c)
winsch(win, c)
mvinsch(y,x,c)
mvwinsch(win,y,x,c)
The character c 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 char-
acter feature.
insertln()
winsertln(win)
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.
5.6.6. Formatted Output
printw(fmt, ...)
wprintw(win, fmt, ...)
mvprintw(y, x, fmt, ...)
mvwprintw(win, y, x, fmt, ...)
vwprintw(win, fmt, va_list)
These functions correspond to printf. The characters which
would be output by printf are instead output using waddch on
the given window. vwprintw() acts like vprintf().
5.6.7. Line drawing
Borders are drawn inside a window and not around it.
border(ls, rs, ts, bs, tl, tr, bl, br)
wborder(win, ls, rs, ts, bs, tl, tr, bl, br)
box(win, vert, hor)
A border is drawn around the edges of the window. ls, rs,
ts, bs, tl, tr, bl, and br are the character and attribute
to draw the left side, right side, top side, bottom side,
top left, top right, bottom left, and bottom right respec-
tively.
If any of these are 0, the follwing defaults are used:
ACS_VLINE. ACS_VLINE, ACS_HLINE, ACS_HLINE, ACS_ULCORNER,
ACS_URCORNER, ACS_LLCORNER, ACS_LRCORNER. box is shorthand
for wborder(win, vert, vert, hor, hor, 0, 0, 0, 0).
vline(ch,n)
wvline(win,ch,n)
These functions draw a vertical line starting at the current
cursor position using ch for n characters or as many as will
fit on the window. The cursor position is not advanced.
hline(ch,n)
whline(win,ch,n)
These functions draw a horizontal line starting at the
current cursor position using ch for n characters or as many
as will fit on the window. The cursor position is not
advanced.
5.6.8 Scrolling
Scrolling only works if enabled via scrollok(). The cursor
position is unchanged by these functions. As an optimization
the physical screen is scrolled if the window in question is
covering the entire screen.
scroll(win)
The window is scrolled up one line. This involves moving
the lines in the window data structure.
scrl(n)
wscrl(win,n)
These functions scroll thw window up/down n lines depending
on the sign on n (+ for up, - for down).
5.7. Querying the Contents of a Window
getyx(win,y,x)
The cursor position of the window is placed in the two
integer variables y and x. Since this is a macro, no & is
necessary.
inch()
winch(win)
mvinch(y,x)
mvwinch(win,y,x)
The character at the current position in the named window is
returned.
5.8. Input from the Terminal
getch()
wgetch(win)
mvgetch(y,x)
mvwgetch(win,y,x)
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.
If keypad 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.) The one second delay can
be turned off using the notimeout() function.
getstr(str)
wgetstr(win,str)
mvgetstr(y,x,str)
mvwgetstr(win,y,x,str)
A series of calls to getch is made, until a newline is
received. The resulting value is placed in the area pointed
at by the character pointer str. The users erase and kill
characters are interpreted, and the string is echoed.
scanw(fmt, ...)
wscanw(win, fmt, ...)
mvscanw(y, x, fmt, ...)
mvwscanw(win, y, x, fmt, ...)
vwscanw(win,fmt,va_list)
These functions corresponds to scanf. wgetstr is called on
the window, and the resulting line is used as input for the
scan.
5.9. Video Attributes
attroff(at)
wattroff(win, attrs)
attron(at)
wattron(win, attrs)
attrset(at)
wattrset(win, attrs)
standout()
standend()
wstandout(win)
wstandend(win)
These functions set the current attributes of the named win-
dow. These attributes can be any combination of A_STANDOUT,
A_REVERSE, A_BOLD, A_DIM, A_BLINK, A_BLANK, A_UNDERLINE,
A_PROTECT, A_INVIS, and A_ALTCHARSET. These constants are
defined in <ncurses.h> and can be combined with the C | (or)
operator. 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 char-
acter 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.
attrset(at) sets the current attributes of the given window
to at. attroff(at) turns off the named attributes without
affecting any other attributes. attron(at) turns on the
named attributes without affecting any others. standout is
the same as attrset(A_STANDOUT), standend is the same as
attrset(0), that is, it turns off all attributes.
5.10. Color Manipulation
Ncurses provides support for the use of color on terminals
that are capable of display it. Note the BSD and older SYSV
curses don't support color. Color support in the PC version
is not compatible with SYSR4.
has_colors()
this function returns TRUE if the terminal supports color,
FALSE otherwise. Other color handling funtions will return
ERR if has_colors() is FALSE. You should always check before
using color and use other video attributes to replace color.
can_change_color()
This function returns TRUE if the terminal is capable of
redefining colors using the init_color function, FALSE if it
can't. Don't use init_color and color_content if it returns
FALSE.
start_color()
This function must be called before any other color handling
function is called. It initializes the 8 basic colors (see
appendix I) and sets the global variables COLORS and COLOR_
PAIRS to the maximum number of colors and color-pairs a
terminal can handle.
init_pair(pair, fg, bg)
This function changes the definition of a color-pair, pair.
Each pair has a foregroung color fg, and a background color
bg. Both values must be between 0 and COLORS-1. pair must be
between 1 and COLOR_PAIRS-1.
[If a pair is changed from a previous definition, the screen
is refreshed and all occurances of the color-pair are
changed to reflect the change.]
pair_content(pair, f, b)
This function stores the foreground and background colors of
the color-pair pair into the variables pointed to by f, b.
pair should be between 1 and COLOR_PAIRS-1.
init_color(color, r, g, b)
This function changes the value of a given color. A color is
defined by its red, green, and blue components, r, g, and b.
These values must be between 0 and 1000. color should be
between 0 and COLORS-1.
color_content(color, r, g, b)
This function puts the red, green, and blue components of
color into the variable pointed to by r, g, b respectively.
color should be between 0 and COLORS-1.
5.11. Pads
5.12. Soft Labels
5.13. Bells and Flashing Lights
beep()
flash()
These functions are used to signal the programmer. beep
will sound the audible alarm on the terminal, if possible,
and if not, will flash the screen (visible bell), if that is
possible. flash 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.
5.14. Portability Functions
These functions do not have anything to do with terminal
dependent character output, but tend to be needed by pro-
grams that use curses. Unfortunately, their implemention
varies from one version of UNIX* to another. They have been
included here to enhance the portability of programs using
curses.
baudrate()
baudrate returns the output speed of the terminal. The num-
ber returned is the integer baud rate, for example, 9600,
rather than a table index such as B9600.
erasechar()
The erase character chosen by the user is returned. This is
the character typed by the user to erase the character just
typed.
killchar()
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.
flushinp()
flushinp throws away any typeahead that has been typed by
the user and has not yet been read by the program.
5.15. Debugging
These functions are useful when debugging a program with
curses.
unctrl(ch)
This macro expands to a character string which is a print-
able representation of the character ch. The program must
include the file <unctrl.h>. Control characters are dis-
played in the ^x notation. Printing characters are displayed
as is.
traceoff()
traceon()
It is possible to compile a debugging version of curses with
tracing turned on, and with the -g option for gdb. 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 initscr is first called, tracing is
automatically turned on.
You should use -DTRACE when compiling programs that use
tracing.
_tracef()
This function can be used to output your own debugging info-
rmation. It is only available only if you compile with the
-DTRACE flag and linking with -ldcurses. It can be used the
same way as printf, only it outputs a newline after the end
of arguments.
6. Lower Level Functions
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 han-
dle various glitches in certain terminals. However, a pro-
gram can be smaller if it only brings in the low level rou-
tines.
gettmode()
setterm(type)
These two initialization routines are provided for upward
compatibility with the old curses. gettmode does nothing.
setterm results in a call to setupterm with appropriate
arguments.
def_prog_mode()
def_shell_mode()
These functions define "program" mode and "shell" mode. The
first describes the status of a terminal while in curses,
the second the status outside curses.
reset_prog_mode()
reset_shell_mode()
These functions restore a terminal to "program" mode after
shelling out, or to "shell" mode before shelling out.
fixterm()
resetterm()
These functions are obselete and have been replaced by
reset_prog_mode() and reset_prog_mode() respectively.
saveterm()
This fucntion is obselete and is replaced by
def_prog_mode().
mvcur(oldrow, oldcol, newrow, newcol)
This routine optimally moves the cursor from (oldrow, old-
col) 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 pes-
simistic assumptions, sometimes resulting in less than opti-
mal cursor motion. For example, moving the cursor a few
spaces to the right can be done by transmitting the charac-
ters being moved over, but if curses does not have access to
the screen image, it doesn't know what these characters are.
If either of oldcol or oldrow are negative, mvcur() will
refrain from using any relative motions. This is handy for
occasions when a program is unsure as to the current cursor
location.
7. Terminfo Level
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 setupterm, the capabilities will
be available with macro names defined in <term.h>. See ter-
minfo(5) for a detailed description of the capabilies. If
the program only needs to handle one terminal, the defini-
tion -DSINGLE can be passed to the C compiler, resulting in
static references to capabilities instead of dynamic refer-
ences. 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.
setupterm(term, filenum, errret)
This routine is called to initialize a terminal. term is
the character string representing the name of the terminal
being used. filenum is the UNIX file descriptor of the ter-
minal being used for output. errret 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).
The value of term can be given as 0, which will cause the
value of TERM in the environment to be used. The errret
pointer can also be given as 0, meaning no error code is
wanted. If errret is defaulted, and something goes wrong,
setupterm will print an appropriate error message and exit,
rather than returning. Thus, a simple program can call
setupterm(0, 1, 0) and not worry about initialization
errors.
setupterm 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, setupterm will remove the definition of the
tab and backtab functions, assuming that since the user is
not using hardware tabs, they may not be properly set in the
terminal.
After the call to setupterm, the global variable cur_term is
set to point to the current structure of terminal capabili-
ties. By calling setupterm for each terminal, and saving
and restoring cur_term, it is possible for a program to use
two or more terminals at once. Setupterm also stores the
names section of the terminal description in the global
character array ttytype[]. Subsequent calls to setupterm
will overwrite this array, so you'll have to save it your-
self if need be.
The mode that turns newlines into CRLF on output is not dis-
abled. Programs that use cud1 or ind should avoid these
capabilities if their value is linefeed unless they disable
this mode. setupterm calls fixterm after any changes it
makes.
vidattr(newmode)
vidputs(newmode, outc)
newmode 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 vidattr() sends the
output characters to putchar; vidputs sends them to the
given routine outc, one character at a time. That routine
should therefore expect one char parameter. The previous
mode is remembered by this routine.
tparm(instring, p1, p2, p3, p4, p5, p6, p7, p8, p9)
tparm is used to instantiate a parameterized string. The
character string returned is suitable for tputs. Up to 9
parameters can be passed, in addition to the parameterized
string.
tputs(cp, affcnt, outc)
A string capability, possibly containing padding informa-
tion, 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 outc, which should expect one character parame-
ter. (This routine often just calls putchar.) cp is the
capability string. affcnt is the number of units affected
by the capability, which varies with the particular capabil-
ity. (For example, the affcnt for insert_line 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.)
affcnt 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.
putp(str)
This is a convenient function to output a capability with no
affcnt. The string is output to putchar with an affcnt of
1. It can be used in simple applications that do not need
to process the output of tputs.
8. Termcap Emulation
Appendix I: Attributes
----------------------
Attributes are used with wattron(), wattroff(), wattrset(),
or or'ed with the character passed to waddch(). They are
defined in <ncurses.h>
A_ATTRIBUTES mask chtype for attributes
A_NORMAL reset all attributes
A_STANDOUT best highlighting mode
A_UNDERLINE underline
A_REVERSE reverse video, background and foreground reversed
A_BLINK blinking
A_DIM dim or half bright
A_BOLD bold or extra bright
A_ALTCHARSET use alternate character set
A_INVIS invisible, background same as foreground
A_PROTECT I haven't a clue
A_CHARTEXT mask chtype for actual character
A_COLOR mask for color
COLOR_PAIR(n) set color-pair to that stored in n
PAIR_NUMBER(a) get color-pair stored in attribute a
Appendix II: COLORS
-------------------
Colors are defined in <ncurses.h> are used with init_pair().
COLOR_BLACK 0
COLOR_RED 1
COLOR_GREEN 2
COLOR_YELLOW 3
COLOR_BLUE 4
COLOR_MAGENTA 5
COLOR_CYAN 6
COLOR_WHITE 7
Appendix III: Alternative character sets
----------------------------------------
ACS variables are used to add line-drawing capability to
ncurses on terminals that support it. When defined for a
given terminal (using acs) the A_ALTCHARSET attribute is
set for that variable, otherwise the default value is
used.
ACS_ULCORNER +
ACS_LLCORNER +
ACS_URCORNER +
ACS_LRCORNER +
ACS_RTEE +
ACS_LTEE +
ACS_BTEE +
ACS_TTEE +
ACS_HLINE -
ACS_VLINE |
ACS_PLUS +
ACS_S1 ~ /* scan line 1 */
ACS_S9 _ /* scan line 9 */
ACS_DIAMOND + /* diamond */
ACS_CKBOARD : /* checker board (stipple) */
ACS_DEGREE ' /* degree symbol */
ACS_PLMINUS # /* plus/minus */
ACS_BULLET 0 /* bullet */
ACS_LARROW < /* arrow pointing left */
ACS_RARROW > /* arrow pointing right */
ACS_DARROW v /* arrow pointing down */
ACS_UARROW ^ /* arrow pointing up */
ACS_BOARD # /* board of squares */
ACS_LANTERN # /* lantern symbol */
ACS_BLOCK # /* solid square block */
Appendix IV: Function keys, their codes, and their definition
-------------------------------------------------------------
Function keys can return their respective codes if keypad()
is enabled and they are defined in the terminal's terminfo
description (assuming the terminal transmits unique sequences
for the key. They are defined in <ncurses.h>
KEY_BREAK 0401 /* break key (unreliable) */
KEY_DOWN 0402 /* The four arrow keys ... */
KEY_UP 0403
KEY_LEFT 0404
KEY_RIGHT 0405 /* ... */
KEY_HOME 0406 /* Home key (upward+left arrow) */
KEY_BACKSPACE 0407 /* backspace (unreliable) */
KEY_F0 0410 /* Function keys. Space for 64 */
KEY_F(n) (KEY_F0+(n)) /* keys is reserved. */
KEY_DL 0510 /* Delete line */
KEY_IL 0511 /* Insert line */
KEY_DC 0512 /* Delete character */
KEY_IC 0513 /* Insert char or enter insert mode */
KEY_EIC 0514 /* Exit insert char mode */
KEY_CLEAR 0515 /* Clear screen */
KEY_EOS 0516 /* Clear to end of screen */
KEY_EOL 0517 /* Clear to end of line */
KEY_SF 0520 /* Scroll 1 line forward */
KEY_SR 0521 /* Scroll 1 line backwards (reverse) */
KEY_NPAGE 0522 /* Next page */
KEY_PPAGE 0523 /* Previous page */
KEY_STAB 0524 /* Set tab */
KEY_CTAB 0525 /* Clear tab */
KEY_CATAB 0526 /* Clear all tabs */
KEY_ENTER 0527 /* Enter or send (unreliable) */
KEY_SRESET 0530 /* soft (partial) reset (unreliable) */
KEY_RESET 0531 /* reset or hard reset (unreliable) */
KEY_PRINT 0532 /* print or copy */
KEY_LL 0533 /* home down or bottom (lower left) */
/* The keypad is arranged like this: */
/* a1 up a3 */
/* left b2 right */
/* c1 down c3 */
KEY_A1 0534 /* Upper left of keypad */
KEY_A3 0535 /* Upper right of keypad */
KEY_B2 0536 /* Center of keypad */
KEY_C1 0537 /* Lower left of keypad */
KEY_C3 0540 /* Lower right of keypad */
KEY_BTAB 0541 /* Back tab key */
KEY_BEG 0542 /* beg(inning) key */
KEY_CANCEL 0543 /* cancel key */
KEY_CLOSE 0544 /* close key */
KEY_COMMAND 0545 /* cmd (command) key */
KEY_COPY 0546 /* copy key */
KEY_CREATE 0547 /* create key */
KEY_END 0550 /* end key */
KEY_EXIT 0551 /* exit key */
KEY_FIND 0552 /* find key */
KEY_HELP 0553 /* help key */
KEY_MARK 0554 /* mark key */
KEY_MESSAGE 0555 /* message key */
KEY_MOVE 0556 /* move key */
KEY_NEXT 0557 /* next object key */
KEY_OPEN 0560 /* open key */
KEY_OPTIONS 0561 /* options key */
KEY_PREVIOUS 0562 /* previous object key */
KEY_REDO 0563 /* redo key */
KEY_REFERENCE 0564 /* ref(erence) key */
KEY_REFRESH 0565 /* refresh key */
KEY_REPLACE 0566 /* replace key */
KEY_RESTART 0567 /* restart key */
KEY_RESUME 0570 /* resume key */
KEY_SAVE 0571 /* save key */
KEY_SBEG 0572 /* shifted beginning key */
KEY_SCANCEL 0573 /* shifted cancel key */
KEY_SCOMMAND 0574 /* shifted command key */
KEY_SCOPY 0575 /* shifted copy key */
KEY_SCREATE 0576 /* shifted create key */
KEY_SDC 0577 /* shifted delete char key */
KEY_SDL 0600 /* shifted delete line key */
KEY_SELECT 0601 /* select key */
KEY_SEND 0602 /* shifted end key */
KEY_SEOL 0603 /* shifted clear line key */
KEY_SEXIT 0604 /* shifted exit key */
KEY_SFIND 0605 /* shifted find key */
KEY_SHELP 0606 /* shifted help key */
KEY_SHOME 0607 /* shifted home key */
KEY_SIC 0610 /* shifted input key */
KEY_SLEFT 0611 /* shifted left arrow key */
KEY_SMESSAGE 0612 /* shifted message key */
KEY_SMOVE 0613 /* shifted move key */
KEY_SNEXT 0614 /* shifted next key */
KEY_SOPTIONS 0615 /* shifted options key */
KEY_SPREVIOUS 0616 /* shifted prev key */
KEY_SPRINT 0617 /* shifted print key */
KEY_SREDO 0620 /* shifted redo key */
KEY_SREPLACE 0621 /* shifted replace key */
KEY_SRIGHT 0622 /* shifted right arrow */
KEY_SRSUME 0623 /* shifted resume key */
KEY_SSAVE 0624 /* shifted save key */
KEY_SSUSPEND 0625 /* shifted suspend key */
KEY_SUNDO 0626 /* shifted undo key */
KEY_SUSPEND 0627 /* suspend key */
KEY_UNDO 0630 /* undo key */
KEY_MAX 0777 /* Maximum curses key */
Reference in New Issue View Git Blame Copy Permalink