Manual page for CURSES(3V)
curses - System V terminal screen handling and optimization package
SYNOPSIS
The
curses
manual page is organized as follows:
In
SYNOPSIS
-
- compiling information
- summary of parameters used by
curses
routines
In
SYSTEM V SYNOPSIS:
-
In
DESCRIPTION
and
SYSTEM V DESCRIPTION:
-
- An overview of how
curses
routines should be used
In
ROUTINES,
descriptions of
curses
routines are grouped under the appropriate topics:
-
- Overall Screen Manipulation
- Window and Pad Manipulation
- Output
- Input
- Output Options Setting
- Input Options Setting
- Environment Queries
- Low-level Curses Access
- Miscellaneous
- Use of
curscr
In
SYSTEM V ROUTINES,
descriptions of
curses
routines are grouped under the appropriate topics:
-
- Overall Screen Manipulation
- Window and Pad Manipulation
- Output
- Input
- Output Options Setting
- Input Options Setting
- Environment Queries
- Soft Labels
- Low-level Curses Access
- Terminfo-Level Manipulations
- Termcap Emulation
- Miscellaneous
- Use of
curscr
Then come sections on:
-
- SYSTEM V ATTRIBUTES
- SYSTEM V FUNCTION KEYS
- LINE GRAPHICS
cc
[
flags
]
files
-lcurses -ltermcap
[
libraries
]
- #include <curses.h>
-
(automatically includes
<stdio.h>
and
<unctl.h>.)
The parameters in the following list are not global
variables. This is a summary of the parameters used by the
curses
library routines.
All routines return the
int
values
ERR
or
OK
unless otherwise noted.
Routines that return pointers always return
NULL
on error.
ERR,
OK ,
and
NULL
are all defined in
<curses.h>.)
Routines that return
integers are not listed in the parameter list below.
bool bf
char **area,*boolnames[], *boolcodes[], *boolfnames[], *bp
char *cap, *capname, codename[2], erasechar, *filename, *fmt
char *keyname, killchar, *label, *longname
char *name, *numnames[], *numcodes[], *numfnames[]
char *slk_label, *str, *strnames[], *strcodes[], *strfnames[]
char *term, *tgetstr, *tigetstr, *tgoto, *tparm, *type
chtype attrs, ch, horch, vertch
FILE *infd, *outfd
int begin_x, begin_y, begline, bot, c, col, count
int dmaxcol, dmaxrow, dmincol, dminrow, *errret, fildes
int (*init()), labfmt, labnum, line
int ms, ncols, new, newcol, newrow, nlines, numlines
int oldcol, oldrow, overlay
int p1, p2, p9, pmincol, pminrow, (*putc()), row
int smaxcol, smaxrow, smincol, sminrow, start
int tenths, top, visibility, x, y
SCREEN *new, *newterm, *set_term
TERMINAL *cur_term, *nterm, *oterm
va_list varglist
WINDOW *curscr, *dstwin, *initscr, *newpad, *newwin, *orig
WINDOW *pad, *srcwin, *stdscr, *subpad, *subwin, *win
SYSTEM V SYNOPSIS
/usr/5bin/cc
[
flag
...]
file
...
-lcurses
[
library
...]
- #include <curses.h>
-
(automatically includes
<stdio.h>,
<termio.h>,
and
<unctrl.h>).
DESCRIPTION
These routines give the user a method of updating screens with reasonable
optimization. They keep an image of the current screen,
and the user sets up an image of a new one. Then the
refresh()
tells the routines to make the current screen look like the new one.
In order to initialize the routines, the routine
initscr()
must be called before any of the other routines that deal with windows and
screens are used. The routine
endwin()
should be called before exiting.
SYSTEM V DESCRIPTION
The
curses
routines give the user
a terminal-independent method of updating screens with reasonable
optimization.
In order to initialize the routines, the routine
initscr()
or
newterm()
must be called before any of the other routines that deal with windows and
screens are used.
Three exceptions are noted where they apply.
The routine
endwin()
must be called before exiting.
To get character-at-a-time input without echoing, (most interactive, screen
oriented programs want this) after calling
initscr()
you should call
`cbreak (); noecho ();'
Most programs would additionally call
`nonl ();
intrflush(stdscr, FALSE); keypad(stdscr, TRUE);'.
Before a
curses
program is run, a terminal's
TAB
stops should be set and its initialization
strings, if defined, must be output.
This can be done by executing the
tset
command in your
.profile
or
.login
file.
For further details, see
tset.1
and the
Tabs and Initialization
subsection of
terminfo.5v
The
curses
library contains routines that
manipulate data structures called
windows
that can be thought of as two-dimensional arrays of characters
representing all or part of a terminal screen.
A default window called
stdscr
is supplied, which is the size of the terminal screen.
Others may be created with
newwin().
Windows are referred to by variables declared as
WINDOW *;
the type
WINDOW
is defined in
<curses.h>
to be a C structure.
These data structures are manipulated with routines described below, among
which the most basic are
move()
and
addch().
More general versions of these routines are included with names
beginning with
w,
allowing you to specify a window.
The routines not beginning with
w
usually affect
stdscr.
Then
refresh()
is called, telling the routines to make the user's terminal screen look like
stdscr.
The characters in a window are actually of type
chtype,
so that other information about the character may also be stored with each
character.
Special windows called
pads
may also be manipulated.
These are windows that are not constrained to the size of the screen and
whose contents need not be displayed completely.
See the description of
newpad()
under
Window and Pad Manipulation
for more information.
In addition to drawing characters on the screen, video attributes may be
included that cause the characters to show up in modes such as
underlined or in reverse video on terminals that support such display
enhancements.
Line drawing characters may be specified to be output.
On input,
curses
is also able to translate arrow and function keys that
transmit escape sequences into single values.
The video attributes, line drawing characters, and input values use names,
defined in
<curses.h>,
such as
A_REVERSE,
ACS_HLINE,
and
KEY_LEFT.
curses
also defines the
WINDOW *
variable,
curscr,
which is used only for certain low-level operations like clearing
and redrawing a garbaged screen.
curscr
can be used in only a few routines.
If the window argument to
clearok()
is
curscr,
the next call to
wrefresh()
with any window will clear and repaint the screen from scratch.
If the window argument to
wrefresh()
is
curscr,
the screen in immediately cleared and
repainted from scratch.
This is how most programs would implement
a ``repaint-screen'' function.
More information on using
curscr
is provided where its use is appropriate.
The environment variables
LINES
and
COLUMNS
may be set to override
curses's
idea of how large a screen is.
If the environment variable
TERMINFO
is defined, any program using
curses
will check for a local terminal definition before
checking in the standard place.
For example, if the environment variable
TERM
is set to
sun,
then the compiled terminal definition is found in
/usr/share/lib/terminfo/s/sun.
The
s
is copied from the first letter of
sun
to avoid creation of huge directories.)
However, if
TERMINFO
is set to
$HOME/myterms,
curses
will first check
$HOME/myterms/s/sun,
and, if that fails, will then check
/usr/share/lib/terminfo/s/sun.
This is useful for developing experimental
definitions or when write permission on
/usr/share/lib/terminfo
is not available.
The integer variables
LINES
and
COLS
are defined in
<curses.h>,
and will be filled in by
initscr()
with the size of the screen.
For more information, see the subsection
Terminfo-Level Manipulations.
The constants
TRUE
and
FALSE
have the values
1
and
0,
respectively.
The constants
ERR
and
OK
are returned by routines to indicate whether the routine successfully
completed.
These constants are also defined in
<curses.h>.
ROUTINES
Many of the following routines have two or more versions.
The routines prefixed with
w
require a
window
argument.
The routines prefixed with
p
require a
pad
argument.
Those without a prefix generally use
stdscr.
The routines prefixed with
mv
require
y
and
x
coordinates to move to before performing the appropriate action.
The
mv
routines imply a call to
move()
before the call to the other routine.
The window argument is always specified before
the coordinates.
y
always refers to the row
(of the window), and
x
always refers to the column.
The upper left corner is always
(0,0),
not
(1,1).
The routines prefixed with
mvw
take both a
window
argument and
y
and
x
coordinates.
In each case,
win
is the window affected and
pad
is the pad affected.
(win
and
pad
are always of type
WINDOW *.)
Option-setting routines require a boolean flag
bf
with the value
TRUE
or
FALSE.
(bf
is always of type
bool.)
The types
WINDOW,
bool,
and
chtype
are defined in
<curses.h>
(see
SYNOPSIS
for a summary of what types all variables are).
All routines return either the integer
ERR
or the integer
OK,
unless otherwise noted.
Routines that return pointers always return
NULL
on error.
Overall Screen Manipulation
- WINDOW *initscr()
-
The first routine called should almost always be
initscr().
The exceptions are
slk_init(),
filter(),
and
ripoffline().
This will determine the terminal type and initialize all
curses
data structures.
initscr()
also arranges that the first call to
refresh()
will clear the screen.
If errors occur,
initscr()
will write an appropriate error message to
standard error and exit;
otherwise, a pointer to
stdscr
is returned.
If the program wants an indication of error conditions,
newterm()
should be used instead of
initscr().
initscr()
should only be called once per application.
- endwin()
-
A program should always call
endwin()
before exiting or escaping from
curses
mode temporarily, to do a
shell escape or
system.3
call, for example.
This routine will restore
termio.4
modes, move the cursor to the lower left
corner of the screen and reset the terminal into the proper non-visual mode.
To resume after a temporary escape,
call
wrefresh()
or
doupdate().
Window and Pad Manipulation
- refresh()
-
- wrefresh (win)
-
These routines
(or
prefresh(),
pnoutrefresh(),
wnoutrefresh(),
or
doupdate())
must be called to write output to the terminal,
as most other routines merely manipulate data structures.
wrefresh()
copies the named window to the physical terminal screen,
taking into account what is already there in order
to minimize the amount of information that's
sent to the terminal (called optimization).
refresh()
does the same thing, except it uses
stdscr
as a default window.
Unless
leaveok()
has been enabled, the physical cursor of the terminal is left at the location
of the window's cursor.
The number of characters output to the terminal
is returned.
Note:
refresh()
is a macro.
- WINDOW *newwin (nlines, ncols, begin_y, begin_x)
-
Create and return a pointer to
a new window with the given number of lines (or rows),
nlines,
and columns,
ncols.
The upper left corner of the window is at line
begin_y,
column
begin_x.
If either
nlines
or
ncols
is
0,
they will be set to the value of
lines-begin_y
and
cols-begin_x.
A new full-screen window is created by calling
newwin(0,0,0,0).
- mvwin (win, y, x)
-
Move the window so that the upper left corner will be at position
(y, x).
If the move would cause the window to be off the screen, it is an error and
the window is not moved.
- WINDOW *subwin (orig, nlines, ncols, begin_y, begin_x)
-
Create and return a pointer to
a new window with the given number of lines (or rows),
nlines,
and columns,
ncols.
The window is at position
( begin_y, begin_x)
on the screen.
This position is relative to the screen, and not to the window
orig.
The window is made in the middle of the window
orig,
so that changes made to one window will affect both windows.
When using this routine, often it will be necessary to call
touchwin()
or
touchline()
on
orig
before calling
wrefresh.
- delwin (win)
-
Delete the named window, freeing up all memory associated with it.
In the case of overlapping windows, subwindows should be deleted before the
main window.
Output
These routines are used to ``draw'' text on windows.
- addch (ch)
-
- waddch (win, ch)
-
- mvaddch (y, x, ch)
-
- mvwaddch (win, y, x, ch)
-
The character
ch
is put into the window at the current cursor position of the window and
the position of the window cursor is advanced.
Its function is similar to that of
putchar()
(see
putc.3s
At the right margin, an automatic newline is performed.
At the bottom of the scrolling region,
if
scrollok()
is enabled, the scrolling region will be scrolled up one line.
If
ch
is a
TAB,
NEWLINE,
or backspace, the cursor will be moved appropriately
within the window.
A
NEWLINE
also does a
clrtoeol()
before moving.
TAB
characters are considered to be at every eighth column.
If
ch
is another control character, it will be drawn in the
CTRL-X
notation. (Calling
winch()
after adding a control character will not return the control character, but
instead will return the representation of the control character.)
Video attributes can be combined with a character by or-ing them
into the parameter.
This will result in these attributes also being set.
The intent here is that text, including attributes, can be
copied from one place to another using
inch()
and
addch().
See
standout(),
below.
Note:
ch
is actually of type
chtype,
not a character.
Note:
addch(),
mvaddch(),
and
mvwaddch()
are macros.
- addstr (str)
-
- waddstr (win, str)
-
- mvwaddstr (win, y, x, str)
-
- mvaddstr (y, x, str)
-
These routines write all the characters of the null-terminated character
string
str
on the given window.
This is equivalent to calling
waddch()
once for each character in the string.
Note:
addstr(),
mvaddstr(),
and
mvwaddstr()
are macros.
- box (win, vertch, horch)
-
A box is drawn around the edge of the window,
win.
vertch
and
horch
are the characters the box is to be drawn with.
If
vertch
and
horch
are
0,
then appropriate default characters,
ACS_VLINE
and
ACS_HLINE,
will be used.
Note:
vertch
and
horch
are actually of type
chtype,
not characters.
- erase()
-
- werase (win)
-
These routines copy blanks to every position in the window.
Note:
erase()
is a macro.
- clear()
-
- wclear (win)
-
These routines are like
erase()
and
werase(),
but they also call
clearok(),
arranging that the screen will be cleared completely on the next call to
wrefresh()
for that window, and repainted from scratch.
Note:
clear()
is a macro.
- clrtobot()
-
- wclrtobot (win)
-
All lines below the cursor in this window are erased.
Also, the current line to the right of the cursor, inclusive, is erased.
Note:
clrtobot()
is a macro.
- clrtoeol()
-
- wclrtoeol (win)
-
The current line to the right of the cursor, inclusive, is erased.
Note:
clrtoeol()
is a macro.
- 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 and the last character on the line is filled with a blank.
The cursor position does not change (after moving to
(y, x),
if specified).
This does not imply use of the hardware ``delete-character'' feature.
Note:
delch(),
mvdelch(),
and
mvwdelch()
are macros.
- 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.
The cursor position does not change.
This does not imply use of the hardware ``delete-line'' feature.
Note:
deleteln()
is a macro.
- getyx (win, y, x)
-
The cursor position of the window is placed in the two integer variables
y
and
x.
This is implemented as a macro, so no
`&'
is necessary before the variables.
- insch (ch)
-
- winsch (win, ch)
-
- mvwinsch (win, y, x, ch)
-
- mvinsch (y, x, ch)
-
The character
ch
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 of the line.
The cursor position does not change (after moving to
(y, x),
if specified).
This does not imply use of the hardware ``insert-character'' feature.
Note:
ch
is actually of type
chtype,
not a character.
Note:
insch(),
mvinsch(),
and
mvwinsch()
are macros.
- insertln()
-
- winsertln (win)
-
A blank line is inserted above the current line and the bottom line is lost.
This does not imply use of the hardware ``insert-line'' feature.
Note:
insertln()
is a macro.
- move (y, x)
-
- wmove (win, y, x)
-
The cursor associated with the window is moved to
line (row)
y,
column
x.
This does not move the physical cursor of the terminal until
refresh()
is called.
The position specified is relative to the upper left corner of the window,
which is
(0, 0).
Note:
move()
is a macro.
- overlay (srcwin, dstwin)
-
- overwrite (srcwin, dstwin)
-
These routines overlay
srcwin
on top of
dstwin;
that is, all text in
srcwin
is copied into
dstwin.
scrwin
and
dstwin
need not be the same size;
only text where the two windows overlap is copied.
The difference is that
overlay()
is non-destructive (blanks are not copied), while
overwrite()
is destructive.
- printw (fmt [, arg...])
-
- wprintw (win, fmt [, arg...])
-
- mvprintw (y, x, fmt [, arg...])
-
- mvwprintw (win, y, x, fmt [, arg...])
-
These routines are analogous to
printf.3v
The string that would be output by
printf.3v
is instead output using
waddstr()
on the given window.
- scroll (win)
-
The window is scrolled up one line.
This involves moving the lines in the window data structure.
As an optimization, if the window is
stdscr
and the scrolling region is the entire window,
the physical screen will be scrolled at the same time.
- touchwin (win)
-
- touchline (win, start, count)
-
Throw away all optimization information about which parts of the window have
been touched, by pretending that the entire window has been drawn on.
This is sometimes necessary when using overlapping windows, since a change to
one window will affect the other window, but the records of which lines have
been changed in the other window will not reflect the change.
touchline()
only pretends that
count
lines have been changed, beginning with line
start.
Input
- 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
ERR
is returned.
In
DELAY
mode,
the program will hang until the system passes text through to
the program.
Depending on the setting of
cbreak(),
this will be after one character (CBREAK mode),
or after the first newline (NOCBREAK mode).
In
HALF-DELAY
mode, the program will hang until a character is typed or the
specified timeout has been reached.
Unless
noecho()
has been set,
the character will also be echoed into the designated window.
No
refresh()
will occur between the
move()
and the
getch()
done within the routines
mvgetch()
and
mvwgetch().
When using
getch(),
wgetch(),
mvgetch(),
or
mvwgetch(),
do not set both
NOCBREAK
mode
(nocbreak())
and
ECHO
mode
(echo())
at the same time.
Depending on the state of the terminal
driver when each character is typed,
the program may produce undesirable results.
If
keypad (win, TRUE)
has been called,
and a function key is pressed, the token for that function
key will be returned instead of the raw characters.
See
keypad()
under
Input Options Setting.
Possible function keys are defined in
<curses.h>
with integers beginning with
0401,
whose names begin with
KEY_.
If a character is received that could be the beginning of a function key
(such as escape),
curses
will set a timer.
If the remainder of the sequence is not received within the designated time,
the character will be passed through,
otherwise the function key value will be returned.
For this reason, on many terminals, there will be a delay after a
user presses the escape key before the escape is returned to the program.
Use by a programmer of the escape key for a single character routine is
discouraged.
Also see
notimeout()
below.
Note:
getch(),
mvgetch(),
and
mvwgetch()
are macros.
- 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, carriage return, or enter key is received.
The resulting value is placed in the area pointed at by the character pointer
str.
The user's erase and kill characters are interpreted.
As in
mvgetch(),
no
refresh()
is done between the
move()
and
getstr()
within the routines
mvgetstr()
and
mvwgetstr().
Note:
getstr(),
mvgetstr(),
and
mvwgetstr()
are macros.
- inch()
-
- winch (win)
-
- mvinch (y, x)
-
- mvwinch (win, y, x)
-
The character, of type
chtype,
at the current position in the named window is returned.
If any attributes are set for that position, their values will be OR'ed into
the value returned.
The predefined constants
A_CHARTEXT
and
A_ATTRIBUTES,
defined in
<curses.h>,
can be used with the C logical
AND
(&) operator to extract the character or
attributes alone.
Note:
inch(),
winch(),
mvinch(),
and
mvwinch()
are macros.
- scanw (fmt[,arg...]")
-
- wscanw (win, fmt [, arg...])
-
- mvscanw (y, x, fmt [, arg...])
-
- mvwscanw (win, y, x, fmt [, arg...])
-
These routines correspond to
scanf.3v
as do their arguments and return values.
wgetstr()
is called on the window,
and the resulting line is used as input for the scan.
Output Options Setting
These routines set options within
curses
that deal with output.
All options are initially
FALSE,
unless otherwise stated.
It is not necessary to turn these options off before calling
endwin().
- clearok (win, bf)
-
If enabled
(bf
is
TRUE),
the next call to
wrefresh()
with this window will clear the screen completely and redraw the entire
screen from scratch.
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
(bf
is
TRUE),
curses
will consider using the hardware ``insert/delete-line''
feature of terminals so equipped.
If disabled
(bf
is
FALSE),
curses
will very seldom use this feature.
The ``insert/delete-character'' feature is always considered.
This option should be enabled
only if your application needs ``insert/delete-line'', for
example, for a screen editor.
It is disabled by default because ``insert/delete-line'' tends to be visually
annoying when used in applications where it is not really needed.
If ``insert/delete-line'' cannot be used,
curses
will redraw the changed portions
of all lines.
- leaveok (win, bf)
-
Normally, the hardware cursor is left at the location of the window cursor
being refreshed.
This option allows the cursor to be left
wherever the update happens to leave
it.
It is useful for applications where the cursor is not used, since it reduces
the need for cursor motions.
If possible, the cursor is made invisible when this option is enabled.
- scrollok (win, bf)
-
This option controls what happens when the cursor of a window is moved off
the edge of the window or scrolling region, either from a newline on the
bottom line, or typing the last character of the last line.
If disabled
(bf
is
FALSE),
the cursor is left on the bottom line
at the location where the offending
character was entered.
If enabled
(bf
is
TRUE),
wrefresh()
is called on the window,
and then the physical terminal and window are scrolled up one line.
Note: in order to get the physical scrolling effect on the terminal,
it is also necessary to call
idlok().
- nl()
-
- nonl()
-
These routines control whether
NEWLINE
is translated into
RETURN
and
LINEFEED
on output, and whether
RETURN
is translated into
NEWLINE
on input.
Initially, the translations do occur.
By disabling these translations using
nonl(),
curses
is able to make better use of the
linefeed capability, resulting in faster cursor motion.
Input Options Setting
These routines set options within
curses
that deal with input.
The options involve using
ioctl.2
and therefore interact with
curses
routines.
It is not necessary to turn these options off
before calling
endwin().
For more information on these options,
refer to
[a manual with the abbreviation PUL].
- cbreak()
-
- nocbreak()
-
These two routines put the terminal into and out of
CBREAK
mode, respectively.
In
CBREAK
mode, characters typed by the user are immediately available to the
program and erase/kill character processing is not performed.
When in
NOCBREAK
mode, the tty driver will buffer characters typed until a
NEWLINE
or
RETURN
is typed.
Interrupt and flow-control characters are unaffected by this mode
(see
termio.4
Initially the terminal may or may not be in
CBREAK
mode, as it is inherited, therefore, a program should call
cbreak()
or
nocbreak()
explicitly.
Most interactive programs using
curses
will set
CBREAK
mode.
Note:
cbreak()
overrides
raw().
See
getch()
under
Input
for a discussion of how these routines interact with
echo()
and
noecho().
- echo()
-
- noecho()
-
These routines control whether characters typed by the user are echoed by
getch()
as they are typed.
Echoing by the tty driver is always disabled,
but initially
getch()
is in
ECHO
mode, so characters typed are echoed.
Authors of most interactive programs prefer to do their own echoing in a
controlled area of the screen, or not to echo at all, so they disable echoing
by calling
noecho().
See
getch()
under
Input
for a discussion
of how these routines interact with
cbreak()
and
nocbreak().
- raw()
-
- noraw()
-
The terminal is placed into or out of
RAW
mode.
RAW
mode is similar to
CBREAK
mode,
in that characters typed are immediately
passed through to the user program.
The differences are that in
RAW
mode, the interrupt, quit, suspend, and flow
control characters are passed through uninterpreted, instead of generating a
signal.
RAW
mode also causes 8-bit input and output.
The behavior of the
BREAK
key depends on other bits in the terminal driver that
are not set by
curses.
Environment Queries
- baudrate()
-
Returns the output speed of the terminal.
The number returned is
in bits per second,
for example, 9600,
and is an integer.
- char erasechar()
-
The user's current erase character is returned.
- char killchar()
-
The user's current line-kill character is returned.
- char *longname()
-
This routine returns a pointer to a static area containing
a verbose description of the current terminal.
The maximum length of a verbose description is 128
characters.
It is defined only after the call to
initscr()
or
newterm().
The area is overwritten by each call to
newterm()
and is not restored by
set_term(),
so the value should be saved between calls to
newterm()
if
longname()
is going to be used with multiple terminals.
Low-Level curses Access
The following routines give low-level access to various
curses
functionality.
These routines typically would be used inside of library routines.
- resetty()
-
- savetty()
-
These routines save and restore the state of the terminal modes.
savetty()
saves the current state of the terminal in a buffer and
resetty()
restores the state to what it was at the last call to
savetty().
Miscellaneous
- unctrl (c)
-
This macro expands to a character string which is a printable
representation of the character
c.
Control characters are displayed in the ^X notation.
Printing characters are displayed as is.
unctrl()
is a macro, defined in
<unctrl.h>,
which is automatically included by
<curses.h>.
- flusok(win,boolf)
-
set flush-on-refresh flag for
win
- getcap(name)
-
get terminal capability
name
- touchoverlap(win1,win2)
-
mark overlap of
win1
on
win2
as changed
Use of curscr
The special window
curscr
can be used in only a few routines.
If the window argument to
clearok()
is
curscr,
the next call to
wrefresh()
with any window will cause the screen to be cleared and repainted from
scratch.
If the window argument to
wrefresh()
is
curscr,
the screen is immediately cleared and repainted from scratch.
This is how most programs would implement a ``repaint-screen'' routine.
The source window argument to
overlay(),
overwrite(),
and
copywin
may be
curscr,
in which case the current contents of the virtual terminal
screen will be accessed.
Obsolete Calls
Various routines are provided to maintain compatibility in programs written
for older versions of the curses library.
These routines are all emulated as indicated below.
- crmode()
-
Replaced by
cbreak().
- gettmode()
-
A no-op.
- nocrmode()
-
Replaced by
nocbreak().
SYSTEM V ROUTINES
The above routines are available as described except for
flusok(),
getcap()
and
touchoverlap()
which are not available.
In addition, the following routines are available:
Overall Screen Manipulation
- isendwin()
-
Returns
TRUE
if
endwin()
has been called without
any subsequent calls to
wrefresh().
- SCREEN *newterm(type, outfd, infd)
-
A program that outputs to more than one terminal must use
newterm()
for each terminal instead of
initscr().
A program that wants an indication of error conditions, so that it may
continue to run in a line-oriented mode if the terminal cannot support a
screen-oriented program, must also use this routine.
newterm()
should be called once for each terminal.
It returns a variable of type
SCREEN*
that should be saved as a reference to that terminal.
The arguments are the
type
of the terminal to be used in place of
the environment variable
TERM;
outfd,
a
stdio.3v
file pointer for output to the terminal; and
infd,
another file pointer for input from the terminal.
When it is done running, the program must also call
endwin()
for each terminal being used.
If
newterm()
is called more than once
for the same terminal, the first terminal referred to
must be the last one for which
endwin()
is called.
- SCREEN *set_term (new)
-
This routine is used to switch between different terminals.
The screen reference
new
becomes the new current terminal.
A pointer to the screen of
the previous terminal is returned by the routine.
This is the only routine that manipulates
SCREEN
pointers; all other routines affect only the current terminal.
Window and Pad Manipulation
- wnoutrefresh (win)
-
- doupdate()
-
These two routines allow multiple updates
to the physical terminal screen with more efficiency than
wrefresh()
alone.
How this is accomplished is described in the
next paragraph.
curses
keeps two data structures
representing the terminal screen: a
physical
terminal screen, describing what is actually on the screen, and a
virtual
terminal screen, describing what the programmer
wants
to have on the screen.
wrefresh()
works by first calling
wnoutrefresh(),
which copies the named window to the virtual screen, and then by calling
doupdate(),
which compares the virtual screen to the physical screen and does the actual
update.
If the programmer wishes to output several windows at once, a series of calls
to
wrefresh()
will result in alternating calls to
wnoutrefresh()
and
doupdate(),
causing several bursts of output to the screen.
By first calling
wnoutrefresh()
for each window, it is then possible to call
doupdate()
once, resulting in only one burst of output, with probably fewer total
characters transmitted and certainly less processor time used.
- WINDOW *newpad (nlines, ncols)
-
Create and return a pointer to a new pad
data structure with the given number of lines (or rows),
nlines,
and columns,
ncols.
A pad is a window that is not restricted by the screen size
and is not necessarily associated with a particular part of the screen.
Pads can be used when a large window is needed, and only a part of the window
will be on the screen at one time.
Automatic refreshes of pads (for example,
from scrolling or echoing of input) do not occur.
It is not legal to call
wrefresh()
with a pad as an argument; the routines
prefresh()
or
pnoutrefresh()
should be called instead.
Note: these routines require additional parameters to specify the part of
the pad to be displayed and the location on the screen to be used for display.
- WINDOW *subpad (orig, nlines, ncols, begin_y, begin_x)
-
Create and return a pointer to
a subwindow within a pad with the given number of lines (or rows),
nlines,
and columns,
ncols.
Unlike
subwin(),
which uses screen coordinates,
the window is at position
(begin_y, begin_x)
on the pad.
The window is made in the middle of the window
orig,
so that changes made to one window will affect both windows.
When using this routine, often it will be necessary to call
touchwin()
or
touchline()
on
orig
before calling
prefresh().
- prefresh
(pad,
pminrow,
pmincol,
sminrow,
smincol,
smaxrow,
smaxcol)
-
-
pnoutrefresh
(pad,
pminrow,
pmincol,
sminrow,
smincol,
smaxrow,
smaxcol)
-
- These routines are analogous to
-
wrefresh()
and
wnoutrefresh()
except that pads, instead of windows, are involved.
The additional parameters are needed to indicate what part of the pad and
screen are involved.
pminrow
and
pmincol
specify the upper left corner, in the pad, of the rectangle to be displayed.
sminrow,
smincol,
smaxrow,
and
smaxcol
specify the edges, on the screen, of the rectangle to be displayed in.
The lower right corner in the pad of the rectangle to be displayed is
calculated from the screen coordinates, since the rectangles must be the same
size.
Both rectangles must be entirely contained within their respective structures.
Negative values of
pminrow,
pmincol,
sminrow,
or
smincol
are treated as if they were zero.
Output
These routines are used to ``draw'' text on windows.
- echochar (ch)
-
- wechochar (win, ch)
-
- pechochar (pad, ch)
-
These routines are functionally equivalent to a call to
addch (ch)
followed by a call to
refresh(),
a call to
waddch (win, ch)
followed by a call to
wrefresh (win),
or a call to
waddch (pad, ch)
followed by a call to
prefresh (pad).
The knowledge that only a single character is being output is taken into
consideration and, for non-control characters, a considerable performance
gain can be seen by using these routines instead of their equivalents.
In the case of
pechochar(),
the last location of the pad on the screen is reused for the
arguments to
prefresh().
Note:
ch
is actually of type
chtype,
not a character.
Note:
echochar()
is a macro.
- attroff (attrs)
-
- wattroff (win, attrs)
-
- attron (attrs)
-
- wattron (win, attrs)
-
- attrset (attrs)
-
- wattrset (win, attrs)
-
- beep()
-
- flash()
-
These routines are used to signal the terminal user.
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.
- delay_output (ms)
-
Insert a
ms
millisecond pause in the output.
It is not recommended that this routine be used extensively,
because padding characters are used rather than a processor pause.
- getbegyx (win, y, x)
-
- getmaxyx (win, y, x)
-
Like
getyx(),
these routines store the current beginning coordinates and size of the
specified window.
Note:
getbegyx()
and
getmaxyx()
are macros.
- copywin
(srcwin,
dstwin,
sminrow,
smincol,
dminrow,
dmincol,
dmaxrow,
dmaxcol,
overlay)
-
This routine provides a finer grain of control over the
overlay()
and
overwrite()
routines.
Like in the
prefresh()
routine, a rectangle is specified in the destination window,
(dminrow, dmincol)
and
(dmaxrow, dmaxcol),
and the upper-left-corner coordinates of the source window,
(sminrow, smincol).
If the argument
overlay
is true, then copying is non-destructive, as in
overlay().
- vwprintw (win, fmt, varglist)
-
This routine corresponds to
vprintf.3v
It performs a
wprintw()
using a variable argument list.
The third argument is a
va_list,
a pointer to a list of arguments, as defined
in
<varargs.h>.
See the
vprintf.3v
and
varargs.3
manual pages for a detailed description on how to use variable
argument lists.
Input
- flushinp()
-
Throws away any typeahead that has been typed by the user and has not yet
been read by the program.
- ungetch (c)
-
Place
c
back onto the input queue to be returned by the next call to
wgetch().
- vwscanw (win, fmt, ap)
-
This routine is similar to
vwprintw()
above in that performs a
wscanw()
using a variable argument list.
The third argument is a
va_list,
a pointer to a list of arguments, as defined
in
<varargs.h>.
See the
vprintf.3v
and
varargs.3
manual pages for a detailed description on how to use variable
argument lists.
Output Options Setting
These routines set options within
curses
that deal with output.
All options are initially
FALSE,
unless otherwise stated.
It is not necessary to turn these options off before calling
endwin().
- setscrreg (top, bot)
-
- wsetscrreg (win, top, bot)
-
These routines allow the user to set a software scrolling region
in a window.
top
and
bot
are the line numbers of the top and bottom margin of the scrolling region.
Line 0 is the top line of the window.
If this option and
scrollok()
are enabled, an attempt to move off the bottom margin line will cause all
lines in the scrolling region to scroll up one line.
Note: this has nothing to do with use of a physical scrolling region
capability in the terminal, like that in the
DEC VT100.
Only the text of the window is scrolled;
if
idlok()
is enabled and the terminal has either a scrolling region or
``insert/delete-line'' capability,
they will probably be used by the output routines.
Note:
setscrreg()
and
wsetscrreg()
are macros.
Input Options Setting
These routines set options within
curses
that deal with input.
The options involve using
ioctl.2
and therefore interact with
curses
routines.
It is not necessary to turn these options off
before calling
endwin().
For more information on these options,
refer to
[a manual with the abbreviation PUL].
- halfdelay (tenths)
-
Half-delay mode is similar to
CBREAK
mode in that characters typed by the
user are immediately available to the program.
However, after blocking for
tenths
tenths of seconds,
ERR
will be returned if nothing has been typed.
tenths
must be a number between 1 and 255.
Use
nocbreak()
to leave half-delay mode.
- intrflush (win, bf)
-
If this option is enabled, when an interrupt key is pressed on the keyboard
(interrupt, break, quit) all output in the tty driver queue will be flushed,
giving the effect of faster response to the interrupt, but causing
curses
to have the wrong idea of what is on the screen.
Disabling the option prevents the flush.
The default for the option is inherited from the tty driver settings.
The window argument is ignored.
- keypad (win, bf)
-
This option enables the keypad of the user's terminal.
If enabled, the user can press a function key (such as an arrow key) and
wgetch()
will return a single value representing the function key,
as in
KEY_LEFT.
If disabled,
curses
will not treat function keys specially and the program
would have to interpret the escape sequences itself.
If the keypad in the terminal can be turned on (made to transmit) and off
(made to work locally), turning on this option will cause the
terminal keypad to be turned on when
wgetch()
is called.
- meta (win, bf)
-
If enabled, characters returned by
wgetch()
are transmitted with all 8 bits, instead of with the highest bit stripped.
In order for
meta()
to work correctly, the
km
(has_meta_key)
capability has to be specified in the terminal's
terminfo.5v
entry.
- nodelay (win, bf)
-
This option causes
wgetch()
to be a non-blocking call.
If no input is ready,
wgetch()
will return
ERR.
If disabled,
wgetch()
will hang until a key is pressed.
- notimeout (win, bf)
-
While interpreting an input escape sequence,
wgetch()
will set a timer while waiting for the next character.
If
notimeout (win, TRUE)
is called, then
wgetch()
will not set a timer.
The purpose of the timeout is to differentiate between sequences
received from a function key and those typed by a user.
- typeahead (fildes)
-
curses
does ``line-breakout optimization'' by looking for
typeahead periodically while updating the screen.
If input is found, and it is coming from a tty,
the current update will be postponed until
refresh()
or
doupdate()
is called again.
This allows faster response to commands typed in advance.
Normally, the file descriptor for the input
FILE
pointer passed to
newterm(),
or
stdin
in the case that
initscr()
was used, will be used to do this typeahead checking.
The
typeahead()
routine specifies that the file descriptor
fildes
is to be used to check for typeahead instead.
If
fildes
is
-1,
then no typeahead checking will be done.
Note:
fildes
is a file descriptor, not a
<stdio.h>
FILE
pointer.
Environment Queries
- has_ic()
-
True if the terminal has insert- and delete-character capabilities.
- has_il()
-
True if the terminal has insert- and delete-line capabilities, or can
simulate them using scrolling regions.
This might be used to check to see if it would be appropriate to turn on
physical scrolling using
scrollok().
Soft Labels
If desired,
curses
will manipulate the set of soft function-key labels that exist on many
terminals.
For those terminals that do not have soft labels,
if you want to simulate them,
curses
will take over the
bottom line of
stdscr,
reducing the size of
stdscr
and the variable
LINES.
curses
standardizes on 8 labels of 8 characters each.
- slk_init (labfmt)
-
In order to use soft labels,
this routine must be called
before
initscr()
or
newterm()
is called.
If
initscr()
winds up using a line from
stdscr
to emulate the soft labels, then
labfmt
determines how the labels are arranged on the screen.
Setting
labfmt
to
0
indicates that the labels are to be arranged in a
3-2-3
arrangement;
1
asks for a 4-4 arrangement.
- slk_set (labnum, label, labfmt)
-
labnum
is the label number, from 1 to 8.
label
is the string to be put on the label, up to 8 characters in length.
A
null string or a
NULL
pointer will put up a blank label.
labfmt
is one of
0,
1
or
2,
to indicate whether the label is to be left-justified,
centered, or right-justified within the label.
- slk_refresh()
-
- slk_noutrefresh()
-
These routines correspond to the routines
wrefresh()
and
wnoutrefresh().
Most applications would use
slk_noutrefresh()
because a
wrefresh()
will most likely soon follow.
- char *slk_label (labnum)
-
The current label for label number
labnum,
with leading and trailing blanks stripped,
is returned.
- slk_clear()
-
The soft labels are cleared from the screen.
- slk_restore()
-
The soft labels are restored to the screen after a
slk_clear().
- slk_touch()
-
All of the soft labels are forced to be output the next time a
slk_noutrefresh()
is performed.
Low-Level curses Access
The following routines give low-level access to various
curses
functionality.
These routines typically would be used inside of library routines.
- def_prog_mode()
-
- def_shell_mode()
-
Save the current terminal modes as the ``program'' (in
curses)
or ``shell'' (not in
curses)
state
for use by the
reset_prog_mode()
and
reset_shell_mode()
routines.
This is done automatically by
initscr().
- reset_prog_mode()
-
- reset_shell_mode()
-
Restore the terminal to ``program'' (in
curses)
or ``shell'' (out of
curses)
state.
These are done automatically by
endwin()
and
doupdate()
after an
endwin(),
so they normally would not be called.
- getsyx (y, x)
-
The current coordinates of the virtual screen cursor are returned in
y
and
x.
Like
getyx(),
the variables
y
and
x
do not take an
&
before them.
If
leaveok()
is currently
TRUE,
then
-1, -1
will be returned.
If lines may have been removed from the top of the screen using
ripoffline()
and the values are to be used beyond just passing them on to
setsyx(),
the value
y+stdscr->_yoffset
should be used for those other uses.
Note:
getsyx()
is a macro.
- setsyx (y, x)
-
The virtual screen cursor is set to
y, x.
If
y
and
x
are both
-1,
then
leaveok()
will be set.
The two routines
getsyx()
and
setsyx()
are designed to be used by a library routine that manipulates
curses
windows but does not want to mess up the current position of the program's
cursor.
The library routine would call
getsyx()
at the beginning, do its manipulation of its own windows, do a
wnoutrefresh()
on its windows, call
setsyx(),
and then call
doupdate().
- ripoffline (line, init)
-
This routine provides access to the same facility that
slk_init()
uses to reduce the size of the screen.
ripoffline()
must be called
before
initscr()
or
newterm()
is called.
If
line
is positive, a line will be removed from the top of
stdscr;
if negative, a line will be removed from the bottom.
When this is done inside
initscr(),
the routine
init
is called with two arguments:
a window pointer to the 1-line window that has been allocated and
an integer with the number of columns in the window.
Inside this initialization routine,
the integer variables
LINES
and
COLS
(defined in
<curses.h>)
are not guaranteed to be accurate and
wrefresh()
or
doupdate()
must not be called.
It is allowable to call
wnoutrefresh()
during the initialization routine.
ripoffline()
can be called up to five times before calling
initscr()
or
newterm().
- scr_dump (filename)
-
The current contents of the virtual screen are written to the file
filename.
- scr_restore (filename)
-
The virtual screen is set to the contents of
filename,
which must have been written using
scr_dump().
The next call to
doupdate()
will restore the screen to what it looked like in the dump file.
- scr_init (filename)
-
The contents of
filename
are read in and used to initialize the
curses
data structures about what the
terminal currently has on its screen.
If the data is determined to be valid,
curses
will base its next update of
the screen on this information rather than clearing the screen and
starting from scratch.
scr_init()
would be used after
initscr()
or a
system.3
call to share the screen with another process that has done a
scr_dump()
after its
endwin()
call.
The data will be declared invalid if the time-stamp of
the tty is old or the
terminfo.5v
capability
nrrmc
is true.
- curs_set (visibility)
-
The cursor is set to invisible, normal, or very visible for
visibility
equal to
0,
1
or
2.
- draino (ms)
-
Wait until the output has drained enough that it will only take
ms
more milliseconds to drain completely.
- garbagedlines (win, begline, numlines)
-
This routine indicates to
curses
that a screen line is garbaged and
should be thrown away before having anything written over the top of it.
It could be used for programs such as editors that want a command to
redraw just a single line.
Such a command could be used in cases where
there is a noisy communications line
and redrawing the entire screen would be subject
to even more communication noise.
Just redrawing the single line gives some semblance
of hope that it would show up unblemished.
The current location of the window is used to determine which lines are to
be redrawn.
- napms (ms)
-
Sleep for
ms
milliseconds.
Terminfo-Level Manipulations
These low-level routines must be called by
programs that need to deal directly with the
terminfo.5v
database to handle certain terminal capabilities,
such as programming function keys.
For all other functionality,
curses
routines are more suitable and their use is
recommended.
Initially,
setupterm()
should be called.
Note:
setupterm()
is automatically called by
initscr()
and
newterm().
This will define the set of terminal-dependent
variables defined in the
terminfo.5v
database.
The
terminfo.5v
variables
lines
and
columns
(see
terminfo.5v
are initialized by
setupterm()
as follows: if the environment variables
LINES
and
COLUMNS
exist, their values are used.
If the above environment variables
do not exist, and the window sizes in rows and columns as returned by the
TIOCGWINSZ
ioctl
are non-zero, those sizes are used.
Otherwise, the values for
lines
and
columns
specified in the
terminfo.5v
database are used.
The header files
<curses.h>
and
<term.h>
should be included, in this order, to get the definitions
for these strings, numbers, and flags.
Parameterized strings should be passed through
tparm()
to instantiate them.
All
terminfo.5v
strings (including the output of
tparm()
should be printed with
tputs()
or
putp().
Before exiting,
reset_shell_mode()
should be called to restore the tty modes.
Programs that use cursor addressing should
output
enter_ca_mode
upon startup
and should output
exit_ca_mode
before exiting (see
terminfo.5v
Programs desiring shell escapes should call
reset_shell_mode()
and output
exit_ca_mode
before the shell is called and should output
enter_ca_mode
and call
reset_prog_mode()
after returning from the shell.
Note: this is different from the
curses
routines (see
endwin()).
- setupterm (term, fildes, errret)
-
Reads in the
terminfo.5v
database, initializing the
terminfo.5v
structures, but does
not set up the output virtualization structures used by
curses.
The terminal type is in the character string
term;
if
term
is
NULL,
the environment variable
TERM
will be used.
All output is to the file descriptor
fildes.
If
errret
is not
NULL,
then
setupterm()
will return
OK
or
ERR
and store a status value in the integer pointed to by
errret.
A status of
1
in
errret
is normal,
0
means that the terminal could not be found, and
-1
means that the
terminfo.5v
database could not be found.
If
errret
is
NULL,
setupterm()
will print an error message upon finding an error and exit.
Thus, the simplest call is
`setupterm ((char *)0, 1, (int *)0)',
which uses all the defaults.
The
terminfo.5v
boolean, numeric and string variables are
stored in a structure of type
TERMINAL.
After
setupterm()
returns successfully, the variable
cur_term
(of type
TERMINAL *)
is initialized with all of the information that the
terminfo.5v
boolean, numeric and string variables refer to.
The pointer may be saved before calling
setupterm()
again.
Further calls to
setupterm()
will allocate new space rather than reuse the space pointed to by
cur_term.
- set_curterm (nterm)
-
nterm
is of type
TERMINAL * .
set_curterm()
sets the variable
cur_term
to
nterm,
and makes all of the
terminfo.5v
boolean, numeric and string variables use the values from
nterm.
- del_curterm (oterm)
-
oterm
is of type
TERMINAL *.
del_curterm()
frees the space pointed to by
oterm
and makes it available for further use.
If
oterm
is the same as
cur_term,
then references to any of the
terminfo.5v
boolean, numeric and string variables thereafter may refer to invalid memory locations
until another
setupterm()
has been called.
- restartterm (term, fildes, errret)
-
Like
setupterm()
after a memory restore.
- char *tparm (str, p, p, ..., p)
-
Instantiate the string
str
with parms pi.
A pointer is returned to the result of
str
with the parameters applied.
- tputs (str, count, putc)
-
Apply padding to the string
str
and output it.
str
must be a
terminfo.5v
string variable or the return value from
tparm(),
tgetstr(),
tigetstr()
or
tgoto().
count
is the number of lines affected, or
1
if not applicable.
putchar()
is a
putc.3s
routine to which the characters are passed, one at a time.
- putp (str)
-
A routine that calls
tputs()
(str,
1,
putc(3s).
- vidputs (attrs, putc)
-
Output a string that puts the terminal in the video attribute mode
attrs,
which is any combination of the attributes listed below.
The characters are passed to the
putc.3s
routine
putc.3s
- vidattr (attrs)
-
Like
vidputs(),
except that it outputs through
putc.3s
- tigetflag (capname)
-
The value
-1
is returned if
capname
is not a boolean capability.
- tigetnum (capname)
-
The value
-2
is returned if
capname
is not a numeric capability.
- tigetstr (capname)
-
The value
(char *) -1
is returned if
capname
is not a string capability.
Termcap Emulation
These routines are included as a conversion aid for programs that use
the
termcap.3x
library.
Their parameters are the same and the routines are emulated using the
terminfo.5v
database.
- tgetent (bp, name)
-
Look up
termcap
entry for
name.
The emulation ignores the buffer pointer
bp.
- tgetflag (codename)
-
Get the boolean entry for
codename.
- tgetnum (codes)
-
Get numeric entry for
codename.
- char *tgetstr (codename, area)
-
Return the string entry for
codename.
If
area
is not
NULL,
then also store it in the buffer pointed to by
area
and advance
area.
tputs()
should be used to output the returned string.
- char *tgoto (cap, col, row)
-
Instantiate the parameters into the given capability.
The output from this routine is to be passed to
tputs().
- tputs (str, affcnt, putc)
-
See
tputs()
above, under
Terminfo-Level Manipulations.
Miscellaneous
- char *keyname (c)
-
A character string corresponding to the key
c
is returned.
- filter()
-
This routine is one of the few that is to be called
before
initscr()
or
newterm()
is called.
It arranges things so that
curses
thinks that there is a 1-line screen.
curses
will not use any terminal capabilities that assume that they know what
line on the screen the cursor is on.
Use of curscr
The special window
curscr
can be used in only a few routines.
If the window argument to
clearok()
is
curscr,
the next call to
wrefresh()
with any window will cause the screen to be cleared and repainted from
scratch.
If the window argument to
wrefresh()
is
curscr,
the screen is immediately cleared and repainted from scratch.
This is how most programs would implement a ``repaint-screen'' routine.
The source window argument to
overlay(),
overwrite(),
and
copywin
may be
curscr,
in which case the current contents of the virtual terminal
screen will be accessed.
Obsolete Calls
Various routines are provided to maintain compatibility in programs written
for older versions of the curses library.
These routines are all emulated as indicated below.
- crmode()
-
Replaced by
cbreak().
- fixterm()
-
Replaced by
reset_prog_mode().
- nocrmode()
-
Replaced by
nocbreak().
- resetterm()
-
Replaced by
reset_shell_mode().
- saveterm()
-
Replaced by
def_prog_mode().
- setterm()
-
Replaced by
setupterm().
SYSTEM V ATTRIBUTES
The following video attributes,
defined in
<curses.h>,
can be passed to the routines
attron(),
attroff(),
and
attrset(),
or
OR'ed
with the characters passed to
addch().
A_STANDOUT Terminal's best highlighting mode
A_UNDERLINE Underlining
A_REVERSE Reverse video
A_BLINK Blinking
A_DIM Half bright
A_BOLD Extra bright or bold
A_ALTCHARSET Alternate character set
A_CHARTEXT Bit-mask to extract character (described under winch)
A_ATTRIBUTES Bit-mask to extract attributes (described under winch)
A_NORMAL Bit mask to reset all attributes off
(for example: `attrset (A_NORMAL)'
SYSTEM V FUNCTION KEYS
The following function keys,
defined in
<curses.h>,
might be returned by
getch()
if
keypad()
has been enabled.
Note: not all of these may be supported on a particular terminal if the
terminal does not transmit a unique code when the key is pressed or the
definition for the key is not present in the
terminfo.5v
database.
Name Value Key name
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 keys is reserved.
KEY_F(n) (KEY_F0+(n)) Formula for fn.
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 TAB characters
KEY_ENTER 0527 Enter or send
KEY_SRESET 0530 soft (partial) reset
KEY_RESET 0531 reset or hard reset
KEY_PRINT 0532 print or copy
KEY_LL 0533 home down or bottom (lower left)
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
LINE GRAPHICS
The following variables may be used to add line-drawing characters to the
screen with
waddce.
When defined for the terminal, the variable will have the
A_ALTCHARSET
bit turned on.
Otherwise, the default character listed below will be stored in the variable.
The names were chosen to be consistent with the
DEC VT100
nomenclature.
Name Default Glyph Description
ACS_ULCORNER + upper left corner
ACS_LLCORNER + lower left corner
ACS_URCORNER + upper right corner
ACS_LRCORNER + lower right corner
ACS_RTEE + right tee (-|)
ACS_LTEE + left tee (|-)
ACS_BTEE + bottom tee (_|)
ACS_TTEE + top tee (|)
ACS_HLINE - horizontal line
ACS_VLINE | vertical line
ACS_PLUS + 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 o 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
RETURN VALUES
Unless otherwise
noted in the preceding routine descriptions,
all routines
return:
- OK
-
on success.
- ERR
-
on failure.
SYSTEM V RETURN VALUES
All macros return the value of their
w
version, except
setscrreg(),
wsetscrreg(),
getsyx(),
getyx(),
getbegy(),
getmaxyx(),
which return no useful value.
Routines that return pointers always return
(type
*)
NULL
on failure.
FILES
- .login
-
- .profile
-
SYSTEM V FILES
- /usr/share/lib/terminfo
-
SEE ALSO
cc.1v
ld.1
ioctl.2
getenv.3v
plot.3x
printf.3v
putc.3s
scanf.3v
stdio.3v
system.3
varargs.3
vprintf.3v
termio.4
tty.4
term(5V),
termcap.5
terminfo.5v
tic.8v
SYSTEM V WARNINGS
The plotting library
plot.3x
and the curses library
curses.3v
both use the names
erase()
and
move().
The
curses
versions are macros.
If you need both libraries, put the
plot.3x
code in a different source file than the
curses.3v
code, and/or
`#undef move'
and
`#undef erase'
in the
plot.3x
code.
Between the time a call to
initscr()
and
endwin()
has been issued, use only the routines in the
curses
library to generate output.
Using system calls or the ``standard I/O package''
(see
stdio.3v
for output during that time
can cause unpredictable results.
Created by unroff & hp-tools.
© somebody (See intro for details). All Rights Reserved.
Last modified 11/5/97