curses Overview curses
Library of screen-handling functions
curses is a set of routines that allow you to manipulate the
screen in a sophisticated manner. These routines use the termcap
functions to read information about the user's terminal. This
allows you to write programs that can perform rudimentary
graphics on a wide variety of terminals.
curses contains routines that do the following:
* Move the cursor about the screen.
* Insert text onto the screen, either in normal or reverse video
(if supported by the display device).
* Read what is typed by the user and display it properly.
* Organize the screen into one or more rectangular regions, or
windows, optionally draw a border around each, and manage each
independently.
curses organizes the screen into a two-dimensional array of
cells, one cell for every character that the device can display.
It maintains in memory an image of the screen, called the curscr.
A second image, called the stdcur, is manipulated by the user;
when the user has finished a given manipulation, curses copies
the changes from the stdcur to the curscr, which results in their
being displayed on the physical screen. This act of copying from
the stdscr to the curscr is called refreshing the screen. curses
keeps track of where all changes have begun and ended between one
refresh and the next; this lets it rewrite only the portions of
the curscr that the user has changed, and so speed up rewriting
of the screen.
curses records the position of a ``logical cursor'', which points
to the position in the stdscr that is being manipulated by the
user, and also records the position of the physical cursor. Note
that the two are not necessarily identical: it is possible to
manipulate the logical cursor without repositioning the physical
cursor, and vice versa, depending on the task you wish to per-
form.
Most curses routines work by manipulating WINDOW object. WINDOW
is defined in the header curses.h as follows:
#define WINDOW _win_st
struct _win_st {
short _cury, _curx;
short _maxy, _maxx;
short _begy, _begx;
short _flags;
short _ch_off;
COHERENT Lexicon Page 1
curses Overview curses
bool _clear;
bool _leave;
bool _scroll;
char **_y;
short *_firstch;
short *_lastch;
struct _win_st *_nextp, *_orig;
};
Type bool is defined in curses.h; an object of this type can hold
the value of true (nonzero) or false (zero).
The following describes each WINDOW field in detail.
_cury, _curx
Give the Y and X positions of the logical cursor. The
upper left corner of the window is, by definition,
position 0,0. Note that curses by convention gives
positions as Y/X (column/row) rather than X/Y, as is
usual elsewhere.
_maxy, _maxx
Width and height of the window.
_begy, _begx
Position of the upper left corner of the window rela-
tive to the upper left corner of the physical screen.
For example, if the window's upper left corner is five
rows from the top of the screen and ten columns from
the left, then _begy and _begx will be set to ten and
five, respectively.
_flags One or more of the following flags, logically OR'd
together:
_SUBWIN -- Window is a sub-window
_ENDLINE -- Right edge of window touches edge of the screen
_FULLWIN -- Window fills the physical screen
_SCROLLWIN -- Window touches lower right corner of physical screen
_FULLINE -- Window extends across entire physical screen
_STANDOUT -- Write text in reverse video
_INSL -- Line has been inserted into window
_DELL -- Line has been deleted from window
_ch_off Character offset.
_clear Clear the physical screen before next refresh of the
screen.
_leave Do not move the physical cursor after refreshing the
screen.
COHERENT Lexicon Page 2
curses Overview curses
_scroll Enable scrolling for this window.
_y Pointer to an array of pointers to the character arrays
that hold the window's text.
_firstch Pointer to an array of integers, one for each line in
the window, whose value is the first character in the
line to have been altered by the user. If a line has
not been changed, then its corresponding entry in the
array is set to _NOCHANGE.
_lastch Same as _firstch, except that it indicates the last
character to have been changed on the line.
_nextp Point to next window.
_orig Point to parent window.
When curses is first invoked, it defines the entire screen as
being one large window. The programmer has the choice of sub-
dividing an existing window or creating new windows; when a win-
dow is subdivided, it shares the same curscr as its parent win-
dow, whereas a new window has its own stdscr.
Mark Williams Company will document its curses library in full in
a later release of this manual. The following table, however,
summarizes the functions and macros that that compose the curses
library.
addch(ch) char ch;
Insert a character into stdscr.
addstr(str) char *str;
Insert a string into stdscr.
box(win, vert, hor) WINDOW *win; char vert, hor;
Draw a box. vert is the character used to draw the vertical
lines, and hor is used to draw the horizontal lines. For
example
box(win, '|', '-');
draws a box around window win, using `|' to draw the verti-
cal lines and `-' to draw the horizontal lines.
clear()
Clear the stdscr.
clearok(win,bf) WINDOW *win; bool bf;
Set the clear flag for window win. This will clear the
screen at the next refresh, but not reset the window.
clrtobot()
Clear from the position of the logical cursor to the bottom
of the window.
COHERENT Lexicon Page 3
curses Overview curses
clrtoeol()
Clear from the logical cursor to the end of the line.
crmode()
Turn on control-character mode; i.e., force terminal to
receive cooked input.
delch()
Delete a character from stdscr; shift the rest of the
characters on the line one position to the left.
deleteln()
Delete all of the current line; shift up the rest of the
lines in the window.
delwin(win) WINDOW *win;
Delete window win.
echo()
Turn on both physical and logical echoing; i.e., character
are automatically inserted into the current window and onto
the physical screen.
endwin()
Terminate text processing with curses.
erase()
Erase a window; do not clear the screen.
getch()
Read a character from the terminal.
getstr(str) char *str;
Read a string from the terminal.
getyx(win,y,x) WINDOW *win; short y,x;
Read the position of the logical cursor in win and store it
in y,x. Note that this is a macro, and due to its construc-
tion the variables y and x must be integers, not pointers to
integers.
inch()
Read the character pointed to by the stdscr's logical cur-
sor.
WINDOW *initscr()
Initialize curses.
insch(ch) char ch;
Insert character ch into the stdscr.
insertln()
Insert a blank line into stdscr, above the current line.
COHERENT Lexicon Page 4
curses Overview curses
leaveok(win,bf) WINDOW *win; bool bf;
Set _leave in win to bf.
char *longname(termbuf, name) char *termbuf, *name;
Copy the long name for the terminal from termbuf into name.
move(y,x) short y,x;
Move logical cursor to position y,x in stdscr.
mvaddbytes(y,x,da,count) int y,x; char *da; int count;
Move to position y,x and print count bytes from the string
pointed to by da.
mvaddch(y,x,ch) short y,x; char ch;
Move the logical cursor to position y,x and insert character
ch.
mvaddstr(y,x,str) short y,x; char *str;
Move the logical cursor to position y,x and insert string
str.
mvcur(y_cur,x_cur,y_new,x_new) int y_cur, x_cur, y_new, x_new;
Move cursor from position y_cur,x_cur to position
y_new,x_new.
mvdelch(y,x) short y,x;
Move to position y,x and delete the character found there.
mvgetch(y,x) short y,x;
Move to position y,x and get a character through stdscr.
mvgetstr(y,x,str) short y,x; char *str;
Move to position y,x, get a string through stdscr, and copy
it into string.
mvinch(y,x) short y,x;
Move to position y,x and get the character found there.
mvinsch(y,x,ch) short y,x; char ch;
Move to position y,x and insert a character into stdscr.
mvwaddbytes(win,y,x,da,count) WINDOW *win; int y,x; char *da; int
count;
Move to position y,x and print count bytes from the string
pointed to by da into window win.
mvwaddch(win,y,x,ch) WINDOW *win; int y,x; char ch;
Move to position y,x and insert character ch into window
win.
mvwaddstr(win,y,x,str) WINDOW *win; short y,x; char *str;
Move to position y,x and insert character ch.
mvwdelch(win,y,x) WINDOW *win; int y,x;
Move to position y,x and delete character ch from window
COHERENT Lexicon Page 5
curses Overview curses
win.
mvwgetch(win,y,x) WINDOW *win; short y,x;
Move to position y,x and get a character.
mvwgetstr(win,y,x,str) WINDOW *win; short y,x; char *str;
Move to position y,x, get a string, and write it into str.
mvwin(win,y,x) WINDOW *win; int y,x;
Move window win to position y,x.
mvwinch(win,y,x) WINDOW *win; short y,x;
Move to position y,x and get character found there.
mvwinsch(win,y,x,ch) WINDOW *win; short y,x; char ch;
Move to position y,x and insert character ch there.
WINDOW *newwin(lines, cols, y1, x1) int lines, cols, y1, x1;
Create a new window. The new window is lines lines high,
cols columns wide, with the upper-left corner at position
y1,x1.
nl() Turn on newline mode; i.e., force terminal to output
<newline> after <linefeed>.
nocrmode()
Turn off control-character mode; i.e., force terminal to ac-
cept raw input.
noecho()
Turn off echo mode.
nonl()
Turn off newline mode.
noraw()
Turn off raw mode.
overlay(win1,win2) WINDOW *win1, win2;
Copy all characters, except spaces, from their current
positions in win1 to identical positions in win2.
overwrite(win1,win2) WINDOW *win1, win2;
Copy all characters, including spaces, from win1 to their
identical positions in win2.
printw(format[,arg1,...argN]) char *format; [data type]
arg1,..argN;
Print formatted text on the standard screen.
raw()
Turn on raw mode; i.e., kernel does not process what is
typed at the keyboard, but passes it directly to curses. In
normal (or cooked) mode, the kernel intercepts and processes
the control characters <ctrl-C>, <ctrl-S>, <ctrl-Q>, and
COHERENT Lexicon Page 6
curses Overview curses
<ctrl-Y>. See the entry for stty for more information.
refresh()
Copy the contents of stdscr to the physical screen.
resetty()
Reset the terminal flags to values stored by earlier call to
savetty.
savetty()
Save the current terminal settings.
scanw(format[,arg1,...argN]) char *format; [data type]
arg1,..argN;
Read the standard input; translate what is read into the ap-
propriate data type.
scroll(win) WINDOW *win;
Scroll win up by one line.
scrollok(win,bf) WINDOW *win; bool bf;
Permit or forbid scrolling of window win, depending upon
whether bf is set to true or false.
standend()
Turn off standout mode.
standout()
Turn on standout mode for text. Usually, this means that
text will be displayed in reverse video.
WINDOW *subwin(win,lines,cols,y1,x1) int win,lines,cols,y1,x1;
Create a sub-window in window win. New sub-window is lines
lines high, cols columns wide, and is fixed at position
y1,x1. Note that the position is relative to the upper-left
corner of the physical screen.
touchwin(win) WINDOW *win;
Copy all characters in window win to the screen.
waddch(win,ch) WINDOW *win; char ch;
Add character ch win.
waddstr(win,str) WINDOW *win; char *str;
Add the string pointed to by str to window win.
wclear(win) WINDOW *win;
Clear window win. Move cursor to position 0,0 and set the
screen's clear flag.
wclrtobot(win) WINDOW *win;
Clear window win from current position to the bottom.
wclrtoeol(win) WINDOW *win;
Clear window win from the current position to the end of the
COHERENT Lexicon Page 7
curses Overview curses
line.
wdelch(win) WINDOW *win;
Delete the character at the current position in window win;
shift all remaining characters to the right of the current
position one position left.
wdeleteln(win) WINDOW *win;
Delete the current line and shift all lines below it one
line up.
werase(win) WINDOW *win;
Clear window win. Move the cursor to position 0,0 but do
not set the screen's clear flag.
wgetch(win) WINDOW *win;
Read one character from the standard input.
wgetstr(win,str) WINDOW *win; char *str;
Read a string from the standard input; write it in the area
pointed to by str.
winch(win) WINDOW *win;
Force the next call to refresh() to rewrite the entire
screen.
winsch(win,ch) WINDOW *win; char ch;
Insert character ch into window win at the current position.
Shift all existing characters one position to the right.
winsertln(win) WINDOW *win;
Insert a blank line into window win at the current position.
Move all lines down by one position.
wmove(win,y,x) WINDOW *win; int y, x;
Move current position in the window win to position y,x.
wprintw(win,format[,arg1,...argN]) WINDOW *win; char *format;
[data type] arg1,..argN;
Format text and print it to the current position in window
win.
wrefresh(win) WINDOW *win;
Refresh a window.
wscanw(win,format[,arg1,...argN]) WINDOW *win; char *format;
[data type] arg1,..argN;
Read standard input from the current position in window win,
format it, and store it in the indicated places.
wstandend(win) WINDOW *win;
Turn off standout (reverse video) mode for window win.
wstandout(win) WINDOW *win;
Turn on standout (reverse video) mode for window win.
COHERENT Lexicon Page 8
curses Overview curses
These routines are declared and defined in the header file cur-
ses.h.
***** Structure of a curses Program *****
To use the curses routines, a program must included the header
file curses.h, which declares and defines the functions and mac-
ros that comprise the curses library.
Before a program can perform any graphics operations, it must
call the function initscr() to initialize the curses environment.
Then, the program must call cmdwind() to open the curscr.
As noted above, curses manipulates text in a copy of the screen
that it maintains in memory. After a program has manipulated
text, it must call refresh() to copy these alterations from
memory to the physical screen. (This is done because writing to
the screen is slow; this scheme permits mass alterations to be
made to copy in memory, then written to the screen in a batch.)
Finally, when the program has finished working with curses, it
must call the function endwin(). This frees memory allocated by
curses, and generally closes down the curses environment
gracefully.
***** Example *****
The following program, called curexample.c, gives a simple ex-
ample of programming with curses. To compile this program, use
the command line:
cc curexample.c -lcurses -lterm
Note that order in which the libraries are called is significant.
When this program is run, it clears the screen, then waits for
you to type a Y coordinate, a space, and then an X coordinate.
Note that these do not echo on the screen. It moves the cursor
to the requested coordinates, and there display any non-numeric
string that you type. If you type numerals, curexample will as-
sume that you wish to move the cursor to a new location. To
exit, type <ctrl-C>.
#include <ascii.h>
#include <ctype.h>
#include <curses.h>
COHERENT Lexicon Page 9
curses Overview curses
#define NORMAL 0
#define INY 1
#define INX 2
main()
{
int c, y, x, state;
initscr(); /* initialize curses */
noecho();
raw();
clear();
move(0, 0);
for(state = NORMAL;;) {
refresh();
c = getch();
if(isdigit(c)) {
switch (state) {
case NORMAL:
y = x = 0;
state = INY;
case INY:
y *= 10;
y += c - '0';
break;
case INX:
x *= 10;
x += c - '0';
}
} else {
if (c == A_ETX) { /* ctl-c */
noraw();
echo();
endwin();
exit(0);
}
COHERENT Lexicon Page 10
curses Overview curses
switch (state) {
case INX:
state = NORMAL;
move(y, x);
case NORMAL:
addch(c);
break;
case INY:
state = INX;
}
}
}
}
***** See Also *****
curses.h, libraries, termcap
Strang J: Programming with curses. Sebastopol, Calif, O'Reilly &
Associates Inc., 1986.
***** Notes *****
curses is copyrighted by the Regents of the University of
California.
COHERENT Lexicon Page 11