CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
-------------------------------------------------------------------------------
curses
PURPOSE
Controls cursor movement and windowing.
LIBRARY
Curses Library (libcurses.a)
SYNTAX
#include <curses.h>
#include <term.h>
DESCRIPTION
Note: The curses package of subroutines is included here only for
compatibility with existing programs. For information about the
enhanced screen-handling subroutine library, see "extended curses
library." The system calls curses and extended curses cannot both be
used by the same program.
The curses subroutine package updates the screen with reasonable optimization.
The term.h header file is only needed if terminfo level routines are needed
(see "Terminfo Level Subroutines").
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. To get character-at-a-time
input without echoing, call the nonl, cbreak, and noecho routines. Most
interactive, screen-oriented programs require the character-at-a-time input
without echoing.
The full curses interface permits manipulation of data structures called
windows, which can be thought of as two-dimensional arrays of characters
representing all or part of a screen. Default windows called stdscr and curscr
are supplied, and others can be created with the newwin routine. Windows are
referred to by variables declared WINDOW *. The type WINDOW is defined in
curses.h to be a C structure. These data structures are manipulated with the
routines described below, among which the most basic are move and addch, which
modify stdscr. After manipulating the data structures, the refresh subroutine
is called, which updates the screen to look like stdscr. Routines beginning
with the new definition of w allow window specification. Routines not
beginning with a w affect stdscr. For further information about video mode
support, see "Configuring the Virtual Terminal."
Processed November 7, 1990 CURSES(3x,L) 1
CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
Minicurses is a subset of curses that does not allow manipulation of more than
one window. To invoke this subset, use -DMINICURSES as a cc option. This
level is smaller and faster than the full curses.
If the environment variable TERMINFO is defined, any program using curses
checks for a local terminal definition before checking in /usr/lib/terminfo.
For example, if TERM is set to vt100, the compiled file is normally found in
/usr/lib/terminfo/v/vt100. (The directory name v is copied from the first
letter of vt100 to avoid creating huge directories.) If, for example, TERMINFO
is set to /usr/mark/myterms, curses first checks /usr/mark/myterms/v/vt100. If
this file does not exist, curses then checks /usr/lib/terminfo/v/vt100. This
is useful for developing experimental definitions or when write permission in
/usr/lib/terminfo is not available.
The following parameter names are of the type.
int win, p1, p2, p3;
char *str;
int p1, p2, p3;
Note: The plotting library, plot and the curses library, curses both use the
names erase and move. The curses versions are macros. If you need both
libraries, put the plot code in a different source file than the curses
code, or include the following statements in the plot code:
#undef move()
#undef erase()
ROUTINES
The routines listed here can be called when using the full curses. Those
marked with an asterisk can be called when using minicurses.
Note: In the following routines, flag is a Boolean variable and should have a
value of TRUE or FALSE.
addch(int ch);* Add the character ch to stdscr (like putchar), wrapping to
the next line at the end of a line.
waddch(window *win, int ch);
Add the character ch to win.
mvwaddch(window *w, int y, int x, int ch);
Move cursor position to (y, x) then add the character ch
to win.
addstr(int str);* Call addch with each character in str.
mvaddstr(int y, int x; int str);
Move cursor position to (y, x) then add str.
Processed November 7, 1990 CURSES(3x,L) 2
CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
waddstr(window *win, int str);
Add the string str to win.
mvwaddstr(window *win, int y, int x, int str);
Move cursor position to (y, x) then add the string str to
win.
attroff(int attrs); Turn off the attributes named in attrs.
attron(int attrs); Turn on the attributes named in attrs.
attrset(int attrs); Set current attributes to those specified in attrs.
baudrate ( );* Set current terminal speed.
beep ( );* Sound beep on terminal.
box(window *win, int vert, int hor);
Draw a box around edges of win. The vert and hor
parameters are the characters to use for vertical and
horizontal edges of the box.
cbreak ( );* Set cbreak mode.
nocbreak ( );* Unset cbreak mode.
clear ( ); Clear stdscr.
clearok(window *win, int bf);
Clear screen before next redraw of win.
clrtobot ( ); Clear to bottom of stdscr.
clrtoeol ( ); Clear to end of line on stdscr.
delay_output(int ms);*
Insert ms millisecond pause in output.
nodelay(window *win, int bf);
Enable nodelay input mode through getch.
delch ( ); Delete a character from stdscr.
deleteln ( ); Delete a line from stdscr.
delwin(window *win); Delete window win.
doupdate ( ); Update screen from all wnoutrefresh.
echo ( );* Set echo mode.
Processed November 7, 1990 CURSES(3x,L) 3
CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
noecho ( );* Unset echo mode.
endwin ( );* End window modes.
erase ( ); Erase stdscr.
erasechar ( ); Return user's erase character.
fixterm ( ); Restore terminal to in curses state.
flash ( ); Flash screen or beep.
flushinp ( );* Throw away any type-ahead.
getch ( );* Get a character from tty.
getstr(int *str); Get a string through stdscr.
gettmode ( ); Establish current tty modes.
getyx(window *win, int y, int x);
Get (y, x) coordinates.
has_ic ( ); Returns the value of TRUE if terminal can insert
characters.
has_il ( ); Returns the value of TRUE if terminal can insert lines.
idlok(window *win, int bf);*
Use terminal's insert/delete line if flag!=0.
inch ( ); Get character at current (y, x) coordinates.
initscr ( );* Initialize screens.
insch(c); Insert a character.
insertln ( ); Insert a line.
intrflush(window *win, int bf);*
Interrupt flush output if flag is true.
keypad(WINDOW *win, int flag);*
Enable keypad and function keys.
killchar ( ); Return current user's kill character.
leaveok(window *win, int flag);
Permit cursor to be left anywhere after refresh if FALSE
for win; otherwise cursor must be left at current
position.
Processed November 7, 1990 CURSES(3x,L) 4
CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
longname ( ); Return verbose name of terminal.
meta(window *win, int flag);
Allow metacharacters on input if FALSE.
move(int y, int x); Moves cursor to (y, x) on stdscr.
mvaddch(int y, int x, int ch);
Move cursor position to (y, x) then add ch.
mvcur(int oldrow, int oldcol, int newrow, int newcol);
Move cursor from current position to another position.
mvdelch(int y, int x);
Move cursor position to (y, x) then delete a character.
mvgetch(int y, int x);
Move cursor position to (y, x) then get a character from
tty.
mvgetstr(int y, int x, int str);
Move cursor position to (y, x) then get a string through
stdscr.
mvinch(int y, int x,);
Move cursor position to (y, x) then get the character at
current (y, x) coordinates.
mvinsch(int y, int x, int c);
Move cursor position to (y, x) then insert the character
c.
mvprintw(int y, int x, int fmt, int args);
Move cursor position to (y, x) then get printf on stdscr.
mvscanw(int y, int x, int fmt, int args);
Move cursor position to (y, x) then scan through stdscr.
mvwdelch(window, *win, int y, int x);
Move cursor position to (y, x) then delete a character
from win.
mvwgetch(window *win, int y, int x);
Move cursor position to (y, x) then get a character
through win.
mvwgetstr(window *win, int y, int x, int str);
Move cursor position to (y, x) then get a string through
win.
Processed November 7, 1990 CURSES(3x,L) 5
CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
mvwin(window *win, int by, int bx);
Move win so that the upper left-hand corner is located at
(y, x).
mvwinch(window *win, int y, int x);
Move cursor position to (y, x) then get the character at
current (y, x) in win.
mvwinsch(window *win, int y, int x, int c);
Move cursor position to (y, x) then insert the character c
into win.
mvwprint(window *win, int y, int x, char *fmt, int args);
Move cursor position to (y, x) then printf on stdscr.
mvwscanw(window *win, int y, int x, char *fmt, int args);
Move cursor position to (y, x) then scanf through stdscr.
window * newpad(int nlines, int ncols);
Create a new pad with given dimensions.
struct screen *newterm(char *type, FILE *outfd, FILE *infd);
Set up new terminal of given type to output on fd.
window *newwin(int nlines, int ncols, int by, int bx);
Create a new window.
nl ( )*; Set newline mapping.
nonl ( )*; Unset newline mapping.
overlay(window *win1, window *win2);
Overlay win1 on win2.
overwrite(window *win1, window *win2);
Overwrite win1 on top of win2.
printw(char *fmt, va_dcl);
Printw on stdscr.
raw ( );* Set raw mode.
refresh ( );* Make curscr look like stdscr.
prefresh(window *pad, int pminrow, int pmincol, int sminrow, int smincol, int
smaxrow, int smaxcol);
Refresh from pad starting with given upper left corner of
pad with output to given portion of screen.
pnoutrefresh(WINDOW *pad, int pminrow, int pmincol, int sminrow, int smincol,
int
smaxrow, int smaxcol);
Processed November 7, 1990 CURSES(3x,L) 6
CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
Refresh like prefresh, but with no output until doupdate
is called.
noraw ( );* Unset raw mode.
resetterm ( );* Set tty modes to out of curses state.
resetty ( );* Reset tty flags to stored value.
saveterm ( );* Save current modes as in curses state.
savetty ( );* Store current tty flags.
scanw(char *fmt, va_dcl);
Scanf through stdscr.
scroll(window *win); Scroll win one line.
scrollok(window *win, int bf);
Allow terminal to scroll if flag=FALSE.
set_term(char *type);
Enable talk to terminal new.
setscrreg(int t, int b)
Set user scrolling region to lines short t through short
b.
setterm(char *type); Establish terminal with a given type.
standend ( )* Clear standout mode attribute.
standout ( )* Set standout mode attribute.
subwin(window *orig, int num_lines, int num_cols, int begy, int begx);
Create a subwindow.
touchwin(window *win);
Forces the next call to refresh( ) to write the entire
window.
traceoff ( ) Turn off debugging trace output.
traceon ( ) Turn on debugging trace output.
typeahead(int fd); Check file descriptor fd to check type-ahead.
unctrl(ch)* Use printable version of ch.
wattroff(window *win, int attrs);
Turn off attrs in win.
Processed November 7, 1990 CURSES(3x,L) 7
CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
wattron(WINDOW *win, int attrs);
Turn on attrs in win.
wattrset(window *win, int attrs);
Set attributes in win to attrs.
wclear(WINDOW *win); Clear win.
wclrtobot(WINDOW *win);
Clear to bottom of win.
wclrtoeol(WINDOW *win);
Clear to end of line on win.
wdelch(WINDOW *win); Delete the character at the current cursor coordinates in
win.
wdeleteln(WINDOW *win);
Delete line from win
werase(WINDOW *win); Erase win.
wgetch(WINDOW *win); Get a character through win.
wgetstr(WINDOW *win, char *str);
Get the string str through win.
winch(WINDOW *win); Get the character at current cursor coordinates in win.
winsch(WINDOW *win, chtype c);
Insert the character c into win.
winsertln(WINDOW *win);
Insert line into win.
wmove(WINDOW *win, int y, int x);
Move the cursor to (y, x) coordinates on win.
wnoutrefresh(WINDOW *win);
Refresh but no screen output.
wprintw(WINDOW *win, char *fmt, va_dcl);
printf on win.
wrefresh(WINDOW *win);
Make screen look like win.
wscanw(WINDOW *win, char *fmt, va_dcl);
scanf through win.
Processed November 7, 1990 CURSES(3x,L) 8
CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
wsetscrreg(WINDOW *win, int t, int b);
Set scrolling region of win to lines short t through short
b.
wstandend(WINDOW *win);
Clear standout attribute in win.
wstandout(WINDOW *win);
Set standout attribute in win.
TERMINFO LEVEL SUBROUTINES
These routines should be called by programs that have to deal directly with the
terminfo data base. Due to the low level of this interface, its use is
discouraged. The header files curses.h and term.h should be included (in that
order) to get the definitions for these strings, numbers, and flags. You
should call setupterm before using any of the other terminfo subroutines. This
defines the set of terminal-dependent variables defined in the terminfo file.
If the program needs only one terminal, you can specify the -DSINGLE flag to
the C compiler. This results in static references instead of dynamic
references to capabilities. The result is smaller code, but only one terminal
can be used at a time for the program.
Capabilities with a Boolean value have the value 1 if the capability is present
and 0 if it is not. Numeric capabilities have a value of -1 if the capability
is missing and a value of 0 or greater if it is present. String capabilities
have a NULL value if the capability is missing and otherwise have type char *
and point to a character string that contains the capability. Special
character codes that use the backslash and circumflex characters (\ and ^) are
transformed into the appropriate ASCII characters. Padding information of the
form $<time>, and parameter information beginning with % (percent) are left
uninterpreted. The tputs routine interprets padding information and tparm
interprets parameter information.
All terminfo 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 desiring shell escapes can call reset_shell_mode
before the shell is called and reset_prog_mode after returning from the shell.
delay_output (int ms);
Sets the output delay, in milliseconds.
def_prog_mode ( );
Saves the current terminal mode as program mode, in cur_term->Nttyb.
def_shell_mode ( );
Saves the shell mode as normal mode, in cur_term->Ottyb. def_shell_mode is
called automatically by setupterm.
Processed November 7, 1990 CURSES(3x,L) 9
CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
putp(char *str);
Calls tputs(str, 1, _outchar).
reset_prog_mode ( );
Puts the terminal into program mode.
reset_shell_mode ( );
Puts the terminal into shell mode. All programs must call reset_shell_mode
before they exit. The higher-level routine endwin automatically does this.
setupterm(char *term, int filenum, int *erret);
Reads in the data base. term is a character string that specifies the
terminal name. If term is 0, then the value of the TERM environment
variable is used. One of the following status values is stored into the
integer pointed to by erret:
1 Successful completion
0 No such terminal
-1 An error occurred while locating the terminfo data base.
If the erret parameter is 0, then no status value is returned, and an error
causes setupterm to print an error message and exit, rather than return.
filenum is the file descriptor of the terminal being used for output.
setupterm calls termdef to determine the number of lines and columns on the
display. If termdef cannot supply this information, then setupterm uses the
values in the terminfo data base. The simplest call is setupterm(0, 1, 0),
which uses all the defaults.
After the call to setupterm, the global variable cur_term is set to point to
the current structure of terminal capabilities. It is possible for a
program to use more than one terminal at a time by calling setupterm for
each terminal and saving and restoring cur_term.
The setupterm subroutine also initializes the global variable ttytype, an
array of characters to the value of the list of names for the terminal. The
list comes from the beginning of the terminfo description.
char *tparm(char *str, int p1, int p2, ... int p9)
Instantiates the string str with parameters p[i]. The character string
returned has the given parameters applied.
tputs(char *cp, int affcnt, int (*outc) ( ));
Applies padding information to string cp. affcnt is the number of lines
affected, or 1 if not applicable. outc is a putchar-like routine to which
the characters are passed one at a time.
Some strings are of a form like "$<20>", which is an instruction to pad for
20 milliseconds.
Processed November 7, 1990 CURSES(3x,L) 10
CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
vidputs(int newmode, int (*outc) ( ));
Outputs the string to put terminal in video attribute mode attrs. Characters
are passed to the putchar-like routine outc. The attrs are defined in
<curses.h>. The previous mode is retained by this routine.
vidattr(int newmode);
Like vidputs, but outputs through putchar.
TERMCAP COMPATIBILITY ROUTINES
These routines are included for compatibility with programs that require
termcap. Their parameters are the same as for termcap, and they are emulated
using the terminfo data base.
int tgetent(char *bp, char *name);
Looks up the termcap entry for name. name is a terminal name; bp is
ignored. Calls setupterm.
int tgetflag(char *id);
Returns the Boolean entry for id. id is a 2-character string that contains
a termcap identifier.
int tgetnum(char *id);
Returns the numeric entry for id. id is a 2-character string that contains
a termcap identifier.
char * tgetstr(char *id, char *area);
Returns the string entry for id. id is a 2-character string that contains a
termcap identifier. The area parameter is ignored.
char * tgoto(char *cap, int col, int row);
Applies parameters to the given cap. Calls tparm.
tputs(char *cp, int affcnt, int (*outc) ( ));
Applies padding to cap calling outc as putchar.
ATTRIBUTES
The following video attributes can be passed to the routines attron, attroff,
and attrset. Not all attributes are currently supported on all terminals (see
"Possible graphic renditions of VGA adapter").
A_STANDOUT The terminal's best highlighting mode
A_UNDERLINE Underlined
A_REVERSE Reverse video
A_BLINK Blinking
A_DIM Half bright
A_BOLD Extra bright or bold
A_INVIS Invisible (blanked or zero-intensity)
A_PROTECT Protected
A_ALTCHARSET Alternate character set
A_NORMAL Normal attributes
Processed November 7, 1990 CURSES(3x,L) 11
CURSES(3x,L) AIX Technical Reference CURSES(3x,L)
FUNCTION KEYS
The following function keys might be returned by getch if keypad has been
enabled. Note that not all of these are currently supported due to lack of
definitions in terminfo, or due to the terminal not transmitting a unique code
when the key is pressed.
KEY_BREAK Break key (unreliable)
KEY_DOWN Down-arrow key
KEY_UP Up-arrow key
KEY_LEFT Left-arrow key
KEY_RIGHT Right-arrow key
KEY_HOME Home key
KEY_BACKSPACE Backspace (unreliable)
KEY_F(n) Function key Fn, where n is an integer from 0 to 12
KEY_DL Delete line
KEY_IL Insert line
KEY_DC Delete character
KEY_IC Insert character or enter insert mode
KEY_EIC Exit insert character mode
KEY_CLEAR Clear screen
KEY_EOS Clear to end of screen
KEY_EOL Clear to end of line
KEY_SF Scroll 1 line forward
KEY_SR Scroll 1 line backwards (reverse)
KEY_NPAGE Next page
KEY_PPAGE Previous page
KEY_STAB Set tab
KEY_CTAB Clear tab
KEY_CATAB Clear all tabs
KEY_ENTER Enter or send (unreliable)
KEY_SRESET Soft (partial) reset (unreliable)
KEY_RESET Reset or hard reset (unreliable)
KEY_PRINT Print or copy
KEY_LL Home down or bottom (lower left)
KEY_A1 Upper left key of keypad
KEY_A3 Upper right key of keypad
KEY_B2 Center key of keypad
KEY_C1 Lower left key of keypad
KEY_C3 Lower right key of keypad
RELATED INFORMATION
In this book: "extended curses library," "termdef," and "terminfo."
Processed November 7, 1990 CURSES(3x,L) 12