1362 lines
53 KiB
Plaintext
1362 lines
53 KiB
Plaintext
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 */
|
|
|