![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to curses CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [MW Coherent from dump] / coherent / a / usr / man / COHERENT|
Return to curses CVS log | Up to [MW Coherent from dump] / coherent / a / usr / man / COHERENT |
coherent
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 tteerrmmccaapp
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
_w_i_n_d_o_w_s, 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.
_ccuurryy, _ccuurrxx
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.
_mmaaxxyy, _mmaaxxxx
Width and height of the window.
_bbeeggyy, _bbeeggxx
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.
_ffllaaggss One or more of the following flags, logically OR'd
together:
_SSUUBBWWIINN -- Window is a sub-window
_EENNDDLLIINNEE -- Right edge of window touches edge of the screen
_FFUULLLLWWIINN -- Window fills the physical screen
_SSCCRROOLLLLWWIINN -- Window touches lower right corner of physical screen
_FFUULLLLIINNEE -- Window extends across entire physical screen
_SSTTAANNDDOOUUTT -- Write text in reverse video
_IINNSSLL -- Line has been inserted into window
_DDEELLLL -- Line has been deleted from window
_cchh_ooffff Character offset.
_cclleeaarr Clear the physical screen before next refresh of the
screen.
_lleeaavvee Do not move the physical cursor after refreshing the
screen.
COHERENT Lexicon Page 2
curses Overview curses
_ssccrroollll Enable scrolling for this window.
_yy Pointer to an array of pointers to the character arrays
that hold the window's text.
_ffiirrssttcchh 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 _NNOOCCHHAANNGGEE.
_llaassttcchh Same as _ffiirrssttcchh, except that it indicates the last
character to have been changed on the line.
_nneexxttpp Point to next window.
_oorriigg 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.
aaddddcchh(_c_h) cchhaarr _c_h;
Insert a character into stdscr.
aaddddssttrr(_s_t_r) cchhaarr *_s_t_r;
Insert a string into stdscr.
bbooxx(_w_i_n, _v_e_r_t, _h_o_r) WWIINNDDOOWW *_w_i_n; cchhaarr _v_e_r_t, _h_o_r;
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.
cclleeaarr()
Clear the stdscr.
cclleeaarrookk(_w_i_n,_b_f) WWIINNDDOOWW *_w_i_n; bbooooll _b_f;
Set the clear flag for window win. This will clear the
screen at the next refresh, but not reset the window.
ccllrrttoobboott()
Clear from the position of the logical cursor to the bottom
of the window.
COHERENT Lexicon Page 3
curses Overview curses
ccllrrttooeeooll()
Clear from the logical cursor to the end of the line.
ccrrmmooddee()
Turn on control-character mode; i.e., force terminal to
receive cooked input.
ddeellcchh()
Delete a character from stdscr; shift the rest of the
characters on the line one position to the left.
ddeelleetteellnn()
Delete all of the current line; shift up the rest of the
lines in the window.
ddeellwwiinn(_w_i_n) WWIINNDDOOWW *_w_i_n;
Delete window win.
eecchhoo()
Turn on both physical and logical echoing; i.e., character
are automatically inserted into the current window and onto
the physical screen.
eennddwwiinn()
Terminate text processing with curses.
eerraassee()
Erase a window; do not clear the screen.
ggeettcchh()
Read a character from the terminal.
ggeettssttrr(_s_t_r) cchhaarr *_s_t_r;
Read a string from the terminal.
ggeettyyxx(_w_i_n,_y,_x) WWIINNDDOOWW *_w_i_n; sshhoorrtt _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.
iinncchh()
Read the character pointed to by the stdscr's logical cur-
sor.
WWIINNDDOOWW *iinniittssccrr()
Initialize curses.
iinnsscchh(_c_h) cchhaarr _c_h;
Insert character ch into the stdscr.
iinnsseerrttllnn()
Insert a blank line into stdscr, above the current line.
COHERENT Lexicon Page 4
curses Overview curses
lleeaavveeookk(_w_i_n,_b_f) WWIINNDDOOWW *_w_i_n; bbooooll _b_f;
Set _leave in win to bf.
cchhaarr *lloonnggnnaammee(_t_e_r_m_b_u_f, _n_a_m_e) cchhaarr *_t_e_r_m_b_u_f, *_n_a_m_e;
Copy the long name for the terminal from termbuf into name.
mmoovvee(_y,_x) sshhoorrtt _y,_x;
Move logical cursor to position y,x in stdscr.
mmvvaaddddbbyytteess(_y,_x,_d_a,_c_o_u_n_t) iinntt _y,_x; cchhaarr *_d_a; iinntt _c_o_u_n_t;
Move to position y,x and print count bytes from the string
pointed to by da.
mmvvaaddddcchh(_y,_x,_c_h) sshhoorrtt _y,_x; cchhaarr _c_h;
Move the logical cursor to position y,x and insert character
ch.
mmvvaaddddssttrr(_y,_x,_s_t_r) sshhoorrtt _y,_x; cchhaarr *_s_t_r;
Move the logical cursor to position y,x and insert string
str.
mmvvccuurr(_y__c_u_r,_x__c_u_r,_y__n_e_w,_x__n_e_w) iinntt _y__c_u_r, _x__c_u_r, _y__n_e_w, _x__n_e_w;
Move cursor from position y_cur,x_cur to position
y_new,x_new.
mmvvddeellcchh(_y,_x) sshhoorrtt _y,_x;
Move to position y,x and delete the character found there.
mmvvggeettcchh(_y,_x) sshhoorrtt _y,_x;
Move to position y,x and get a character through stdscr.
mmvvggeettssttrr(_y,_x,_s_t_r) sshhoorrtt _y,_x; cchhaarr *_s_t_r;
Move to position y,x, get a string through stdscr, and copy
it into string.
mmvviinncchh(_y,_x) sshhoorrtt _y,_x;
Move to position y,x and get the character found there.
mmvviinnsscchh(_y,_x,_c_h) sshhoorrtt _y,_x; cchhaarr _c_h;
Move to position y,x and insert a character into stdscr.
mmvvwwaaddddbbyytteess(_w_i_n,_y,_x,_d_a,_c_o_u_n_t) WWIINNDDOOWW *_w_i_n; iinntt _y,_x; cchhaarr *_d_a; iinntt
_c_o_u_n_t;
Move to position y,x and print count bytes from the string
pointed to by da into window win.
mmvvwwaaddddcchh(_w_i_n,_y,_x,_c_h) WWIINNDDOOWW *_w_i_n; iinntt _y,_x; cchhaarr _c_h;
Move to position y,x and insert character ch into window
win.
mmvvwwaaddddssttrr(_w_i_n,_y,_x,_s_t_r) WWIINNDDOOWW *_w_i_n; sshhoorrtt _y,_x; cchhaarr *_s_t_r;
Move to position y,x and insert character ch.
mmvvwwddeellcchh(_w_i_n,_y,_x) WWIINNDDOOWW *_w_i_n; iinntt _y,_x;
Move to position y,x and delete character ch from window
COHERENT Lexicon Page 5
curses Overview curses
win.
mmvvwwggeettcchh(_w_i_n,_y,_x) WWIINNDDOOWW *_w_i_n; sshhoorrtt _y,_x;
Move to position y,x and get a character.
mmvvwwggeettssttrr(_w_i_n,_y,_x,_s_t_r) WWIINNDDOOWW *_w_i_n; sshhoorrtt _y,_x; cchhaarr *_s_t_r;
Move to position y,x, get a string, and write it into str.
mmvvwwiinn(_w_i_n,_y,_x) WWIINNDDOOWW *_w_i_n; iinntt _y,_x;
Move window win to position y,x.
mmvvwwiinncchh(_w_i_n,_y,_x) WWIINNDDOOWW *_w_i_n; sshhoorrtt _y,_x;
Move to position y,x and get character found there.
mmvvwwiinnsscchh(_w_i_n,_y,_x,_c_h) WWIINNDDOOWW *_w_i_n; sshhoorrtt _y,_x; cchhaarr _c_h;
Move to position y,x and insert character ch there.
WWIINNDDOOWW *nneewwwwiinn(lliinneess, ccoollss, yy11, xx11) iinntt _l_i_n_e_s, _c_o_l_s, _y_1, _x_1;
Create a new window. The new window is lines lines high,
cols columns wide, with the upper-left corner at position
y1,x1.
nnll() Turn on newline mode; i.e., force terminal to output
<newline> after <linefeed>.
nnooccrrmmooddee()
Turn off control-character mode; i.e., force terminal to ac-
cept raw input.
nnooeecchhoo()
Turn off echo mode.
nnoonnll()
Turn off newline mode.
nnoorraaww()
Turn off raw mode.
oovveerrllaayy(_w_i_n_1,_w_i_n_2) WWIINNDDOOWW *_w_i_n_1, _w_i_n_2;
Copy all characters, except spaces, from their current
positions in win1 to identical positions in win2.
oovveerrwwrriittee(_w_i_n_1,_w_i_n_2) WWIINNDDOOWW *_w_i_n_1, _w_i_n_2;
Copy all characters, including spaces, from win1 to their
identical positions in win2.
pprriinnttww(_f_o_r_m_a_t[,_a_r_g_1,..._a_r_g_N]) cchhaarr *_f_o_r_m_a_t; [_d_a_t_a _t_y_p_e]
_a_r_g_1,.._a_r_g_N;
Print formatted text on the standard screen.
rraaww()
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 _c_o_o_k_e_d) 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.
rreeffrreesshh()
Copy the contents of stdscr to the physical screen.
rreesseettttyy()
Reset the terminal flags to values stored by earlier call to
savetty.
ssaavveettttyy()
Save the current terminal settings.
ssccaannww(_f_o_r_m_a_t[,_a_r_g_1,..._a_r_g_N]) cchhaarr *_f_o_r_m_a_t; [_d_a_t_a _t_y_p_e]
_a_r_g_1,.._a_r_g_N;
Read the standard input; translate what is read into the ap-
propriate data type.
ssccrroollll(_w_i_n) WWIINNDDOOWW *_w_i_n;
Scroll win up by one line.
ssccrroollllookk(_w_i_n,_b_f) WWIINNDDOOWW *_w_i_n; bbooooll _b_f;
Permit or forbid scrolling of window win, depending upon
whether bf is set to true or false.
ssttaannddeenndd()
Turn off standout mode.
ssttaannddoouutt()
Turn on standout mode for text. Usually, this means that
text will be displayed in reverse video.
WWIINNDDOOWW *ssuubbwwiinn(_w_i_n,_l_i_n_e_s,_c_o_l_s,_y_1,_x_1) iinntt _w_i_n,_l_i_n_e_s,_c_o_l_s,_y_1,_x_1;
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.
ttoouucchhwwiinn(_w_i_n) WWIINNDDOOWW *_w_i_n;
Copy all characters in window win to the screen.
wwaaddddcchh(_w_i_n,_c_h) WWIINNDDOOWW *_w_i_n; cchhaarr _c_h;
Add character ch win.
wwaaddddssttrr(_w_i_n,_s_t_r) WWIINNDDOOWW *_w_i_n; cchhaarr *_s_t_r;
Add the string pointed to by str to window win.
wwcclleeaarr(_w_i_n) WWIINNDDOOWW *_w_i_n;
Clear window win. Move cursor to position 0,0 and set the
screen's clear flag.
wwccllrrttoobboott(_w_i_n) WWIINNDDOOWW *_w_i_n;
Clear window win from current position to the bottom.
wwccllrrttooeeooll(_w_i_n) WWIINNDDOOWW *_w_i_n;
Clear window win from the current position to the end of the
COHERENT Lexicon Page 7
curses Overview curses
line.
wwddeellcchh(_w_i_n) WWIINNDDOOWW *_w_i_n;
Delete the character at the current position in window win;
shift all remaining characters to the right of the current
position one position left.
wwddeelleetteellnn(_w_i_n) WWIINNDDOOWW *_w_i_n;
Delete the current line and shift all lines below it one
line up.
wweerraassee(_w_i_n) WWIINNDDOOWW *_w_i_n;
Clear window win. Move the cursor to position 0,0 but do
not set the screen's clear flag.
wwggeettcchh(_w_i_n) WWIINNDDOOWW *_w_i_n;
Read one character from the standard input.
wwggeettssttrr(_w_i_n,_s_t_r) WWIINNDDOOWW *_w_i_n; cchhaarr *_s_t_r;
Read a string from the standard input; write it in the area
pointed to by str.
wwiinncchh(_w_i_n) WWIINNDDOOWW *_w_i_n;
Force the next call to refresh() to rewrite the entire
screen.
wwiinnsscchh(_w_i_n,_c_h) WWIINNDDOOWW *_w_i_n; cchhaarr _c_h;
Insert character ch into window win at the current position.
Shift all existing characters one position to the right.
wwiinnsseerrttllnn(_w_i_n) WWIINNDDOOWW *_w_i_n;
Insert a blank line into window win at the current position.
Move all lines down by one position.
wwmmoovvee(_w_i_n,_y,_x) WWIINNDDOOWW *_w_i_n; iinntt _y, _x;
Move current position in the window win to position y,x.
wwpprriinnttww(_w_i_n,_f_o_r_m_a_t[,_a_r_g_1,..._a_r_g_N]) WWIINNDDOOWW *_w_i_n; cchhaarr *_f_o_r_m_a_t;
[_d_a_t_a _t_y_p_e] aarrgg11,..aarrggNN;
Format text and print it to the current position in window
win.
wwrreeffrreesshh(_w_i_n) WWIINNDDOOWW *_w_i_n;
Refresh a window.
wwssccaannww(_w_i_n,_f_o_r_m_a_t[,_a_r_g_1,..._a_r_g_N]) WWIINNDDOOWW *_w_i_n; cchhaarr *_f_o_r_m_a_t;
[_d_a_t_a _t_y_p_e] _a_r_g_1,.._a_r_g_N;
Read standard input from the current position in window win,
format it, and store it in the indicated places.
wwssttaannddeenndd(_w_i_n) WWIINNDDOOWW *_w_i_n;
Turn off standout (reverse video) mode for window win.
wwssttaannddoouutt(_w_i_n) WWIINNDDOOWW *_w_i_n;
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: _P_r_o_g_r_a_m_m_i_n_g _w_i_t_h _c_u_r_s_e_s. Sebastopol, Calif, O'Reilly &
Associates Inc., 1986.
***** Notes *****
curses is copyrighted by the Regents of the University of
California.
COHERENT Lexicon Page 11
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.