







     SSSSccccrrrreeeeeeeennnn UUUUppppddddaaaattttiiiinnnngggg aaaannnndddd CCCCuuuurrrrssssoooorrrr MMMMoooovvvveeeemmmmeeeennnntttt OOOOppppttttiiiimmmmiiiizzzzaaaattttiiiioooonnnn::::
                     AAAA LLLLiiiibbbbrrrraaaarrrryyyy PPPPaaaacccckkkkaaaaggggeeee

                  _K_e_n_n_e_t_h _C_. _R_. _C_. _A_r_n_o_l_d
                         _E_l_a_n _A_m_i_r

                 Computer Science Division
 Department of Electrical Engineering and Computer Science
             University of California, Berkeley
                Berkeley, California  94720



                          _AA_BB_SS_TT_RR_AA_CC_TT





     This  document  describes  a  package  of C library
functions which allow the user to:

1)   update a screen with reasonable optimization,

2)   get input from the terminal  in  a  screen-oriented
     fashion, and

3)   independent  from  the above, move the cursor opti-
     mally from one point to another.

     These routines all use the _t_e_r_m_c_a_p(5)  database  to
describe the capabilities of the terminal.

AAAAcccckkkknnnnoooowwwwlllleeeeddddggggeeeemmmmeeeennnnttttssss

     This  package  would not exist without the work of Bill
Joy, who, in writing his editor, created the  capability  to
generally  describe terminals, wrote the routines which read
this database, and, most importantly, those which  implement
optimal cursor movement, which routines I have simply lifted
nearly intact.  Doug  Merritt  and  Kurt  Shoens  also  were
extremely important, as were both willing to waste time lis-
tening to me rant and rave.  The help and/or support of  Ken
Abrams, Alan Char, Mark Horton, and Joe Kalash, was, and is,
also greatly appreciated.  _K_e_n _A_r_n_o_l_d    _1_6 _A_p_r_i_l _1_9_8_6

     The help and/or support  of  Kirk  McKusick  and  Keith
Bostic  (public vi!)  was invaluable in bringing the package
``into the 90's'', which now includes  completely  new  data
structures  and  screen refresh optimization routines.  _E_l_a_n
_A_m_i_r   _2_9 _D_e_c_e_m_b_e_r _1_9_9_2











SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                      PPPPSSSS1111::::11119999----1111


1111....  OOOOvvvveeeerrrrvvvviiiieeeewwww

     In making available the generalized  terminal  descrip-
tions  in _t_e_r_m_c_a_p(5), much information was made available to
the programmer, but little  work  was  taken  out  of  one's
hands.   The  purpose of this package is to allow the C pro-
grammer to do the most common  type  of  terminal  dependent
functions, those of movement optimization and optimal screen
updating, without doing any of  the  dirty  work,  and  with
nearly  as much ease as is necessary to simply print or read
things.

1111....1111....  TTTTeeeerrrrmmmmiiiinnnnoooollllooooggggyyyy

     In this document, the following terminology is used:

wwwwiiiinnnnddddoooowwww: An internal representation containing  an  image  of
     what  a section of the terminal screen may look like at
     some point in time.  This subsection can either  encom-
     pass the entire terminal screen, or any smaller portion
     down to a single character within that screen.

tttteeeerrrrmmmmiiiinnnnaaaallll: Sometimes called tttteeeerrrrmmmmiiiinnnnaaaallll ssssccccrrrreeeeeeeennnn.   The  package's
     idea  of  what  the  terminal's  screen currently looks
     like, _i_._e_., what the user sees now.  This is a  special
     _s_c_r_e_e_n:

ssssccccrrrreeeeeeeennnn:  This  is  a subset of windows which are as large as
     the terminal screen, _i_._e_., they start at the upper left
     hand  corner and encompass the lower right hand corner.
     One of these, _s_t_d_s_c_r, is automatically provided for the
     programmer.

1111....2222....  CCCCoooommmmppppiiiilllliiiinnnngggg AAAApppppppplllliiiiccccaaaattttiiiioooonnnnssss

     In  order  to  use the library, it is necessary to have
certain types and variables defined.   Therefore,  the  pro-
grammer must have a line:

    ####iiiinnnncccclllluuuuddddeeee <<<<ccccuuuurrrrsssseeeessss....hhhh>>>>

at  the top of the program source.  Compilations should have
the following form:

    _c_c [ flags ] file ... _-_l_c_u_r_s_e_s _-_l_t_e_r_m_c_a_p


1111....3333....  SSSSccccrrrreeeeeeeennnn UUUUppppddddaaaattttiiiinnnngggg

     In order to update the screen optimally, it  is  neces-
sary  for  the  routines  to  know what the screen currently
looks like and what the programmer wants  it  to  look  like
next.   For  this  purpose,  a  data  type (structure) named










SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                      PPPPSSSS1111::::11119999----3333


_W_I_N_D_O_W is defined which describes a window image to the rou-
tines,  including  its  starting position on the screen (the
(y, x) co-ordinates of the upper left hand corner)  and  its
size.   One of these (called _c_u_r_s_c_r for _c_u_r_r_e_n_t _s_c_r_e_e_n) is a
screen image of what  the  terminal  currently  looks  like.
Another  screen (called _s_t_d_s_c_r, for _s_t_a_n_d_a_r_d _s_c_r_e_e_n) is pro-
vided by default to make changes on.

     A window is a purely internal  representation.   It  is
used  to  build  and store a potential image of a portion of
the terminal.  It doesn't bear  any  necessary  relation  to
what  is  really on the terminal screen.  It is more like an
array of characters on which to make changes.

     When one has a window which describes  what  some  part
the  terminal  should  look  like, the routine refresh() (or
wrefresh()  if  the  window  is  not  _s_t_d_s_c_r)   is   called.
refresh()  makes  the  terminal,  in the area covered by the
window, look like that window.  Note, therefore, that chang-
ing  something  on  a  window  _d_o_e_s _nn_oo_tt _c_h_a_n_g_e _t_h_e _t_e_r_m_i_n_a_l.
Actual updates to the terminal screen are made only by call-
ing  refresh() or wrefresh().  This allows the programmer to
maintain several different ideas of what a  portion  of  the
terminal screen should look like.  Also, changes can be made
to windows in any order,  without  regard  to  motion  effi-
ciency.   Then,  at will, the programmer can effectively say
"make it look like this", and the package will  execute  the
changes in an optimal way.

1111....4444....  NNNNaaaammmmiiiinnnngggg CCCCoooonnnnvvvveeeennnnttttiiiioooonnnnssss

     As  hinted above, the routines can use several windows,
but two are always available: _c_u_r_s_c_r, which is the image  of
what  the  terminal looks like at present, and _s_t_d_s_c_r, which
is the image of what the programmer wants  the  terminal  to
look like next.  The user should not access _c_u_r_s_c_r directly.
Changes should be made to the appropriate screen,  and  then
the routine refresh() (or wrefresh()) should be called.

     Many  functions  are  set  up  to deal with _s_t_d_s_c_r as a
default screen.  For example, to add a character to  _s_t_d_s_c_r,
one  calls addch() with the desired character.  If a differ-
ent window is to be used, the routine waddch() (for  wwwwindow-
specific addch()) is provided1.  This convention of prepend-
ing function names with a "_w" when they are to be applied to
specific  windows is consistent.  The only routines which do
_n_o_t do this are those to  which  a  window  must  always  be
____________________
   1  Actually, addch() is really a "#define" macro with ar-
guments, as are most of the "functions" which act upon  _s_t_d_-
_s_c_r.












PPPPSSSS1111::::11119999----4444                                      SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


specified.

     In  order  to move the current (y, x) co-ordinates from
one point to another, the routines move()  and  wmove()  are
provided.   However, it is often desirable to first move and
then perform some I/O operation.  In order to avoid  clumsi-
ness,  most  I/O routines can be preceded by the prefix "_m_v"
and the desired (y, x) co-ordinates can then be added to the
arguments to the function.  For example, the calls

    move(y, x);
    addch(ch);

can be replaced by

    mvaddch(y, x, ch);

and

    wmove(win, y, x);
    waddch(win, ch);

can be replaced by

    mvwaddch(win, y, x, ch);

Note  that the window description pointer (_w_i_n) comes before
the added (y, x)  co-ordinates.   If  a  window  pointer  is
needed, it is always the first parameter passed.

2222....  VVVVaaaarrrriiiiaaaabbbblllleeeessss

     Many  variables which are used to describe the terminal
environment are available to the programmer.  They are:


    type    name       description
    ----------------------------------------------------------------------
    WINDOW *curscr     current version of the screen (terminal screen).
    WINDOW *stdscr     standard screen.  Most updates  are  usually  done
                       here.
    char *  Def_term   default terminal type if type cannot be determined
    bool    My_term    use the terminal specification in _D_e_f___t_e_r_m as ter-
                       minal, irrelevant of real terminal type
    char *  ttytype    full name of the current terminal.
    int     LINES      number of lines on the terminal
    int     COLS       number of columns on the terminal
    int     COLORS     number of colors on the terminal
    int     COLOR_PAIRSnumber of color pairs on the terminal
    int     ERR        error flag returned by routines on a fail.
    int     OK         flag returned by routines upon success.












SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                      PPPPSSSS1111::::11119999----5555


3333....  UUUUssssaaaaggggeeee

     This is a description of how to actually use the screen
package.  For simplicity, we assume all  updating,  reading,
etc.   is applied to _s_t_d_s_c_r, although a different window can
of course be specified.

3333....1111....  IIIInnnniiiittttiiiiaaaalllliiiizzzzaaaattttiiiioooonnnn

     In order to use the screen package, the  routines  must
know  about  terminal  characteristics,  and  the  space for
_c_u_r_s_c_r and _s_t_d_s_c_r must be allocated.   These  functions  are
performed  by  initscr().   Since it must allocate space for
the windows, it can overflow core when attempting to do  so.
On   this  rather  rare  occasion,  initscr()  returns  ERR.
initscr() must _aa_ll_ww_aa_yy_ss be called before any of  the  routines
which  affect  windows  are used.  If it is not, the program
will core dump as soon as either _c_u_r_s_c_r or _s_t_d_s_c_r are refer-
enced.  However, it is usually best to wait to call it until
after you are sure you will need it, like after checking for
startup errors.  Terminal status changing routines like nl()
and cbreak() should be called after initscr().

     After the initial window allocation done by  initscr(),
specific  window  characteristics can be set.  Scrolling can
be enabled by calling scrollok().  If you want the cursor to
be left after the last change, use leaveok().  If this isn't
done, refresh() will move the cursor to the window's current
(y, x)  co-ordinates  after updating it.  Additional windows
can be created by using the functions newwin() and subwin().
delwin() allows you to delete an existing window.  The vari-
ables _L_I_N_E_S and _C_O_L_S control the size of the terminal.  They
are  initially  implicitly  set  by  initscr(),  but  can be
altered explicitly  by  the  user  followed  by  a  call  to
initscr().   Note  that  any  call to initscr(), will always
delete any existing _s_t_d_s_c_r and/or _c_u_r_s_c_r before creating new
ones  so this change is best done before the initial call to
initscr().

3333....2222....  OOOOuuuuttttppppuuuutttt

     The basic functions used to change what will  go  on  a
window  are addch() and move().  addch() adds a character at
the current (y, x) co-ordinates, returning ERR if  it  would
cause the window to illegally scroll, _i_._e_., printing a char-
acter in the lower right-hand corner  of  a  terminal  which
automatically  scrolls  if scrolling is not allowed.  move()
changes the current (y, x) co-ordinates to whatever you want
them  to be.  It returns ERR if you try to move off the win-
dow.  As mentioned above, you can combine the two into mvad-
dch() to do both things in one call.












PPPPSSSS1111::::11119999----6666                                      SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


     The  other  output  functions  (such  as  addstr()  and
printw()) all call addch() to add characters to the  window.

     After  a  change  has been made to the window, you must
call refresh().  when you want the portion of  the  terminal
covered  by  the  window to reflect the change.  In order to
optimize finding changes, refresh() assumes that any part of
the window not changed since the last refresh() of that win-
dow has not been changed on the  terminal,  _i_._e_.,  that  you
have  not  refreshed a portion of the terminal with an over-
lapping window.  If this  is  not  the  case,  the  routines
touchwin(),  touchline(), and touchoverlap() are provided to
make it look like a desired part of window has been changed,
thus forcing refresh() to check that whole subsection of the
terminal for changes.

     If you call wrefresh() with _c_u_r_s_c_r, it  will  make  the
screen  look  like  the image of _c_u_r_s_c_r.  This is useful for
implementing a command which would redraw the screen in case
it got messed up.

3333....3333....  IIIInnnnppppuuuutttt

     Input  is  essentially  a  mirror image of output.  The
complementary function to addch() is getch() which, if  echo
is  set, will call addch() to echo the character.  Since the
screen package needs to know what is on the terminal at  all
times,  if  characters  are to be echoed, the tty must be in
raw or cbreak mode.  If it is not, getch()  sets  it  to  be
cbreak, and then reads in the character.

3333....4444....  TTTTeeeerrrrmmmmiiiinnnnaaaattttiiiioooonnnn

     In order to perform certain optimizations, and, on some
terminals, to work at all, some things must be  done  before
the screen routines start up.  These functions are performed
in getttmode() and setterm(), which are called by initscr().
In  order  to  clean up after the routines, the routine end-
win() is provided.  It restores tty modes to what they  were
when  initscr() was first called.  The terminal state module
uses the variable _c_u_r_s_e_s___t_e_r_m_i_o_s to save the original termi-
nal  state  which  is then restored upon a call to endwin().
Thus, anytime after the call to initscr, endwin() should  be
called  before  exiting.  Note however, that endwin() should
always be called bbbbeeeeffffoooorrrreeee the final calls to  delwin(),  which
free the storage of the windows.

4444....  CCCCuuuurrrrssssoooorrrr MMMMoooovvvveeeemmmmeeeennnntttt OOOOppppttttiiiimmmmiiiizzzzaaaattttiiiioooonnnnssss

     One  of  the  most  difficult  things to do properly is
motion optimization.  After using gettmode()  and  setterm()
to get the terminal descriptions, the function mvcur() deals
with this task.  It usage is simple: simply  tell  it  where










SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                      PPPPSSSS1111::::11119999----7777


you are now and where you want to go.  For example

    mvcur(0, 0, LINES/2, COLS/2);


would  move  the cursor from the home position (0, 0) to the
middle of  the  screen.   If  you  wish  to  force  absolute
addressing,  you  can  use  the  function  tgoto()  from the
tttteeeerrrrmmmmlllliiiibbbb(7) routines, or you can tell mvcur()  that  you  are
impossibly  far away, For example, to absolutely address the
lower left hand corner of  the  screen  from  anywhere  just
claim that you are in the upper right hand corner:

    mvcur(0, COLS-1, LINES-1, 0);


5555....  CCCChhhhaaaarrrraaaacccctttteeeerrrr OOOOuuuuttttppppuuuutttt aaaannnndddd SSSSccccrrrroooolllllllliiiinnnngggg

     The  character  output  policy deals with the following
problems.  First, where is the location of the cursor  after
a  character  is printed, and secondly, when does the screen
scroll if scrolling is enabled.

     In  the  normal  case  the  characters  are  output  as
expected, with the cursor occupying the position of the next
character to be output.  However, when the cursor is on  the
last  column  of  the  line,  the cursor will remain on that
position after the last character on the line is output  and
will only assume the position on the next line when the next
character (the first on the next line) is output.

     Likewise, if scrolling is enabled,  a  scroll  will  be
invoked  only when the first character on he first line past
the bottom line of the window is output.   If  scrolling  is
not  enabled  the  chracters will to be output to the bottom
right corner of the window which is the cursor location.

     This policy allows consistent behavior of the cursor at
the  boundary conditions.  Furthermore, it prevents a scroll
from happening before it is actually needed (the old package
used  to  scroll when the bottom right position was output a
character).  As a precedent, it models the  _x_t_e_r_m  character
output conventions.

6666....  TTTTeeeerrrrmmmmiiiinnnnaaaallll SSSSttttaaaatttteeee HHHHaaaannnnddddlllliiiinnnngggg

     The variable _c_u_r_s_e_s___t_e_r_m_i_o_s contains the terminal state
of the terminal.  Certain historical routines return  infor-
mation:  baudrate(),  erasechar(), killchar(), and ospeed().
These routines are obsolete and exist only for backward com-
patibility.   If  you  wish  to  use  the information in the
_c_u_r_s_e_s___t_e_r_m_i_o_s structure, you  should  use  the  _t_s_e_t_a_t_t_r(3)
routines.










PPPPSSSS1111::::11119999----8888                                      SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


7777....  SSSSuuuubbbbwwwwiiiinnnnddddoooowwwwssss

     Subwindows are windows which do not have an independent
text structure, _i_._e_., they are windows whose text is a  sub-
set  of the text of a larger window: the _p_a_r_e_n_t window.  One
consequence of this is that changes to either the parent  or
the  child  window  are  destructive  to  the other, _i_._e_., a
change to the subwindow is also a change to the parent  win-
dow  and a change to the parent window in the region defined
by the subwindow is implicitly a change to the subwindow  as
well.   Apart from this detail, subwindows function like any
other window.

8888....  TTTThhhheeee FFFFuuuunnnnccccttttiiiioooonnnnssss

     In the  following  definitions,  "[*]"  means  that  if
___C_U_R_S_E_S___U_S_E___M_A_C_R_O_S  is  defined,  the "function" is really a
"#define" macro with arguments.


addbytes(_c_h_a_r _*_s_t_r, _i_n_t _l_e_n);

     This function is the low level character  output  func-
     tion.   _L_e_n  characters of the string _s_t_r are output to
     the current (y, x) co-ordinates position of the window.


addch(_c_h_t_y_p_e _c_h);

     Add  the  character  _c_h  on  the  window at the current
     (y, x) co-ordinates.  If the  character  is  a  newline
     ('\n')  the  line  will  be cleared to the end, and the
     current (y, x) co-ordinates  will  be  changed  to  the
     beginning  off  the next line if newline mapping is on,
     or to the next line at the same x co-ordinate if it  is
     off.  A return ('\r') will move to the beginning of the
     line on the window.  Tabs ('\t') will be expanded  into
     spaces  in  the normal tabstop positions of every eight
     characters.  This returns ERR if  it  would  cause  the
     screen to scroll illegally.


addchstr(_c_h_t_y_p_e _*_s_t_r);

     Add the characters and attributes in the string pointed
     to by _s_t_r on the window at the current (y, x)  co-ordi-
     nates.   This  returns ERR if it would cause the screen
     to scroll illegally.  In this case, it will put  on  as
     much as it can.


addchnstr(_c_h_t_y_p_e _*_s_t_r, _i_n_t _l_e_n);











SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                      PPPPSSSS1111::::11119999----9999


     Add  no  more than _l_e_n characters and attributes of the
     string pointed to by _s_t_r on the window at  the  current
     (y, x)  co-ordinates.   This  returns  ERR  if it would
     cause the screen to scroll illegally.  In this case, it
     will put on as much as it can.


addstr(_c_h_a_r _*_s_t_r);

     Add  the  string pointed to by _s_t_r on the window at the
     current (y, x) co-ordinates.  This returns  ERR  if  it
     would  cause  the  screen to scroll illegally.  In this
     case, it will put on as much as it can.


addnstr(_c_h_a_r _*_s_t_r, _i_n_t _l_e_n);

     Add no more than _l_e_n characters of the  string  pointed
     to  by _s_t_r on the window at the current (y, x) co-ordi-
     nates.  This returns ERR if it would cause  the  screen
     to  scroll  illegally.  In this case, it will put on as
     much as it can.


assume_default_colors(_s_h_o_r_t _f_o_r_e, _s_h_o_r_t _b_a_c_k);

     Set the curses default foreground and background colors
     to _f_o_r_e and _b_a_c_k.


attr_get(_a_t_t_r___t _*_a_t_t_r, _s_h_o_r_t _*_p_a_i_r, _v_o_i_d _*_o_p_t);

     Get  the  attributes  and  colour  pair for the window.
     Either _a_t_t_r or _p_a_i_r may be NULL.  The _o_p_t  argument  is
     not used.


attr_off(_a_t_t_r___t _a_t_t_r, _v_o_i_d _*_o_p_t);

     Remove   character   attributes  set  by  attr_on()  or
     attr_set().


attr_on(_a_t_t_r___t _a_t_t_r, _v_o_i_d _*_o_p_t);

     Add character attributes for any  characters  added  to
     the window (if it has that capability).  The attributes
     that can be set are  AAAA____UUUUNNNNDDDDEEEERRRRLLLLIIIINNNNEEEE,  AAAA____RRRREEEEVVVVEEEERRRRSSSSEEEE,  AAAA____BBBBLLLLIIIINNNNKKKK,
     AAAA____DDDDIIIIMMMM,  AAAA____BBBBOOOOLLLLDDDD,  AAAA____BBBBLLLLAAAANNNNKKKK,  AAAA____PPPPRRRROOOOTTTTEEEECCCCTTTT,,,,  AAAA____AAAALLLLTTTTCCCCHHHHAAAARRRRSSSSEEEETTTT and
     CCCCOOOOLLLLOOOORRRR____PPPPAAAAIIIIRRRR((((nnnn)))).













PPPPSSSS1111::::11119999----11110000                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


attr_set(_a_t_t_r___t _a_t_t_r, _s_h_o_r_t _p_a_i_r, _v_o_i_d _*_o_p_t);

     Set character attributes and color pair for any charac-
     ters added to the window (if it has that capability).


attroff(_i_n_t _a_t_t_r_i_b_u_t_e);

     Remove   character   attributes   set  by  attron()  or
     attrset().  To  clear  all  character  attributes,  use
     attroff(_A___A_T_T_R_I_B_U_T_E_S).  attroff(_A___S_T_A_N_D_O_U_T); is equiva-
     lent to standend().  attroff(_A___U_N_D_E_R_L_I_N_E);  is  equiva-
     lent to underend().


attron(_i_n_t _a_t_t_r_i_b_u_t_e);

     Add  character  attributes  for any characters added to
     the   window   (if    it    has    that    capability).
     attron(_A___S_T_A_N_D_O_U_T);   is   equivalent   to  standout().
     attron(_A___U_N_D_E_R_L_I_N_E); is equivalent to underscore().


attrset(_i_n_t _a_t_t_r_i_b_u_t_e);

     Set character attributes for any  characters  added  to
     the window (if it has that capability).


baudrate();

     Returns  the output baud rate of the terminal.  This is
     a system dependent constant (defined in <<<<ssssyyyyssss////ttttttttyyyy....hhhh>>>>  on
     BSD systems, which is included by <<<<ccccuuuurrrrsssseeeessss....hhhh>>>>).


beep();

     Sound  the  terminal bell.  If the terminal has no bell
     capability, but has the ability to flash the screen, do
     that instead.  See also flash()


bkgd(_c_h_t_y_p_e _c_h);

     Sets the background rendition to _c_h.


bkgdset(_c_h_t_y_p_e _c_h);

     Sets  the  background  rendition to _c_h and applies this
     rendition to the window.











SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----11111111


border(_c_h_t_y_p_e _l_e_f_t, _c_h_t_y_p_e _r_i_g_h_t, _c_h_t_y_p_e _t_o_p, _c_h_t_y_p_e _b_o_t_t_o_m, _c_h_t_y_p_e _t_o_p_l_e_f_t, _c_h_t_y_p_e _t_o_p_r_i_g_h_t, _c_h_t_y_p_e _b_o_t_l_e_f_t, _c_h_t_y_p_e _b_o_t_r_i_g_h_t);

     Draws a border around the window using the  characters:
     _l_e_f_t  for  drawing the left side, _r_i_g_h_t for drawing the
     left side, _t_o_p for drawing the  top  edge,  _b_o_t_t_o_m  for
     drawing  the top edge, _t_o_p_l_e_f_t for drawing the top-left
     corner, _t_o_p_r_i_g_h_t  for  drawing  the  top-right  corner,
     _b_o_t_l_e_f_t   for   drawing  the  bottom-left  corner,  and
     _b_o_t_r_i_g_h_t  for  drawing  the  bottom-right  corner.   If
     scrolling  is  not  allowed, and the window encompasses
     the lower right-hand corner of the terminal,  the  cor-
     ners are left blank to avoid a scroll.


box(_W_I_N_D_O_W _w_i_n, _c_h_t_y_p_e _v_e_r_t, _c_h_t_y_p_e _h_o_r);

     Draws a box around the window using _v_e_r_t as the charac-
     ter for drawing the vertical sides, and _h_o_r for drawing
     the horizontal lines.  If scrolling is not allowed, and
     the window encompasses the lower right-hand  corner  of
     the  terminal,  the  corners  are left blank to avoid a
     scroll.


can_change_color();

     Check if terminal can change colors.


cbreak();

     Set the terminal to cbreak mode.


clear();

     Resets the entire  window  to  blanks.   If  _w_i_n  is  a
     screen,  this  sets  the clear flag, which will cause a
     clear-screen sequence to be sent on the next  refresh()
     call.   This also moves the current (y, x) co-ordinates
     to (0, 0).


clearok(_W_I_N_D_O_W _*_s_c_r, _i_n_t _b_o_o_l_f);

     Sets the clear flag for the screen _s_c_r.   If  _b_o_o_l_f  is
     non-zero,  this will force a clear-screen to be printed
     on the next refresh(), or stop  it  from  doing  so  if
     _b_o_o_l_f  is  0.   This only works on screens, and, unlike
     clear(), does not alter the contents of the screen.  If
     _s_c_r  is  _c_u_r_s_c_r,  the  next refresh() call will cause a
     clear-screen, even if the window passed to refresh() is
     not a screen.










PPPPSSSS1111::::11119999----11112222                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


clrtobot();

     Wipes the window clear from the current (y, x) co-ordi-
     nates to the bottom.  This  does  not  force  a  clear-
     screen  sequence  on the next refresh under any circum-
     stances.  This has no associated "mmmmvvvv" command.


clrtoeol();

     Wipes the window clear from the current (y, x) co-ordi-
     nates  to  the end of the line.  This has no associated
     "mmmmvvvv" command.


color_content(_s_h_o_r_t _c_o_l_o_r, _s_h_o_r_t _*_r_e_d, _s_h_o_r_t _*_g_r_e_e_n, _s_h_o_r_t _*_b_l_u_e);

     Get the red, green and blue values of color _c_o_l_o_r.


color_set(_s_h_o_r_t _p_a_i_r, _v_o_i_d _*_o_p_t);

     Set color pair for any characters added to  the  window
     (if it has that capability).


copywin(_c_o_n_s_t _W_I_N_D_O_W _*_s_r_c, _W_I_N_D_O_W _*_d_s_t, _i_n_t _s_m_i_n_r_o_w, _i_n_t _s_m_i_n_c_o_l, _i_n_t _d_m_i_n_r_o_w, _i_n_t _d_m_i_n_c_o_l, _i_n_t _d_m_a_x_r_o_w, _i_n_t _d_m_a_x_c_o_l);

     Copies  the  contents  of  the window _s_r_c starting at (
     _s_m_i_n_r_o_w, _s_m_i_n_c_o_l) to the destination window _d_s_t  start-
     ing at ( _d_m_i_n_r_o_w, _d_m_i_n_c_o_l) and ending at either the end
     of the source window or ( _d_m_a_x_r_o_w,  _d_m_a_x_c_o_l)  whichever
     is  the  lesser.   The parameter _o_v_e_r_l_a_y determines the
     nature of the copy.  If _o_v_e_r_l_a_y is TRUE then  only  the
     non-space  characters  from  _s_r_c are copied to _d_s_t.  If
     _o_v_e_r_l_a_y is FALSE then all characters  are  copied  from
     _s_r_c to _d_s_t_.


curs_set(_i_n_t _v_i_s_i_b_i_l_i_t_y);

     Sets  the visibility of the screen cursor.  The parame-
     ter _v_i_s_i_b_i_l_i_t_y can be one of three values, 0 means make
     the  cursor invisible, 1 means set the cursor to normal
     visibility and 2 sets the cursor  to  high  visibility.
     In  all cases the old mode of the cursor is returned if
     the call was successful and EEEERRRRRRRR is returned if the ter-
     minal cannot support the requested visibility mode.


crmode();












SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----11113333


     Identical to cbreak().  The misnamed macro crmode() and
     nocrmode() is retained for backwards compatibility with
     ealier versions of the library.


delay_output(_i_n_t _m_s);

     Pause output for _m_s milliseconds using the terminal pad
     character.


def_prog_mode();

     Save the current terminal  modes  as  the  'in  curses'
     state for use with reset_prog_mode().


def_shell_mode();

     Save  the current terminal modes as the 'not in curses'
     state for use with reset_shell_mode().


define_key(_c_h_a_r _*_s_e_q_u_e_n_c_e, _i_n_t _k_e_y___s_y_m_b_o_l);

     Assigns the character sequence given in _s_e_q_u_e_n_c_e to the
     key  symbol  _k_e_y___s_y_m_b_o_l.   If keypad() has set been set
     TRUE and the character sequence is found in  the  input
     stream  then  the  key symbol defined will be returned.
     Normally the sequences are found in the  tttteeeerrrrmmmmccccaaaapppp  data-
     base but this function allows extensions to be added by
     the application.  If _s_e_q_u_e_n_c_e is a  NULL  pointer  then
     all  the  sequences  associated with _k_e_y___s_y_m_b_o_l will be
     removed, including any definitions inserted by tttteeeerrrrmmmmccccaaaapppp.


delch();

     Delete  the  character  at  the current (y, x) co-ordi-
     nates.  Each character after it on the line  shifts  to
     the left, and the last character becomes blank.


deleteln();

     Delete  the current line.  Every line below the current
     one will move up,  and  the  bottom  line  will  become
     blank.   The  current  (y, x)  co-ordinates will remain
     unchanged.


delscreen(_S_C_R_E_E_N _*_s_c_r_e_e_n);











PPPPSSSS1111::::11119999----11114444                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


     Delete the screen and frees all associated resources.


delwin(_W_I_N_D_O_W _*_w_i_n);

     Deletes the window from existence.  All  resources  are
     freed  for  future use by ccccaaaalllllllloooocccc(3).  If a window has a
     subwin() allocated window inside of  it,  deleting  the
     outer window the subwindow is not affected, even though
     this does invalidate it.  Therefore, subwindows  should
     be deleted before their outer windows are.


derwin(_W_I_N_D_O_W _*_o_r_i_g, _i_n_t _n_l_i_n_e_s, _i_n_t _n_c_o_l_s, _i_n_t _b_y, _i_n_t _b_x);

     Performs  a  function very similar to that of subwin().
     The difference being that with derwin() the  origin  of
     the  child window given by ( _b_y, _b_x) is relative to the
     origin of the parent window _o_r_i_g instead of being abso-
     lute screen coordinates as they are in subwin().


doupdate();

     Synchronize the terminal screen with the virtual screen
     that has had window contents added to it  by  calls  to
     wnoutrefresh().


dupwin(_W_I_N_D_O_W _*_w_i_n);

     Creates an exact copy of the window _w_i_n.


echo();

     Sets the terminal to echo characters.


echochar(_c_o_n_s_t _c_h_t_y_p_e _c_h);

     Add  the  character  _c_h  on  the  window at the current
     (y, x) co-ordinates and immediately refresh the window.


endwin();

     Finish  up  window routines before exit.  This restores
     the terminal to the state it was before  initscr()  (or
     gettmode() and setterm()) was called.  It should always
     be called before exiting and before the final calls  to
     delwin().  It does not exit.  This is especially useful
     for resetting  tty  stats  when  trapping  rubouts  via










SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----11115555


     ssssiiiiggggnnnnaaaallll(2).


erase();

     Erases  the  window to blanks without setting the clear
     flag.  This is analagous to  clear(),  except  that  it
     never causes a clear-screen sequence to be generated on
     a refresh().  This has no associated "mmmmvvvv" command.


erasechar();

     Returns the erase character for the terminal, _i_._e_., the
     character  used by the user to erase a single character
     from the input.


flash();

     Flash the terminal screen.   If  the  terminal  has  no
     flash  capability,  but  has  the  ability to sound the
     bell, do that instead.  See also bell()


flushinp();

     Throw away any input that has been typed  by  the  user
     but has not yet been read by the program.


flushok(_W_I_N_D_O_W _*_w_i_n, _i_n_t _b_o_o_l_f);

     Normally,  refresh() fflush(_'_s); _s_t_d_o_u_t when it is fin-
     ished.  flushok() allows you to control this.  if _b_o_o_l_f
     is  non-zero  (_i_._e_., non-zero) it will do the fflush(),
     otherwise it will not.


getattrs(_W_I_N_D_O_W _*_w_i_n);

     Gets the attributes for _w_i_n.


getbkgd(_W_I_N_D_O_W _*_w_i_n);

     Gets the background rendition for _w_i_n.


getcap(_c_h_a_r _*_n_a_m_e);

     Get the terminal capability _n_a_m_e.











PPPPSSSS1111::::11119999----11116666                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


getch();

     Gets a character from the terminal and  (if  necessary)
     echos  it  on the window.  This returns ERR if it would
     cause the screen to scroll illegally.   Otherwise,  the
     character  gotten is returned.  If _n_o_e_c_h_o has been set,
     then the window is left unaltered.  In order to  retain
     control of the terminal, it is necessary to have one of
     _n_o_e_c_h_o, _c_b_r_e_a_k, or _r_a_w_m_o_d_e set.  If you do not set one,
     whatever  routine  you call to read characters will set
     _c_b_r_e_a_k for you, and then reset  to  the  original  mode
     when finished.


getcury(_W_I_N_D_O_W _*_w_i_n);

     Get current y position on _w_i_n.


getcurx(_W_I_N_D_O_W _*_w_i_n);

     Get current x position on _w_i_n.


getbegy(_W_I_N_D_O_W _*_w_i_n);

     Get start y position on _w_i_n.


getbegx(_W_I_N_D_O_W _*_w_i_n);

     Get start x position on _w_i_n.


getmaxy(_W_I_N_D_O_W _*_w_i_n);

     Get maximum y position on _w_i_n.


getmaxx(_W_I_N_D_O_W _*_w_i_n);

     Get maximum x position on _w_i_n.


getnstr(_c_h_a_r _*_s_t_r);

     Get a string through the window and put it in the loca-
     tion pointed to by _s_t_r.  A maximum of _n  characters  is
     returned  (including  the  trailing null).  It sets tty
     modes  if  necessary,  and  then  calls   getch()   (or
     wgetch())  to  get the characters needed to fill in the
     string until a newline or EOF is encountered.  The new-
     line  stripped  off the string.  This returns ERR if it










SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----11117777


     would cause the screen to scroll illegally.


getstr(_c_h_a_r _*_s_t_r);

     Get a string through the window and put it in the loca-
     tion  pointed  to  by _s_t_r, which is assumed to be large
     enough to handle it.  It sets tty modes  if  necessary,
     and then calls getch() (or wgetch()) to get the charac-
     ters needed to fill in the string until  a  newline  or
     EOF  is  encountered.   The  newline  stripped  off the
     string.  This returns ERR if it would cause the  screen
     to scroll illegally.


getparx(_W_I_N_D_O_W _*_w_i_n);

     Returns  the x location of the given subwindow relative
     to the parent window.  If the window is not a subwindow
     then -1 is returned.


getpary(_W_I_N_D_O_W _*_w_i_n);

     Returns  the y location of the given subwindow relative
     to the parent window.  If the window is not a subwindow
     then -1 is returned.


getpary(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x);

     Is  a  macro  that  sets  the _y and _x parameters to the
     respective coordinates of the top left hand  corner  of
     the  subwindow  relative  to the parent window.  If the
     given window _w_i_n is not a subwindow then both _y  and  _x
     will be set to -1.


gettmode();

     Get   the  tty  stats.   This  is  normally  called  by
     initscr().


getwin(_F_I_L_E _*_f_p);

     Creates a window from a file written by putwin().


getyx(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x);

     Puts the current (y, x)  co-ordinates  of  _w_i_n  in  the
     variables  _y  and  _x.   Since  it  is  a  macro,  not a










PPPPSSSS1111::::11119999----11118888                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


     function, you do not pass the address of _y and _x.


halfdelay(_i_n_t _t_i_m_e_o_u_t);

     Sets the terminal into a mode similar to that  done  by
     cbreak()  with  the  exception  that the input routines
     will wait for _t_i_m_e_o_u_t number of tenths of a second,  if
     at  this  time  there  is  no  input  then  ERR will be
     returned.


has_colors();

     Check if terminal has colors.


hline(_c_h_t_y_p_e _c_h, _i_n_t _c_o_u_n_t);

     Draw a horizontal line of the character ch starting  at
     the  current  cursor  position  and  moving towards the
     rightmost column.  At most  _c_o_u_n_t  characters  will  be
     written,  less  if  the  edge  of the screen is reached
     before _c_o_u_n_t is reached.


idcok(_W_I_N_D_O_W _*_w_i_n, _i_n_t _b_o_o_l_f);

     Reserved for future use.  This will  eventually  signal
     to refresh() that it is all right to use the insert and
     delete char sequences when updating the window.


idlok(_W_I_N_D_O_W _*_w_i_n, _i_n_t _b_o_o_l_f);

     Reserved for future use.  This will  eventually  signal
     to refresh() that it is all right to use the insert and
     delete line sequences when updating the window.


inch();

     Returns the character at the current  position  on  the
     given  window.   This  does not make any changes to the
     window.


inchnstr(_c_h_t_y_p_e _*_c_h_s_t_r, _i_n_t _n);

     Get an array of at most  _n  characters  and  renditions
     starting  at  the current cursor position and ending at
     the end of the line and put it in the location  pointed
     to by _c_h_s_t_r.










SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----11119999


inchstr(_c_h_t_y_p_e _*_c_h_s_t_r);

     Get  an  array of characters and renditions starting at
     the current cursor position and ending at  the  end  of
     the  line  and  put  it  in  the location pointed to by
     _c_h_s_t_r, which is assumed to be large  enough  to  handle
     it.


innstr(_c_h_a_r _*_s_t_r, _i_n_t _n);

     Get  a  string  of at most _n characters starting at the
     current cursor position and ending at the  end  of  the
     line and put it in the location pointed to by _s_t_r.


init_color(_s_h_o_r_t _c_o_l_o_r, _s_h_o_r_t _r_e_d, _s_h_o_r_t _g_r_e_e_n, _s_h_o_r_t _b_l_u_e);

     Set the red, green and blue values of color _c_o_l_o_r.


init_pair(_s_h_o_r_t _p_a_i_r, _s_h_o_r_t _f_o_r_e, _s_h_o_r_t _b_a_c_k);

     Set  the foreground and background colors of pair _p_a_i_r.


initscr();

     Initialize the screen routines.  This  must  be  called
     before  any  of  the screen routines are used.  It ini-
     tializes the terminal-type data and such,  and  without
     it none of the routines can operate.  If standard input
     is not a tty, it sets the specifications to the  termi-
     nal  whose  name  is  pointed to by _D_e_f___t_e_r_m (initially
     "dumb").  If the boolean _M_y___t_e_r_m is non-zero,  _D_e_f___t_e_r_m
     is  always used.  If the system supports the TTTTIIIIOOOOCCCCGGGGWWWWIIIINNNNSSSSZZZZ
     _i_o_c_t_l_(_2_) call, it is used to get the  number  of  lines
     and  columns  for  the  terminal, otherwise it is taken
     from the tttteeeerrrrmmmmccccaaaapppp description.


insch(_c_h_a_r _c);

     Insert _c at the current (y, x) co-ordinates Each  char-
     acter  after it shifts to the right, and the last char-
     acter disappears.  This returns ERR if it  would  cause
     the screen to scroll illegally.


insdelln(_i_n_t _n);

     If  _n is positive insert _n lines above the current one.
     Every line below the current line will be shifted down,










PPPPSSSS1111::::11119999----22220000                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


     and the last _n lines will disappear.  If _n is negative,
     delete _n lines starting from the current one.  The last
     _n  lines  are cleared.  The current (y, x) co-ordinates
     will remain unchanged.


insertln();

     Insert a line above the current one.  Every line  below
     the  current  line will be shifted down, and the bottom
     line will disappear.   The  current  line  will  become
     blank,  and the current (y, x) co-ordinates will remain
     unchanged.


instr(_c_h_a_r _*_s_t_r);

     Get an string starting at the current  cursor  position
     and  ending  at  the  end of the line and put it in the
     location pointed to by _s_t_r,  which  is  assumed  to  be
     large enough to handle it.


is_linetouched(_W_I_N_D_O_W _*_w_i_n, _i_n_t _l_i_n_e);

     Returns  TRUE  if _l_i_n_e in the window _w_i_n has been modi-
     fied since the last call to wrefresh().


is_wintouched(_W_I_N_D_O_W _*_w_i_n, _i_n_t _l_i_n_e);

     Returns TRUE if the window _w_i_n has been modified  since
     the last call to wrefresh().


isendwin();

     Returns TRUE if endwin() has been called without a sub-
     sequent call to wrefresh(), and FALSE otherwise.


intrflush(_W_I_N_D_O_W _*_w_i_n, _i_n_t _b_o_o_l_f);

     Sets the terminal flush on interrupt mode.  If _b_o_o_l_f is
     non-zero, flushing of the output buffer will occur when
     an interrupt key is pressed.  The default is  inherited
     from the terminal settings.


keyok(_i_n_t _k_e_y___s_y_m_b_o_l, _b_o_o_l _f_l_a_g);

     Controls  the recognition of the key symbol _k_e_y___s_y_m_b_o_l.
     By  setting  _f_l_a_g  to  FALSE  the  recognition  of  any










SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----22221111


     sequence  of  characters that have been associated with
     the key symbol will be disabled.  By default, this flag
     is TRUE so sequences will be recognised.


keyname(_i_n_t _k_e_y);

     Returns a description of the key _k_e_y.


keypad(_W_I_N_D_O_W _*_w_i_n, _i_n_t _b_o_o_l_f);

     Sets  the  boolean  flag  for  interpretation of escape
     sequences.  If _b_o_o_l_f is non-zero, escape sequences from
     terminal  keypad  and function keys will be interpreted
     by the library.  Escape sequences are  not  interpreted
     by  default.   The include file <<<<ccccuuuurrrrsssseeeessss....hhhh>>>> contains the
     list of recognised keypad and function keys.  See  also
     notimeout().


killchar();

     Returns the line kill character for the terminal, _i_._e_.,
     the character used by the user to erase an entire  line
     from the input.


leaveok(_W_I_N_D_O_W _*_w_i_n, _i_n_t _b_o_o_l_f);

     Sets  the boolean flag for leaving the cursor after the
     last change.  If _b_o_o_l_f is non-zero, the cursor will  be
     left  after  the  last  update on the terminal, and the
     current (y, x) co-ordinates for  _w_i_n  will  be  changed
     accordingly.  If _b_o_o_l_f
      is  0  the  cursor will be moved to the current (y, x)
     co-ordinates.  This  flag  (initially  0)  retains  its
     value until changed by the user.


longname();

     Returns  a string containing the verbose description of
     the terminal.


meta(_W_I_N_D_O_W _*_w_i_n, _b_o_o_l _b_f);

     Manipulates the meta mode  on  terminals  that  support
     this capability.  Note that _w_i_n is always ignored.













PPPPSSSS1111::::11119999----22222222                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


move(_i_n_t _y, _i_n_t _x);

     Change the current (y, x) co-ordinates of the window to
     (_y_, _x).  This returns ERR if it would cause the  screen
     to scroll illegally.


mvaddch(_i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _c_h);

     Moves the cursor to the position _(_y, _x) and then adds a
     character in the same manner as addch().


mvaddchstr(_i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _*_s_t_r);

     Moves the cursor to the position _(_y, _x) and  then  adds
     characters  and attributes in the same manner as addch-
     str().


mvaddchnstr(_i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _*_s_t_r);

     Moves the cursor to the position _(_y, _x) and  then  adds
     characters and attributes in the same manner as addchn-
     str().


mvaddstr(_i_n_t _y, _i_n_t _x, _c_h_a_r _*_s_t_r);

     Moves the cursor to the position _(_y, _x) and then adds a
     string in the same manner as addstr().


mvaddnstr(_i_n_t _y, _i_n_t _x, _c_h_a_r _*_s_t_r);

     Moves the cursor to the position _(_y, _x) and then adds a
     string in the same manner as addnstr().


mvcur(_i_n_t _l_a_s_t_y, _i_n_t _l_a_s_t_x, _i_n_t _n_e_w_y, _i_n_t _n_e_w_x);

     Moves the  terminal's  cursor  from  (_l_a_s_t_y_, _l_a_s_t_x)  to
     (_n_e_w_y_, _n_e_w_x)  in  an  approximation of optimal fashion.
     This routine uses the functions borrowed from  _e_x  ver-
     sion  2.6.   It  is  possible  to use this optimization
     without the benefit of the screen routines.   With  the
     screen routines, this should not be called by the user.
     move() and refresh() should be used to move the  cursor
     position, so that the routines know what's going on.


mvderwin(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x);











SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----22223333


     Moves  the  subwindow  _w_i_n to the location (_y_, _x) where
     the location is relative to the top left hand corner of
     the parent window.  This call will return ERR if _w_i_n is
     not a subwindow or if the relocated  window  would  lie
     outside the parent window.


mvhline(_i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _c_h, _i_n_t _c_o_u_n_t);

     Moves  the cursor to the position _(_y, _x) and then draws
     a horizontal line in the same manner as hline().


mvprintw(_i_n_t _y, _i_n_t _x, _c_o_n_s_t _c_h_a_r _*_f_m_t, _._._.);

     Equivalent to:

         move(y, x);
         printw(fmt, ...);



mvscanw(_i_n_t _y, _i_n_t _x, _c_o_n_s_t _c_h_a_r _*_f_m_t, _._._.);

     Equivalent to:

         move(y, x);
         scanw(fmt, ...);



mvvline(_i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _c_h, _i_n_t _c_o_u_n_t);

     Moves the cursor to the position _(_y, _x) and then  draws
     a vertical line in the same manner as vline().


mvwhline(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _c_h, _i_n_t _c_o_u_n_t);

     Moves  the  cursor to the position _(_y, _x) on window _w_i_n
     and then draws a horizontal line in the same manner  as
     whline().


mvwvline(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _c_h, _i_n_t _c_o_u_n_t);

     Moves  the  cursor to the position _(_y, _x) on window _w_i_n
     and then draws a horizontal line in the same manner  as
     wvline().


mvwin(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x);











PPPPSSSS1111::::11119999----22224444                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


     Move  the home position of the window _w_i_n from its cur-
     rent starting coordinates to (_y_, _x).  If that would put
     part  or all of the window off the edge of the terminal
     screen, mvwin() returns ERR and does  not  change  any-
     thing.  For subwindows, mvwin() also returns ERR if you
     attempt to move it off its main window.  If you move  a
     main window, all subwindows are moved along with it.


mvwprintw(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_o_n_s_t _c_h_a_r _*_f_m_t, _._._.);

     Equivalent to:

         wmove(win, y, x);
         printw(fmt, ...);



mvwscanw(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_o_n_s_t _c_h_a_r _*_f_m_t, _._._.);

     Equivalent to:

         wmove(win, y, x);
         scanw(fmt, ...);



napms(_i_n_t _m_s);

     Sleep for _m_s milliseconds.


newpad(_i_n_t _l_i_n_e_s, _i_n_t _c_o_l_s);

     Create a new pad with _l_i_n_e_s lines and _c_o_l_s columns.


newterm(_c_h_a_r _*_t_y_p_e, _F_I_L_E _*_o_u_t_f_d, _F_I_L_E _*_i_n_f_d);

     Iinitialise the curses subsystem to use the terminal of
     type _t_y_p_e connected via the input  and  output  streams
     _i_n_f_d_,_o_u_t_f_d_.   The  newterm()  is used in multi-terminal
     applications and returns a pointer to a structure  that
     holds  the  state  for  that  particular terminal.  The
     application may swap between the terminals  by  calling
     the set_term() function.  If the _t_y_p_e parameter is NULL
     then the $TERM variable is used as the terminal type.


newwin(_i_n_t _l_i_n_e_s, _i_n_t _c_o_l_s, _i_n_t _b_e_g_i_n___y, _i_n_t _b_e_g_i_n___x);

     Create a new window with _l_i_n_e_s lines and  _c_o_l_s  columns
     starting  at  position  (_b_e_g_i_n___y_, _b_e_g_i_n___x).   If either










SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----22225555


     _l_i_n_e_s or _c_o_l_s is 0 (zero), that dimension will  be  set
     to  (_L_I_N_E_S _- _b_e_g_i_n___y) or (_C_O_L_S _- _b_e_g_i_n___x) respectively.
     Thus, to get a new window of dimensions _L_I_N_E_S  x  _C_O_L_S,
     use newwin(_0, _0, _0, _0).


nl();

     Set  the terminal to nl mode, _i_._e_., start/stop the sys-
     tem from mapping <<<<RRRREEEETTTTUUUURRRRNNNN>>>> to <<<<LLLLIIIINNNNEEEE----FFFFEEEEEEEEDDDD>>>>.  If the  map-
     ping  is  not done, refresh() can do more optimization,
     so it is recommended, but not required, to turn it off.


no_color_video();

     Return attributes that cannot be combined with color.


nocbreak();

     Unset the terminal from cbreak mode.


nocrmode();

     Identical to nocbreak().  The misnamed macro nocrmode()
     is retained for  backwards  compatibility  with  ealier
     versions of the library.


nodelay(_W_I_N_D_O_W _*_w_i_n_1, _i_n_t _b_o_o_l_f);

     Sets  the  boolean  flag  for non-blocking getch().  If
     _b_o_o_l_f is non-zero, getch() will return ERR is no  input
     is  waiting.   The  default  is to for getch() to block
     indefinitely.  See also timeout().


noecho();

     Turn echoing of characters off.


nonl();

     Unset the terminal to from nl mode.  See nl().


noqiflush();

     Unset the terminal flush on interrupt  mode.   This  is
     equivalent to intrflush(_s_t_d_s_c_r, _F_A_L_S_E).










PPPPSSSS1111::::11119999----22226666                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


noraw();

     Unset the terminal from raw mode.  See raw().


notimeout(_W_I_N_D_O_W _*_w_i_n_1, _i_n_t _b_o_o_l_f);

     Sets the boolean flag for inter-key timeouts for escape
     sequences  interpreted  when  keypad()  is   set.    By
     default,  keypad()  sets  a timer while waiting for the
     next character of an escape sequence.  If _b_o_o_l_f is non-
     zero,  getch()  will  wait  indefinitely between escape
     sequence characters, or until a delay set by  timeout()
     expires.


overlay(_W_I_N_D_O_W _*_w_i_n_1, _W_I_N_D_O_W _*_w_i_n_2);

     Overlay _w_i_n_1 on _w_i_n_2.  The contents of _w_i_n_1, insofar as
     they fit, are placed on _w_i_n_2 at their  starting  (y, x)
     co-ordinates.   This  is  done non-destructively, i.e.,
     blanks on _w_i_n_1 leave the contents of the space on  _w_i_n_2
     untouched.   Note  that  all  non-blank  characters are
     overwritten destructively in the overlay.


overwrite(_W_I_N_D_O_W _*_w_i_n_1, _W_I_N_D_O_W _*_w_i_n_2);

     Overwrite _w_i_n_1 on _w_i_n_2.  The contents of _w_i_n_1,  insofar
     as  they  fit,  are  placed  on  _w_i_n_2 at their starting
     (y, x) co-ordinates.  This is done destructively, _i_._e_.,
     blanks on _w_i_n_1 become blank on _w_i_n_2.


pair_content(_s_h_o_r_t _p_a_i_r, _s_h_o_r_t _*_f_o_r_e, _s_h_o_r_t _*_b_a_c_k);

     Get  the foreground and background colors of pair _p_a_i_r.


pechochar(_c_o_n_s_t _c_h_t_y_p_e _c_h);

     Add the character _c_h on the pad at the  current  (y, x)
     co-ordinates and immediately refresh the pad.


pnoutrefresh(_W_I_N_D_O_W _*_p_a_d, _i_n_t _p_b_e_g___y, _i_n_t _p_b_e_g___x, _i_n_t _s_b_e_g___y, _i_n_t _s_b_e_g___x, _i_n_t _s_m_a_x___y, _i_n_t _s_m_a_x___x);

     Add the pad contents to a virtual screen.  Several pads
     can be added before a call to doupdate(), thus allowing
     the screen to updated in an efficient manner.













SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----22227777


prefresh(_W_I_N_D_O_W _*_p_a_d, _i_n_t _p_b_e_g___y, _i_n_t _p_b_e_g___x, _i_n_t _s_b_e_g___y, _i_n_t _s_b_e_g___x, _i_n_t _s_m_a_x___y, _i_n_t _s_m_a_x___x);

     Synchronize the terminal screen with the desired pad.


printw(_c_h_a_r _*_f_m_t, _._._.);

     Performs  a printf() on the window starting at the cur-
     rent (y, x) co-ordinates.  It uses addstr() to add  the
     string on the window.  It is often advisable to use the
     field width options of printf() to avoid leaving things
     on  the window from earlier calls.  This returns ERR if
     it would cause the screen to scroll illegally.


putwin(_W_I_N_D_O_W _*_w_i_n, _F_I_L_E _*_f_p);

     Writes the window data to a file.


qiflush();

     Set the terminal flush  on  interrupt  mode.   This  is
     equivalent to intrflush(_s_t_d_s_c_r, _T_R_U_E).


raw();

     Set  the terminal to raw mode.  On version 7 UUUUNNNNIIIIXXXX2222 this
     also turns off newline mapping (see nl()).


redrawwin(_W_I_N_D_O_W _*_w_i_n);

     Mark the entire window as having been corrupted.   This
     is equivalent to the touchwin() function.


refresh();

     Synchronize  the  terminal screen with the desired win-
     dow.  If the window is not a  screen,  only  that  part
     covered by it is updated.  This returns ERR if it would
     cause the screen to scroll illegally.  In this case, it
     will update whatever it can without causing the scroll.

     As a special case, if wrefresh()  is  called  with  the
     window _c_u_r_s_c_r the screen is cleared and repainted as it
     is currently.  This is very  useful  for  allowing  the
____________________
   2 UUUUNNNNIIIIXXXX is a trademark of Unix System Laboratories.












PPPPSSSS1111::::11119999----22228888                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


     redrawing  of  the  screen  when  the  user has garbage
     dumped on his terminal.


reset_prog_mode();

     Restore the terminal to the 'in curses' state.


reset_shell_mode();

     Restore the terminal to the 'not in curses' state.


resetty();

     resetty()  restores  them  to  what  savetty()  stored.
     These   functions   are   performed   automatically  by
     initscr() and endwin().  This function  should  not  be
     used by the user.


resizeterm(_i_n_t _l_i_n_e_s, _i_n_t _c_o_l_u_m_n_s);

     Resizes  the  curses  terminal  to the given size.  All
     internal curses  structures  are  resized  to  the  new
     dimensions  and  all  curses  windows  that  would have
     boundaries  outside  the  new  terminal  size  will  be
     resized  to fit within the new boundaries.  All windows
     will be cleared and it is expected that the application
     will redraw the window contents.


savetty();

     savetty()  saves  the current tty characteristic flags.
     See resetty().  This function should not be used by the
     user.


scanw(_c_h_a_r _*_f_m_t, _._._.);

     Perform  a  scanf()  through  the window using _f_m_t.  It
     does  this  using  consecutive  calls  to  getch()  (or
     wgetch()).   This  returns  ERR  if  it would cause the
     screen to scroll illegally.


scrl(_i_n_t _n);

     Scroll the window by _n lines. If _n is positive,  scroll
     upward, otherwise scroll downward.











SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----22229999


scroll(_W_I_N_D_O_W _*_w_i_n);

     Scroll  the  window  upward one line.  This is normally
     not used by the user.


scrollok(_W_I_N_D_O_W _*_w_i_n, _i_n_t _b_o_o_l_f);

     Set the scroll flag for the given window.  If _b_o_o_l_f  is
     0,  scrolling is not allowed.  This is its default set-
     ting.


set_term(_S_C_R_E_E_N _*_n_e_w);

     Sets the current screen for input and output to be  the
     one given.  The _n_e_w structure must be one that has been
     previously created  by  the  newterm()  function.   The
     set_term() function returns the previous screen on suc-
     cessful completion.


standend();

     End standout mode initiated by standout().  This  func-
     tion  is  provided  for compatibility with older curses
     implementations.


standout();

     Causes any characters added to the window to be put  in
     standout  mode on the terminal (if it has that capabil-
     ity).  This function is provided for compatibility with
     older  curses implementations.  A larger range of char-
     acter attributes supported by modern terminals  can  be
     accessed using attron() and attrset().


start_color();

     Initialize  the  color  routines.   This must be called
     before any of the color routines are used.  The  termi-
     nal  is setup to use the curses default colors of white
     foreground     on     black     background,      unless
     assume_default_colors()   or  use_default_colors()  are
     called.


subpad(_W_I_N_D_O_W _*_w_i_n, _i_n_t _l_i_n_e_s, _i_n_t _c_o_l_s, _i_n_t _b_e_g_i_n___y, _i_n_t _b_e_g_i_n___x);

     Create a new pad with  _l_i_n_e_s  lines  and  _c_o_l_s  columns
     starting  at position (_b_e_g_i_n___y_, _b_e_g_i_n___x) inside the pad










PPPPSSSS1111::::11119999----33330000                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


     _w_i_n.  This means that any change made to either pad  in
     the  area  covered  by  the subpad will be made on both
     pads.  _b_e_g_i_n___y_, _b_e_g_i_n___x are specified relative  to  the
     relative (0, 0) of _w_i_n.


subwin(_W_I_N_D_O_W _*_w_i_n, _i_n_t _l_i_n_e_s, _i_n_t _c_o_l_s, _i_n_t _b_e_g_i_n___y, _i_n_t _b_e_g_i_n___x);

     Create  a  new window with _l_i_n_e_s lines and _c_o_l_s columns
     starting at position (_b_e_g_i_n___y_, _b_e_g_i_n___x) inside the win-
     dow  _w_i_n.   This  means  that any change made to either
     window in the area covered by  the  subwindow  will  be
     made  on  both windows.  _b_e_g_i_n___y_, _b_e_g_i_n___x are specified
     relative to the overall screen, not the relative (0, 0)
     of  _w_i_n.   If  either  _l_i_n_e_s  or _c_o_l_s is 0 (zero), that
     dimension will be set to (_L_I_N_E_S _- _b_e_g_i_n___y) or  (_C_O_L_S  _-
     _b_e_g_i_n___x) respectively.


termattrs();

     Returns  the  attributes  that  can  be  applied to the
     screen.


term_attrs();

     Returns the wide attributes that can be applied to  the
     screen.


timeout(_i_n_t _d_e_l_a_y);

     Sets  blocking  or  non-blocking  getch().  If _d_e_l_a_y is
     positive, getch() will  block  for  _d_e_l_a_y  milliseconds
     before  returning.   If  _d_e_l_a_y  is  zero,  getch() will
     return ERR is no input is waiting.  If _d_e_l_a_y  is  nega-
     tive,  getch()  will block indefinitely.  See also key-
     pad(), nodelay() and notimeout().


touchline(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _s_t_a_r_t_x, _i_n_t _e_n_d_x);

     This function performs a function similar to touchwin()
     on  a  single  line.  It marks the first change for the
     given line to be _s_t_a_r_t_x, if it is  before  the  current
     first  change  mark, and the last change mark is set to
     be _e_n_d_x if it is currently less than _e_n_d_x.


touchoverlap(_W_I_N_D_O_W _*_w_i_n_1, _W_I_N_D_O_W _*_w_i_n_2);












SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----33331111


     Touch the window _w_i_n_2 in the area which  overlaps  with
     _w_i_n_1.  If they do not overlap, no changes are made.


touchwin(_W_I_N_D_O_W _*_w_i_n);

     Make  it  appear  that the every location on the window
     has been changed.  This  is  usually  only  needed  for
     refreshes with overlapping windows.


tstp()

     This  function will save the current tty state and then
     put the  process  to  sleep.   When  the  process  gets
     restarted,  it  restores  the  saved tty state and then
     calls   wrefresh(_c_u_r_s_c_r);   to   redraw   the   screen.
     Initscr()  sets the signal SIGTSTP to trap to this rou-
     tine.


unctrl(_c_h_a_r _*_c_h);

     Returns a string which is an  ASCII  representation  of
     _c_h.  Characters are 8 bits long.


unctrllen(_c_h_a_r _*_c_h);

     Returns the length of the ASCII representation of _c_h.


underend();

     End underscore mode initiated by underscore().  This is
     equivalent to attroff(_A___U_N_D_E_R_L_I_N_E).


underscore();

     Causes any characters added to the window to be put  in
     underscore  mode  on the terminal (if it has that capa-
     bility).  This is equivalent to attron(_A___U_N_D_E_R_L_I_N_E).


ungetch(_i_n_t _c);

     Places the contents of _c converted to a character  back
     into  the input queue.  Only one character of push back
     before a subsequent call  to  getch()  or  wgetch()  is
     guaranteed  to  function  correctly.   The  results  of
     attempting more than one  character  of  push  back  is
     undefined.










PPPPSSSS1111::::11119999----33332222                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


untouchwin(_W_I_N_D_O_W _*_w_i_n);

     Make the window appear to have not been updated even if
     it has been.


use_default_colors();

     Use the terminal foreground and  background  colors  as
     the curses default foreground and background colors.


vline(_c_h_t_y_p_e _c_h, _i_n_t _c_o_u_n_t);

     Draws  a  vertical line of character _c_h starting at the
     current cursor location and moving towards  the  bottom
     of  the  screen.   At  most _c_o_u_n_t characters are drawn,
     less if the bottom of  the  screen  is  reached  before
     _c_o_u_n_t expires.


vwprintw(_W_I_N_D_O_W _*_w_i_n, _c_o_n_s_t _c_h_a_r _*_f_m_t, _v_a___l_i_s_t _a_p);

     Identical  to printw() except that it takes both a win-
     dow specification and a pointer to  a  variable  length
     argument list.


vwscanw(_W_I_N_D_O_W _*_w_i_n, _c_o_n_s_t _c_h_a_r _*_f_m_t, _v_a___l_i_s_t _a_p);

     Identical to scanw() except that it takes both a window
     specification and a pointer to a variable length  argu-
     ment list.


wnoutrefresh(_W_I_N_D_O_W _*_w_i_n);

     Add  the  window contents to a virtual screen.  Several
     windows can be added before a call to doupdate(),  thus
     allowing  the screen to updated in an efficient manner.


wredrawln(_W_I_N_D_O_W _*_w_i_n, _i_n_t _l_i_n_e, _i_n_t _n);

     Mark _n lines starting at _l_i_n_e in  the  window  as  cor-
     rupted.   This  is equivalent to wtouchln(_w_i_n, _l_i_n_e, _n,
     _1).


wresize(_W_I_N_D_O_W _*_w_i_n, _i_n_t _l_i_n_e_s, _i_n_t _c_o_l_u_m_n_s);

     Resize the specified window to  the  given  dimensions.
     The  window  will  be  cleared  and  the application is










SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----33333333


     expected to redraw the window contents.


wtouchln(_W_I_N_D_O_W _*_w_i_n, _i_n_t _l_i_n_e, _i_n_t _n, _i_n_t _c_h_a_n_g_e_d);

     If _c_h_a_n_g_e_d is 1 then _n lines starting at  _l_i_n_e  in  the
     window  are  touched.   If  _c_h_a_n_g_e_d  is  0 then _n lines
     starting at _l_i_n_e in the window are untouched.



     _T_h_e _f_o_l_l_o_w_i_n_g _f_u_n_c_t_i_o_n_s _d_i_f_f_e_r _f_r_o_m _t_h_e _s_t_a_n_d_a_r_d  _f_u_n_c_-
_t_i_o_n_s  _o_n_l_y  _i_n _t_h_e_i_r _s_p_e_c_i_f_i_c_a_t_i_o_n _o_f _a _w_i_n_d_o_w_, _r_a_t_h_e_r _t_h_a_n
_t_h_e _u_s_e _o_f _t_h_e _d_e_f_a_u_l_t _s_t_d_s_c_r_.


waddbytes(_W_I_N_D_O_W _*_w_i_n, _c_h_a_r_* _s_t_r, _i_n_t _l_e_n);
waddch(_W_I_N_D_O_W _*_w_i_n, _c_h_t_y_p_e _c_h);
waddchnstr(_W_I_N_D_O_W _*_w_i_n, _c_h_t_y_p_e _*_s_t_r, _i_n_t _l_e_n);
waddchstr(_W_I_N_D_O_W _*_w_i_n, _c_h_t_y_p_e _*_s_t_r, _i_n_t _l_e_n);
waddnstr(_W_I_N_D_O_W _*_w_i_n, _c_h_a_r _*_s_t_r, _i_n_t _l_e_n);
waddstr(_W_I_N_D_O_W _*_w_i_n, _c_h_a_r _*_s_t_r);
wattroff(_W_I_N_D_O_W _*_w_i_n, _i_n_t _a_t_t_r);
wattron(_W_I_N_D_O_W _*_w_i_n, _i_n_t _a_t_t_r);
wattrset(_W_I_N_D_O_W _*_w_i_n, _i_n_t _a_t_t_r);
wbkgd(_W_I_N_D_O_W _*_w_i_n, _c_h_t_y_p_e _c_h);
wbkgdset(_W_I_N_D_O_W _*_w_i_n, _c_h_t_y_p_e _c_h);
wborder(_W_I_N_D_O_W _*_w_i_n, _c_h_t_y_p_e _l_e_f_t, _c_h_t_y_p_e _r_i_g_h_t, _c_h_t_y_p_e _t_o_p, _c_h_t_y_p_e _b_o_t_t_o_m, _c_h_t_y_p_e _t_o_p_l_e_f_t, _c_h_t_y_p_e _t_o_p_r_i_g_h_t, _c_h_t_y_p_e _b_o_t_l_e_f_t);
wclear(_W_I_N_D_O_W _*_w_i_n);
wclrtobot(_W_I_N_D_O_W _*_w_i_n);
wclrtoeol(_W_I_N_D_O_W _*_w_i_n);
wdelch(_W_I_N_D_O_W _*_w_i_n);
wdeleteln(_W_I_N_D_O_W _*_w_i_n);
wechochar(_W_I_N_D_O_W _*_w_i_n, _c_h_t_y_p_e _c_h);
werase(_W_I_N_D_O_W _*_w_i_n);
wgetch(_W_I_N_D_O_W _*_w_i_n);
wgetnstr(_W_I_N_D_O_W _*_w_i_n, _c_h_a_r _*_s_t_r, _i_n_t _l_e_n);
wgetstr(_W_I_N_D_O_W _*_w_i_n, _c_h_a_r _*_s_t_r);
whline(_W_I_N_D_O_W _*_w_i_n, _c_h_t_y_p_e _c_h, _i_n_t _c_o_u_n_t);
winch(_W_I_N_D_O_W _*_w_i_n);
winchnstr(_W_I_N_D_O_W _*_w_i_n, _c_h_t_y_p_e _*_c_h_s_t_r, _i_n_t _n);
winchstr(_W_I_N_D_O_W _*_w_i_n, _c_h_t_y_p_e _*_c_h_s_t_r);
winnstr(_W_I_N_D_O_W _*_w_i_n, _c_h_a_r _*_s_t_r, _i_n_t _n);
winsch(_W_I_N_D_O_W _*_w_i_n, _c_h_a_r _c);
winsdelln(_W_I_N_D_O_W _*_w_i_n, _i_n_t _n);
winsertln(_W_I_N_D_O_W _*_w_i_n);
winstr(_W_I_N_D_O_W _*_w_i_n, _c_h_a_r _*_s_t_r);
wmove(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t, _x_");
wprintw(_W_I_N_D_O_W _*_w_i_n, _c_h_a_r _*_f_m_t, _._._.);
wrefresh(_W_I_N_D_O_W _*_w_i_n);
wscanw(_W_I_N_D_O_W _*_w_i_n, _c_h_a_r _*_f_m_t, _._._.);
wscrl(_W_I_N_D_O_W _*_w_i_n, _i_n_t _n);
wstandend(_W_I_N_D_O_W _*_w_i_n);










PPPPSSSS1111::::11119999----33334444                                     SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee


wstandout(_W_I_N_D_O_W _*_w_i_n);
wtimeout(_W_I_N_D_O_W _*_w_i_n, _i_n_t _d_e_l_a_y);
wunderend(_W_I_N_D_O_W _*_w_i_n);
wunderscore(_W_I_N_D_O_W _*_w_i_n);
wvline(_W_I_N_D_O_W _*_w_i_n, _c_h_t_y_p_e _c_h, _i_n_t _c_o_u_n_t);
mvwaddch(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _c_h);
mvwaddchstr(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _*_s_t_r);
mvwaddchnstr(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _*_s_t_r);
mvwaddnstr(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_h_a_r _*_s_t_r, _i_n_t _l_e_n);
mvwaddstr(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_h_a_r _*_s_t_r);
mvwgetnstr(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_h_a_r _*_s_t_r, _i_n_t _l_e_n);
mvwgetstr(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_h_a_r _*_s_t_r);
mvwhline(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _c_h, _i_n_t _c_o_u_n_t);
mvwvline(_W_I_N_D_O_W _*_w_i_n, _i_n_t _y, _i_n_t _x, _c_h_t_y_p_e _c_h, _i_n_t _c_o_u_n_t);

















































SSSSccccrrrreeeeeeeennnn PPPPaaaacccckkkkaaaaggggeeee                                     PPPPSSSS1111::::11119999----33335555


1111....  EEEExxxxaaaammmmpppplllleeeessss

     Here we present a few examples of how to use the  pack-
age.   They attempt to be representative, though not compre-
hensive.  Further examples can be found in the games section
of  the  source  tree  and in various utilities that use the
screen such as _s_y_s_t_a_t_(_1_).

     The following examples are intended to demonstrate  the
basic  structure  of  a program using the package.  An addi-
tional, more comprehensive, program  can  be  found  in  the
source code in the _e_x_a_m_p_l_e_s subdirectory.

1111....1111....  SSSSiiiimmmmpppplllleeee CCCChhhhaaaarrrraaaacccctttteeeerrrr OOOOuuuuttttppppuuuutttt

     This  program  demonstrates  how to set up a window and
output characters to it.   Also,  it  demonstrates  how  one
might  control  the  output  to the window.  If you run this
program, you will get a demonstration of the character  out-
put  chracteristics  discussed in the above Character Output
section.

    _#_i_n_c_l_u_d_e <sys_/types.h>
    _#_i_n_c_l_u_d_e <curses.h>
    _#_i_n_c_l_u_d_e <stdio.h>
    _#_i_n_c_l_u_d_e <signal.h>


    _#_d_e_f_i_n_e YSIZE 10
    _#_d_e_f_i_n_e XSIZE 20

    _i_n_t quit();

    main()
    _{
               _i_n_t i, j, c;
               size_t len;
               _c_h_a_r id[100];
               FILE _*fp;
               _c_h_a_r _*s;

               initscr();                              _/_* _A_l_w_a_y_s _c_a_l_l _i_n_i_t_s_c_r_(_) _f_i_r_s_t _*_/
               signal(SIGINT, quit);                   _/_* _M_a_k_e _s_u_r_e _w_o_u _h_a_v_e _a _'_c_l_e_a_n_u_p_' _f_n _*_/
               crmode();                               _/_* _W_e _w_a_n_t _c_b_r_e_a_k _m_o_d_e _*_/
               noecho();                               _/_* _W_e _w_a_n_t _t_o _h_a_v_e _c_o_n_t_r_o_l _o_f _c_h_a_r_s _*_/
               delwin(stdscr);                         _/_* _C_r_e_a_t_e _o_u_r _o_w_n _s_t_d_s_c_r _*_/
               stdscr = newwin(YSIZE, XSIZE, 10, 35);
               flushok(stdscr, TRUE);                  _/_* _E_n_a_b_l_e _f_l_u_s_h_i_n_g _o_f _s_t_d_o_u_t _*_/
               scrollok(stdscr, TRUE);                 _/_* _E_n_a_b_l_e _s_c_r_o_l_l_i_n_g _*_/
               erase();                                _/_* _I_n_i_t_i_a_l_l_y_, _c_l_e_a_r _t_h_e _s_c_r_e_e_n _*_/

               standout();
               move(0,0);










                         _A_p_p_e_n_d_i_x _A


               _w_h_i_l_e (1) _{
                         c = getchar();
                         _s_w_i_t_c_h(c) _{
                         _c_a_s_e 'q':                     _/_* _Q_u_i_t _o_n _'_q_' _*_/
                                   quit();
                                   _b_r_e_a_k;
                         _c_a_s_e 's':                     _/_* _G_o _i_n_t_o _s_t_a_n_d_o_u_t _m_o_d_e _o_n _'_s_' _*_/
                                   standout();
                                   _b_r_e_a_k;
                         _c_a_s_e 'e':                     _/_* _E_x_i_t _s_t_a_n_d_o_u_t _m_o_d_e _o_n _'_e_' _*_/
                                   standend();
                                   _b_r_e_a_k;
                         _c_a_s_e 'r':                     _/_* _F_o_r_c_e _a _r_e_f_r_e_s_h _o_n _'_r_' _*_/
                                   wrefresh(curscr);
                                   _b_r_e_a_k;
                         _d_e_f_a_u_l_t:                      _/_* _B_y _d_e_f_a_u_l_t _o_u_t_p_u_t _t_h_e _c_h_a_r_a_c_t_e_r _*_/
                                   addch(c);
                                   refresh();
                         _}
               _}
    _}


    _i_n_t
    quit()
    _{
               erase();                      _/_* _T_e_r_m_i_n_a_t_e _b_y _e_r_a_s_i_n_g _t_h_e _s_c_r_e_e_n _*_/
               refresh();
               endwin();                     _/_* _A_l_w_a_y_s _e_n_d _w_i_t_h _e_n_d_w_i_n_(_) _*_/
               delwin(curscr);               _/_* _R_e_t_u_r_n _s_t_o_r_a_g_e _*_/
               delwin(stdscr);
               putchar('\n');
               exit(0);
    _}






1111....2222....  TTTTwwwwiiiinnnnkkkklllleeee

     This is a moderately simple program which  prints  pat-
terns on the screen.  It switches between patterns of aster-
isks, putting them on one by one in random order,  and  then
taking  them  off in the same fashion.  It is more efficient
to write this using only  the  motion  optimization,  as  is
demonstrated below.

    _/_*           _$_N_e_t_B_S_D_: _t_w_i_n_k_l_e_1_._c_,_v _1_._6 _2_0_0_5_/_0_5_/_2_3 _0_4_:_0_4_:_4_9 _c_h_r_i_s_t_o_s _E_x_p _$                    _*_/













                         _A_p_p_e_n_d_i_x _A


    _/_*
     _*
     _*  _C_o_p_y_r_i_g_h_t _(_c_) _1_9_8_0_, _1_9_9_3
     _*          _T_h_e _R_e_g_e_n_t_s _o_f _t_h_e _U_n_i_v_e_r_s_i_t_y _o_f _C_a_l_i_f_o_r_n_i_a_.  _A_l_l _r_i_g_h_t_s _r_e_s_e_r_v_e_d_.
     _*
     _*  _R_e_d_i_s_t_r_i_b_u_t_i_o_n _a_n_d _u_s_e _i_n _s_o_u_r_c_e _a_n_d _b_i_n_a_r_y _f_o_r_m_s_, _w_i_t_h _o_r _w_i_t_h_o_u_t
     _*  _m_o_d_i_f_i_c_a_t_i_o_n_, _a_r_e _p_e_r_m_i_t_t_e_d _p_r_o_v_i_d_e_d _t_h_a_t _t_h_e _f_o_l_l_o_w_i_n_g _c_o_n_d_i_t_i_o_n_s
     _*  _a_r_e _m_e_t_:
     _*  _1_. _R_e_d_i_s_t_r_i_b_u_t_i_o_n_s _o_f _s_o_u_r_c_e _c_o_d_e _m_u_s_t _r_e_t_a_i_n _t_h_e _a_b_o_v_e _c_o_p_y_r_i_g_h_t
     _*     _n_o_t_i_c_e_, _t_h_i_s _l_i_s_t _o_f _c_o_n_d_i_t_i_o_n_s _a_n_d _t_h_e _f_o_l_l_o_w_i_n_g _d_i_s_c_l_a_i_m_e_r_.
     _*  _2_. _R_e_d_i_s_t_r_i_b_u_t_i_o_n_s _i_n _b_i_n_a_r_y _f_o_r_m _m_u_s_t _r_e_p_r_o_d_u_c_e _t_h_e _a_b_o_v_e _c_o_p_y_r_i_g_h_t
     _*     _n_o_t_i_c_e_, _t_h_i_s _l_i_s_t _o_f _c_o_n_d_i_t_i_o_n_s _a_n_d _t_h_e _f_o_l_l_o_w_i_n_g _d_i_s_c_l_a_i_m_e_r _i_n _t_h_e
     _*     _d_o_c_u_m_e_n_t_a_t_i_o_n _a_n_d_/_o_r _o_t_h_e_r _m_a_t_e_r_i_a_l_s _p_r_o_v_i_d_e_d _w_i_t_h _t_h_e _d_i_s_t_r_i_b_u_t_i_o_n_.
     _*  _3_. _N_e_i_t_h_e_r _t_h_e _n_a_m_e _o_f _t_h_e _U_n_i_v_e_r_s_i_t_y _n_o_r _t_h_e _n_a_m_e_s _o_f _i_t_s _c_o_n_t_r_i_b_u_t_o_r_s
     _*     _m_a_y _b_e _u_s_e_d _t_o _e_n_d_o_r_s_e _o_r _p_r_o_m_o_t_e _p_r_o_d_u_c_t_s _d_e_r_i_v_e_d _f_r_o_m _t_h_i_s _s_o_f_t_w_a_r_e
     _*     _w_i_t_h_o_u_t _s_p_e_c_i_f_i_c _p_r_i_o_r _w_r_i_t_t_e_n _p_e_r_m_i_s_s_i_o_n_.
     _*
     _*  _T_H_I_S _S_O_F_T_W_A_R_E _I_S _P_R_O_V_I_D_E_D _B_Y _T_H_E _R_E_G_E_N_T_S _A_N_D _C_O_N_T_R_I_B_U_T_O_R_S _`_`_A_S _I_S_'_' _A_N_D
     _*  _A_N_Y _E_X_P_R_E_S_S _O_R _I_M_P_L_I_E_D _W_A_R_R_A_N_T_I_E_S_, _I_N_C_L_U_D_I_N_G_, _B_U_T _N_O_T _L_I_M_I_T_E_D _T_O_, _T_H_E
     _*  _I_M_P_L_I_E_D _W_A_R_R_A_N_T_I_E_S _O_F _M_E_R_C_H_A_N_T_A_B_I_L_I_T_Y _A_N_D _F_I_T_N_E_S_S _F_O_R _A _P_A_R_T_I_C_U_L_A_R _P_U_R_P_O_S_E
     _*  _A_R_E _D_I_S_C_L_A_I_M_E_D_.  _I_N _N_O _E_V_E_N_T _S_H_A_L_L _T_H_E _R_E_G_E_N_T_S _O_R _C_O_N_T_R_I_B_U_T_O_R_S _B_E _L_I_A_B_L_E
     _*  _F_O_R _A_N_Y _D_I_R_E_C_T_, _I_N_D_I_R_E_C_T_, _I_N_C_I_D_E_N_T_A_L_, _S_P_E_C_I_A_L_, _E_X_E_M_P_L_A_R_Y_, _O_R _C_O_N_S_E_Q_U_E_N_T_I_A_L
     _*  _D_A_M_A_G_E_S _(_I_N_C_L_U_D_I_N_G_, _B_U_T _N_O_T _L_I_M_I_T_E_D _T_O_, _P_R_O_C_U_R_E_M_E_N_T _O_F _S_U_B_S_T_I_T_U_T_E _G_O_O_D_S
     _*  _O_R _S_E_R_V_I_C_E_S_; _L_O_S_S _O_F _U_S_E_, _D_A_T_A_, _O_R _P_R_O_F_I_T_S_; _O_R _B_U_S_I_N_E_S_S _I_N_T_E_R_R_U_P_T_I_O_N_)
     _*  _H_O_W_E_V_E_R _C_A_U_S_E_D _A_N_D _O_N _A_N_Y _T_H_E_O_R_Y _O_F _L_I_A_B_I_L_I_T_Y_, _W_H_E_T_H_E_R _I_N _C_O_N_T_R_A_C_T_, _S_T_R_I_C_T
     _*  _L_I_A_B_I_L_I_T_Y_, _O_R _T_O_R_T _(_I_N_C_L_U_D_I_N_G _N_E_G_L_I_G_E_N_C_E _O_R _O_T_H_E_R_W_I_S_E_) _A_R_I_S_I_N_G _I_N _A_N_Y _W_A_Y
     _*  _O_U_T _O_F _T_H_E _U_S_E _O_F _T_H_I_S _S_O_F_T_W_A_R_E_, _E_V_E_N _I_F _A_D_V_I_S_E_D _O_F _T_H_E _P_O_S_S_I_B_I_L_I_T_Y _O_F
     _*  _S_U_C_H _D_A_M_A_G_E_.
     _*
     _*         _@_(_#_)_t_w_i_n_k_l_e_1_._c      _8_._1 _(_B_e_r_k_e_l_e_y_) _6_/_8_/_9_3
     _*_/
    _#_i_n_c_l_u_d_e             <curses.h>
    _#_i_n_c_l_u_d_e             <signal.h>

    _/_*
     _* _t_h_e _i_d_e_a _f_o_r _t_h_i_s _p_r_o_g_r_a_m _w_a_s _a _p_r_o_d_u_c_t _o_f _t_h_e _i_m_a_g_i_n_a_t_i_o_n _o_f
     _* _K_u_r_t _S_c_h_o_e_n_s_.  _N_o_t _r_e_s_p_o_n_s_i_b_l_e _f_o_r _m_i_n_d_s _l_o_s_t _o_r _s_t_o_l_e_n_.
     _*_/

    _#_d_e_f_i_n_e    NCOLS     80
    _#_d_e_f_i_n_e    NLINES    24
    _#_d_e_f_i_n_e    MAXPATTERNS         4

    _t_y_p_e_d_e_f _s_t_r_u_c_t _{
               _i_n_t       y, x;
    _} LOCS;

    _s_t_a_t_i_c LOCS          Layout[NCOLS _* NLINES];       _/_* _c_u_r_r_e_n_t _b_o_a_r_d _l_a_y_o_u_t _*_/

    _s_t_a_t_i_c _i_n_t           Pattern,                      _/_* _c_u_r_r_e_n_t _p_a_t_t_e_r_n _n_u_m_b_e_r _*_/
                         Numstars;                     _/_* _n_u_m_b_e_r _o_f _s_t_a_r_s _i_n _p_a_t_t_e_r_n _*_/

    _s_t_a_t_i_c _v_o_i_d puton(_c_h_a_r);










                         _A_p_p_e_n_d_i_x _A


    _s_t_a_t_i_c _v_o_i_d makeboard(_v_o_i_d);
    _s_t_a_t_i_c _i_n_t ison(_i_n_t, _i_n_t);
    _s_t_a_t_i_c _v_o_i_d die(_i_n_t);

    _i_n_t
    main(_v_o_i_d)
    _{
               srand(getpid());                        _/_* _i_n_i_t_i_a_l_i_z_e _r_a_n_d_o_m _s_e_q_u_e_n_c_e _*_/

               initscr();
               signal(SIGINT, die);
               noecho();
               nonl();
               leaveok(stdscr, TRUE);
               scrollok(stdscr, FALSE);

               _f_o_r (;;) _{
                         makeboard();                  _/_* _m_a_k_e _t_h_e _b_o_a_r_d _s_e_t_u_p _*_/
                         puton('_*');                   _/_* _p_u_t _o_n _'_*_'_s _*_/
                         puton(' ');                   _/_* _c_o_v_e_r _u_p _w_i_t_h _' _'_s _*_/
               _}
    _}

    _/_*
     _* _O_n _p_r_o_g_r_a_m _e_x_i_t_, _m_o_v_e _t_h_e _c_u_r_s_o_r _t_o _t_h_e _l_o_w_e_r _l_e_f_t _c_o_r_n_e_r _b_y
     _* _d_i_r_e_c_t _a_d_d_r_e_s_s_i_n_g_, _s_i_n_c_e _c_u_r_r_e_n_t _l_o_c_a_t_i_o_n _i_s _n_o_t _g_u_a_r_a_n_t_e_e_d_.
     _* _W_e _l_i_e _a_n_d _s_a_y _w_e _u_s_e_d _t_o _b_e _a_t _t_h_e _u_p_p_e_r _r_i_g_h_t _c_o_r_n_e_r _t_o _g_u_a_r_a_n_t_e_e
     _* _a_b_s_o_l_u_t_e _a_d_d_r_e_s_s_i_n_g_.
     _*_/
    _s_t_a_t_i_c _v_o_i_d
    die(_i_n_t n)
    _{
               signal(SIGINT, SIG_IGN);
               mvcur(0, COLS - 1, LINES - 1, 0);
               endwin();
               exit(n);
    _}


    _/_*
     _* _M_a_k_e _t_h_e _c_u_r_r_e_n_t _b_o_a_r_d _s_e_t_u_p_.  _I_t _p_i_c_k_s _a _r_a_n_d_o_m _p_a_t_t_e_r_n _a_n_d
     _* _c_a_l_l_s _i_s_o_n_(_) _t_o _d_e_t_e_r_m_i_n_e _i_f _t_h_e _c_h_a_r_a_c_t_e_r _i_s _o_n _t_h_a_t _p_a_t_t_e_r_n
     _* _o_r _n_o_t_.
     _*_/
    _s_t_a_t_i_c _v_o_i_d
    makeboard(_v_o_i_d)
    _{
               _i_n_t                 y, x;
               LOCS      _*lp;

               Pattern = rand() % MAXPATTERNS;
               lp = Layout;
               _f_o_r (y = 0; y < NLINES; y++)










                         _A_p_p_e_n_d_i_x _A


                         _f_o_r (x = 0; x < NCOLS; x++)
                                   _i_f (ison(y, x)) _{
                                             lp->y = y;
                                             lp->x = x;
                                             lp++;
                                   _}
               Numstars = lp - Layout;
    _}

    _/_*
     _* _R_e_t_u_r_n _T_R_U_E _i_f _(_y_, _x_) _i_s _o_n _t_h_e _c_u_r_r_e_n_t _p_a_t_t_e_r_n_.
     _*_/
    _s_t_a_t_i_c _i_n_t
    ison(_i_n_t y, _i_n_t x)
    _{
               _s_w_i_t_c_h (Pattern) _{
                 _c_a_s_e 0:           _/_* _a_l_t_e_r_n_a_t_i_n_g _l_i_n_e_s _*_/
                         _r_e_t_u_r_n !(y & 01);
                 _c_a_s_e 1:           _/_* _b_o_x _*_/
                         _i_f (x >= LINES && y >= NCOLS)
                                   _r_e_t_u_r_n FALSE;
                         _i_f (y < 3 || y >= NLINES - 3)
                                   _r_e_t_u_r_n TRUE;
                         _r_e_t_u_r_n (x < 3 || x >= NCOLS - 3);
                 _c_a_s_e 2:           _/_* _h_o_l_y _p_a_t_t_e_r_n_! _*_/
                         _r_e_t_u_r_n ((x + y) & 01);
                 _c_a_s_e 3:           _/_* _b_a_r _a_c_r_o_s_s _c_e_n_t_e_r _*_/
                         _r_e_t_u_r_n (y >= 9 && y <= 15);
               _}
               _/_* _N_O_T_R_E_A_C_H_E_D _*_/
    _}

    _s_t_a_t_i_c _v_o_i_d
    puton(_c_h_a_r ch)
    _{
               LOCS      _*lp;
               _i_n_t       r;
               LOCS      _*end;
               LOCS      temp;

               end = &Layout[Numstars];
               _f_o_r (lp = Layout; lp < end; lp++) _{
                         r = rand() % Numstars;
                         temp = _*lp;
                         _*lp = Layout[r];
                         Layout[r] = temp;
               _}

               _f_o_r (lp = Layout; lp < end; lp++) _{
                         mvaddch(lp->y, lp->x, ch);
                         refresh();
               _}
    _}










                         _A_p_p_e_n_d_i_x _A


_CC_oo_nn_tt_ee_nn_tt_ss

1 Overview ............................................    1
   1.1 Terminology ....................................    1
   1.2 Compiling Applications .........................    1
   1.3 Screen Updating ................................    1
   1.4 Naming Conventions .............................    3
2 Variables ...........................................    4
3 Usage ...............................................    5
   3.1 Initialization .................................    5
   3.2 Output .........................................    5
   3.3 Input ..........................................    6
   3.4 Termination ....................................    6
4 Cursor Movement Optimizations .......................    6
5 Character Output and Scrolling ......................    7
6 Terminal State Handling .............................    7
7 Subwindows ..........................................    8
8 The Functions .......................................    8
AAAAppppppppeeeennnnddddiiiixxxx AAAA ............................................   35
1 Examples ............................................   35
   1.1 Simple Character Output ........................   35
   1.2 Twinkle ........................................   36





































