|
|
#include <curses.h>
The curses package allows:
To initialize the routines, you must call the routine
initscr
or
newterm
before using any of the other routines that deal with windows and screens.
The routine
endwin(S)
must be called before exiting.
Most interactive, screen-oriented programs want single-character input
without echoing.
To get it, use this sequence:
cbreak();
noecho();
Most programs would also use the sequence:
nonl();
intrflush(stdscr,FALSE);
keypad(stdscr,TRUE);
Before you run a
curses( )
program, set the tab stops of the terminal
and output its initialization strings if they are defined.
You can do this using the command:
tput init
after the shell environment variable TERM has been exported. (See terminfo(F) and terminfo(M) for details.)
The curses( ) library lets you manipulate data structures, called windows, which can be thought of as two-dimensional arrays of characters. The library supplies a default window called stdscr, which is the size of the terminal screen. You can create others using newwin( ).
Windows are referred to by variables declared as WINDOW *. These data structures are manipulated with routines described on curses pages (whose names begin with ``curs_''). Among the most basic routines are move( ) and addch( ). The library includes more general versions of these routines that allow you to specify a window.
After routines manipulate a window, refresh( ) is called, telling curses( ) to make the user's screen look like stdscr. The characters in a window are actually of type chtype (character and attribute data) so that other information about the character can also be stored with each character.
Special windows called pads can also be manipulated. They are windows that might not be associated with a viewable part of the screen. See curs_pad(S) for more information.
In addition to drawing characters on the screen, you can use video attributes and colors, producing characters that are underlined, reverse video, or in color on terminals that support those modes. You can also output line-drawing characters. On input, curses( ) can also translate the escape sequences from arrow and function keys 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( ) has routines that manipulate color on color alphanumeric terminals. To use them, call start_color( ), usually right after initscr( ). Colors are always used in pairs, called color-pairs. A color-pair has a foreground color (the character) and a background color (the field on which the character is displayed).
You initialize a color-pair with the routine init_pair( ). After it has been initialized, you can use COLOR_PAIR(n), a macro defined in curses.h, in the same way that you use other video attributes. If a terminal can redefine colors, the following routines are useful:
If the environment variables LINES and COLUMNS are set, or if the program is running in a window environment, line and column information in the environment overrides information read by terminfo( ). Programs running in a window environment need this because the size of a screen is changeable.
If the environment variable
TERMINFO
is defined, any program using
curses( )
checks for a local terminal definition before checking in the standard place.
For example, if
TERM
is set to
wyse150,
then the compiled terminal definition is found in
/usr/lib/terminfo/w/wyse150
(The
w
is copied from the first letter of
wyse150
to avoid creating huge directories.)
However, if
TERMINFO
is set to
$HOME/myterms,
curses( )
first checks
$HOME/myterms/w/wyse150
and if that fails, it checks
/usr/lib/terminfo/w/wyse150
This is useful for developing experimental definitions or when write permission in /usr/lib/terminfo is not available.
The integer variables LINES and COLS are defined in curses.h and are filled in by initscr( ) with the size of the screen. The constant TRUE has the value 1; and the constant FALSE has the value 0.
curses routines also define the WINDOW * variable curscr, which is used for certain low-level operations such as clearing and redrawing a screen. However, curscr can be used in only a few routines.
For editing, it is entirely appropriate to operate at the character level. But for screen formatting, arbitrary movement of characters on screen is not desirable.
Routines that overwrite characters (such as addch( )) operate on a screen level. Overwriting a character with a character that requires a different number of columns can produce orphaned columns. They are filled with background characters.
Routines that insert characters (such as insch( )) operate on a character level (that is, at the character boundaries). A new character is inserted right before the current character, regardless of which column of a character the cursor points to. Before insertion, the cursor moves to the first column of the character.
Routines that delete characters (such as delch( )) also operate on a character level (that is, at the character boundaries). The character at the cursor is deleted, no matter which column of the character the cursor points to. Before deletion, the cursor moves to the first column of the character.
You cannot place a multi-column character on the last column of a line. If you try, the last column is set to the background character. Such an operation can also create orphaned columns, filled with background characters.
Overlapping and overwriting a window follows the operation of overwriting characters around its edge. The orphaned columns, if any, are handled as in character operations.
The cursor can be placed anywhere in a window. It moves to the first column of a multi-column character before an insertion or deletion.
Routines that set options require a Boolean flag bf with the value TRUE or FALSE; the flag bf is always of type bool. The variables ch and attrs are always of type chtype. The types WINDOW, SCREEN, bool, and chtype are defined in curses.h. The type TERMINAL, is defined in term.h. All other arguments are integers.
Many routines can be optimized by inlining them as macros.
Compile them with
cc ... -DPERFORMANCE
to explicitly enable this (see tinfo.h).
curses Routine Name | Manual Page Name |
---|---|
addch | curs_addch(S) |
addchnstr | curs_addchstr(S) |
addchstr | curs_addchstr(S) |
addnstr | curs_addstr(S) |
addnwstr | curs_addwstr(S) |
addstr | curs_addstr(S) |
addwch | curs_addwch(S) |
addwchnstr | curs_addwchstr(S) |
addwchstr | curs_addwchstr(S) |
addwstr | curs_addwstr(S) |
attroff | curs_attr(S) |
attron | curs_attr(S) |
attrset | curs_attr(S) |
baudrate | curs_termattrs(S) |
beep | curs_beep(S) |
bkgd | curs_bkgd(S) |
bkgdset | curs_bkgd(S) |
border | curs_border(S) |
box | curs_border(S) |
can_change_color | curs_color(S) |
cbreak | curs_inopts(S) |
clear | curs_clear(S) |
clearok | curs_outopts(S) |
clrtobot | curs_clear(S) |
clrtoeol | curs_clear(S) |
color_content | curs_color(S) |
copywin | curs_overlay(S) |
curs_set | curs_kernel(S) |
def_prog_mode | curs_kernel(S) |
def_shell_mode | curs_kernel(S) |
del_curterm | curs_terminfo(S) |
delay_output | curs_util(S) |
delch | curs_delch(S) |
deleteln | curs_deleteln(S) |
delscreen | curs_initscr(S) |
delwin | curs_window(S) |
derwin | curs_window(S) |
doupdate | curs_refresh(S) |
draino | curs_util(S) |
dupwin | curs_window(S) |
echo | curs_inopts(S) |
echochar | curs_addch(S) |
echowchar | curs_addwch(S) |
endwin | curs_initscr(S) |
erase | curs_clear(S) |
erasechar | curs_termattrs(S) |
filter | curs_util(S) |
flash | curs_beep(S) |
flushinp | curs_util(S) |
getbegyx | curs_getyx(S) |
getch | curs_getch(S) |
getmaxyx | curs_getyx(S) |
getnwstr | curs_getwstr(S) |
getparyx | curs_getyx(S) |
getstr | curs_getstr(S) |
getsyx | curs_kernel(S) |
getwch | curs_getwch(S) |
getwin | curs_util(S) |
getwstr | curs_getwstr(S) |
getyx | curs_getyx(S) |
halfdelay | curs_inopts(S) |
has_colors | curs_color(S) |
has_ic | curs_termattrs(S) |
has_il | curs_termattrs(S) |
hline | curs_border(S) |
idcok | curs_outopts(S) |
idlok | curs_outopts(S) |
immedok | curs_outopts(S) |
inch | curs_inch(S) |
inchnstr | curs_inchstr(S) |
inchstr | curs_inchstr(S) |
init_color | curs_color(S) |
init_pair | curs_color(S) |
initscr | curs_initscr(S) |
innstr | curs_instr(S) |
innwstr | curs_inwstr(S) |
insch | curs_insch(S) |
insdelln | curs_deleteln(S) |
insertln | curs_deleteln(S) |
insnstr | curs_insstr(S) |
insnwstr | curs_inswstr(S) |
insstr | curs_insstr(S) |
instr | curs_instr(S) |
inswch | curs_inswch(S) |
inswstr | curs_inswstr(S) |
intrflush | curs_inopts(S) |
inwch | curs_inwch(S) |
inwchnstr | curs_inwchstr(S) |
inwchstr | curs_inwchstr(S) |
inwstr | curs_inwstr(S) |
is_linetouched | curs_touch(S) |
is_wintouched | curs_touch(S) |
isendwin | curs_initscr(S) |
keyname | curs_util(S) |
keypad | curs_inopts(S) |
killchar | curs_termattrs(S) |
leaveok | curs_outopts(S) |
longname | curs_termattrs(S) |
meta | curs_inopts(S) |
move | curs_move(S) |
mvaddch | curs_addch(S) |
mvaddchnstr | curs_addchstr(S) |
mvaddchstr | curs_addchstr(S) |
mvaddnstr | curs_addstr(S) |
mvaddnwstr | curs_addwstr(S) |
mvaddstr | curs_addstr(S) |
mvaddwch | curs_addwch(S) |
mvaddwchnstr | curs_addwchstr(S) |
mvaddwchstr | curs_addwchstr(S) |
mvaddwstr | curs_addwstr(S) |
mvcur | curs_terminfo(S) |
mvdelch | curs_delch(S) |
mvderwin | curs_window(S) |
mvgetch | curs_getch(S) |
mvgetnwstr | curs_getwstr(S) |
mvgetstr | curs_getstr(S) |
mvgetwch | curs_getwch(S) |
mvgetwstr | curs_getwstr(S) |
mvinch | curs_inch(S) |
mvinchnstr | curs_inchstr(S) |
mvinchstr | curs_inchstr(S) |
mvinnstr | curs_instr(S) |
mvinnwstr | curs_inwstr(S) |
mvinsch | curs_insch(S) |
mvinsnstr | curs_insstr(S) |
mvinsnwstr | curs_inswstr(S) |
mvinsstr | curs_insstr(S) |
mvinstr | curs_instr(S) |
mvinswch | curs_inswch(S) |
mvinswstr | curs_inswstr(S) |
mvinwch | curs_inwch(S) |
mvinwchnstr | curs_inwchstr(S) |
mvinwchstr | curs_inwchstr(S) |
mvinwstr | curs_inwstr(S) |
mvprintw | curs_printw(S) |
mvscanw | curs_scanw(S) |
mvwaddch | curs_addch(S) |
mvwaddchnstr | curs_addchstr(S) |
mvwaddchstr | curs_addchstr(S) |
mvwaddnstr | curs_addstr(S) |
mvwaddnwstr | curs_addwstr(S) |
mvwaddstr | curs_addstr(S) |
mvwaddwch | curs_addwch(S) |
mvwaddwchnstr | curs_addwchstr(S) |
mvwaddwchstr | curs_addwchstr(S) |
mvwaddwstr | curs_addwstr(S) |
mvwdelch | curs_delch(S) |
mvwgetch | curs_getch(S) |
mvwgetnwstr | curs_getwstr(S) |
mvwgetstr | curs_getstr(S) |
mvwgetwch | curs_getwch(S) |
mvwgetwstr | curs_getwstr(S) |
mvwin | curs_window(S) |
mvwinch | curs_inch(S) |
mvwinchnstr | curs_inchstr(S) |
mvwinchstr | curs_inchstr(S) |
mvwinnstr | curs_instr(S) |
mvwinnwstr | curs_inwstr(S) |
mvwinsch | curs_insch(S) |
mvwinsnstr | curs_insstr(S) |
mvwinsstr | curs_insstr(S) |
mvwinstr | curs_instr(S) |
mvwinswch | curs_inswch(S) |
mvwinswstr | curs_inswstr(S) |
mvwinwch | curs_inwch(S) |
mvwinwchnstr | curs_inwchstr(S) |
mvwinwchstr | curs_inwchstr(S) |
mvwinwstr | curs_inwstr(S) |
mvwprintw | curs_printw(S) |
mvwscanw | curs_scanw(S) |
napms | curs_kernel(S) |
newpad | curs_pad(S) |
newterm | curs_initscr(S) |
newwin | curs_window(S) |
nl | curs_outopts(S) |
nocbreak | curs_inopts(S) |
nodelay | curs_inopts(S) |
noecho | curs_inopts(S) |
nonl | curs_outopts(S) |
noqiflush | curs_inopts(S) |
noraw | curs_inopts(S) |
notimeout | curs_inopts(S) |
overlay | curs_overlay(S) |
overwrite | curs_overlay(S) |
pair_content | curs_color(S) |
pechochar | curs_pad(S) |
pechowchar | curs_pad(S) |
pnoutrefresh | curs_pad(S) |
prefresh | curs_pad(S) |
printw | curs_printw(S) |
putp | curs_terminfo(S) |
putwin | curs_util(S) |
qiflush | curs_inopts(S) |
raw | curs_inopts(S) |
redrawwin | curs_refresh(S) |
refresh | curs_refresh(S) |
reset_prog_mode | curs_kernel(S) |
reset_shell_mode | curs_kernel(S) |
resetty | curs_kernel(S) |
restartterm | curs_terminfo(S) |
ripoffline | curs_kernel(S) |
savetty | curs_kernel(S) |
scanw | curs_scanw(S) |
scr_dump | curs_scr_dump(S) |
scr_init | curs_scr_dump(S) |
scr_restore | curs_scr_dump(S) |
scr_set | curs_scr_dump(S) |
scrl | curs_scroll(S) |
scroll | curs_scroll(S) |
scrollok | curs_outopts(S) |
set_curterm | curs_terminfo(S) |
set_term | curs_initscr(S) |
setscrreg | curs_outopts(S) |
setsyx | curs_kernel(S) |
setterm | curs_terminfo(S) |
setupterm | curs_terminfo(S) |
slk_attroff | curs_slk(S) |
slk_attron | curs_slk(S) |
slk_attrset | curs_slk(S) |
slk_clear | curs_slk(S) |
slk_init | curs_slk(S) |
slk_label | curs_slk(S) |
slk_noutrefresh | curs_slk(S) |
slk_refresh | curs_slk(S) |
slk_restore | curs_slk(S) |
slk_set | curs_slk(S) |
slk_touch | curs_slk(S) |
standend | curs_attr(S) |
standout | curs_attr(S) |
start_color | curs_color(S) |
subpad | curs_pad(S) |
subwin | curs_window(S) |
syncok | curs_window(S) |
termattrs | curs_termattrs(S) |
termname | curs_termattrs(S) |
tgetent | curs_termcap(S) |
tgetflag | curs_termcap(S) |
tgetnum | curs_termcap(S) |
tgetstr | curs_termcap(S) |
tgoto | curs_termcap(S) |
tigetflag | curs_terminfo(S) |
tigetnum | curs_terminfo(S) |
tigetstr | curs_terminfo(S) |
timeout | curs_inopts(S) |
touchline | curs_touch(S) |
touchwin | curs_touch(S) |
tparm | curs_terminfo(S) |
tputs | curs_termcap(S) |
tputs | curs_terminfo(S) |
typeahead | curs_inopts(S) |
unctrl | curs_util(S) |
ungetch | curs_getch(S) |
ungetwch | curs_getwch(S) |
untouchwin | curs_touch(S) |
use_env | curs_util(S) |
vidattr | curs_terminfo(S) |
vidputs | curs_terminfo(S) |
vline | curs_border(S) |
vwprintw | curs_printw(S) |
vwscanw | curs_scanw(S) |
waddch | curs_addch(S) |
waddchnstr | curs_addchstr(S) |
waddchstr | curs_addchstr(S) |
waddnstr | curs_addstr(S) |
waddnwstr | curs_addwstr(S) |
waddstr | curs_addstr(S) |
waddwch | curs_addwch(S) |
waddwchnstr | curs_addwchstr(S) |
waddwchstr | curs_addwchstr(S) |
waddwstr | curs_addwstr(S) |
wattroff | curs_attr(S) |
wattron | curs_attr(S) |
wattrset | curs_attr(S) |
wbkgd | curs_bkgd(S) |
wbkgdset | curs_bkgd(S) |
wborder | curs_border(S) |
wclear | curs_clear(S) |
wclrtobot | curs_clear(S) |
wclrtoeol | curs_clear(S) |
wcursyncup | curs_window(S) |
wdelch | curs_delch(S) |
wdeleteln | curs_deleteln(S) |
wechochar | curs_addch(S) |
wechowchar | curs_addwch(S) |
werase | curs_clear(S) |
wgetch | curs_getch(S) |
wgetnstr | curs_getstr(S) |
wgetnwstr | curs_getwstr(S) |
wgetstr | curs_getstr(S) |
wgetwch | curs_getwch(S) |
wgetwstr | curs_getwstr(S) |
whline | curs_border(S) |
winch | curs_inch(S) |
winchnstr | curs_inchstr(S) |
winchstr | curs_inchstr(S) |
winnstr | curs_instr(S) |
winnwstr | curs_inwstr(S) |
winsch | curs_insch(S) |
winsdelln | curs_deleteln(S) |
winsertln | curs_deleteln(S) |
winsnstr | curs_insstr(S) |
winsnwstr | curs_inswstr(S) |
winsstr | curs_insstr(S) |
winstr | curs_instr(S) |
winswch | curs_inswch(S) |
winswstr | curs_inswstr(S) |
winwch | curs_inwch(S) |
winwchnstr | curs_inwchstr(S) |
winwchstr | curs_inwchstr(S) |
winwstr | curs_inwstr(S) |
wmove | curs_move(S) |
wnoutrefresh | curs_refresh(S) |
wprintw | curs_printw(S) |
wredrawln | curs_refresh(S) |
wrefresh | curs_refresh(S) |
wscanw | curs_scanw(S) |
wscrl | curs_scroll(S) |
wsetscrreg | curs_outopts(S) |
wstandend | curs_attr(S) |
wstandout | curs_attr(S) |
wsyncdown | curs_window(S) |
wsyncup | curs_window(S) |
wtimeout | curs_inopts(S) |
wtouchln | curs_touch(S) |
wvline | curs_border(S) |
All macros return the value of the window version, except setscrreg( ), wsetscrreg( ), getyx( ), getbegyx( ), and getmaxyx( ). The return values of those exceptions ( setscrreg( ), wsetscrreg( ), getyx( ), getbegyx( ), and getmaxyx( )) are undefined, so they should not be used as the right-hand side of assignment statements.
Routines that return pointers return NULL on error.