







     Screen Updating and Cursor Movement Optimization:
                     A Library Package

                  Kenneth C. R. C. Arnold
                         Elan Amir

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



                          ABSTRACT





     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 termcap(5)  database  to
describe the capabilities of the terminal.

Acknowledgements

     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.  Ken Arnold    16 April 1986

     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.  Elan
Amir   29 December 1992











Screen Package                                      PS1:19-1


1.  Overview

     In making available the generalized  terminal  descrip-
tions  in termcap(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.

1.1.  Terminology

     In this document, the following terminology is used:

window: 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.

terminal: Sometimes called terminal screen.   The  package's
     idea  of  what  the  terminal's  screen currently looks
     like, i.e., what the user sees now.  This is a  special
     screen:

screen:  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, stdscr, is automatically provided for the
     programmer.

1.2.  Compiling Applications

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

    #include <curses.h>

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

    cc [ flags ] file ... -lcurses -ltermcap


1.3.  Screen Updating

     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










Screen Package                                      PS1:19-3


WINDOW 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 curscr for current screen) is a
screen image of what  the  terminal  currently  looks  like.
Another  screen (called stdscr, for standard screen) 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  stdscr)   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  does not change the terminal.
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.

1.4.  Naming Conventions

     As  hinted above, the routines can use several windows,
but two are always available: curscr, which is the image  of
what  the  terminal looks like at present, and stdscr, which
is the image of what the programmer wants  the  terminal  to
look like next.  The user should not access curscr 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 stdscr as a
default screen.  For example, to add a character to  stdscr,
one  calls addch() with the desired character.  If a differ-
ent window is to be used, the routine waddch() (for  window-
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
not 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  std-
scr.












PS1:19-4                                      Screen Package


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 "mv"
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 (win) comes before
the added (y, x)  co-ordinates.   If  a  window  pointer  is
needed, it is always the first parameter passed.

2.  Variables

     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 Def_term 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.












Screen Package                                      PS1:19-5


3.  Usage

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

3.1.  Initialization

     In order to use the screen package, the  routines  must
know  about  terminal  characteristics,  and  the  space for
curscr and stdscr 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 always 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 curscr or stdscr 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 LINES and COLS 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 stdscr and/or curscr before creating new
ones  so this change is best done before the initial call to
initscr().

3.2.  Output

     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.












PS1:19-6                                      Screen Package


     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 curscr, it  will  make  the
screen  look  like  the image of curscr.  This is useful for
implementing a command which would redraw the screen in case
it got messed up.

3.3.  Input

     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.

3.4.  Termination

     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 curses_termios 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 before the final calls to  delwin(),  which
free the storage of the windows.

4.  Cursor Movement Optimizations

     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










Screen Package                                      PS1:19-7


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
termlib(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);


5.  Character Output and Scrolling

     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  xterm  character
output conventions.

6.  Terminal State Handling

     The variable curses_termios 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
curses_termios structure, you  should  use  the  tsetattr(3)
routines.










PS1:19-8                                      Screen Package


7.  Subwindows

     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 parent 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.

8.  The Functions

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


addbytes(char *str, int len);










































Screen Package                                      PS1:19-9


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


addch(chtype ch);[+]

     Add  the  character  ch  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(chtype *str);[+]










































PS1:19-10                                     Screen Package


     Add the characters and attributes in the string pointed
     to by str 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(chtype *str, int len);[+]

     Add  no  more than len characters and attributes of the
     string pointed to by str 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(char *str);[+]














































Screen Package                                     PS1:19-11


     Add  the  string pointed to by str 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(char *str, int len);[+]

     Add no more than len characters of the  string  pointed
     to  by str 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(short fore, short back);















































PS1:19-12                                     Screen Package


     Set the curses default foreground and background colors
     to fore and back.


attr_get(attr_t *attr, short *pair, void *opt);[+]

     Get  the  attributes  and  colour  pair for the window.
     Either attr or pair may be NULL.  The opt  argument  is
     not used.


attr_off(attr_t attr, void *opt);[+]



















































Screen Package                                     PS1:19-13


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


attr_on(attr_t attr, void *opt);[+]

     Add character attributes for any  characters  added  to
     the window (if it has that capability).  The attributes
     that can be set are  A_UNDERLINE,  A_REVERSE,  A_BLINK,
     A_DIM,  A_BOLD,  A_BLANK,  A_PROTECT,  A_ALTCHARSET and
     COLOR_PAIR(n).


attr_set(attr_t attr, short pair, void *opt);[+]

















































PS1:19-14                                     Screen Package


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


attroff(int attribute);[+]

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


attron(int attribute);[+]

















































Screen Package                                     PS1:19-15


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


attrset(int attribute);[+]

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


baudrate();[+]


















































PS1:19-16                                     Screen Package


     Returns  the output baud rate of the terminal.  This is
     a system dependent constant (defined in <sys/tty.h>  on
     BSD systems, which is included by <curses.h>).


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(chtype ch);


















































Screen Package                                     PS1:19-17


     Sets the background rendition to ch.


bkgdset(chtype ch);

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


border(chtype left, chtype right, chtype top, chtype bottom, chtype topleft, chtype topright, chtype botleft, chtype botright);

     Draws a border around the window using the  characters:
     left  for  drawing the left side, right for drawing the
     left side, top for drawing the  top  edge,  bottom  for
     drawing  the top edge, topleft for drawing the top-left
     corner, topright  for  drawing  the  top-right  corner,
     botleft   for   drawing  the  bottom-left  corner,  and
     botright  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(WINDOW win, chtype vert, chtype hor);







































PS1:19-18                                     Screen Package


     Draws a box around the window using vert as the charac-
     ter for drawing the vertical sides, and hor 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();

















































Screen Package                                     PS1:19-19


     Set the terminal to cbreak mode.


clear();[+]

     Resets the entire  window  to  blanks.   If  win  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(WINDOW *scr, int boolf);[+]


















































PS1:19-20                                     Screen Package


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


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 "mv" command.


clrtoeol();[+]












































Screen Package                                     PS1:19-21


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


color_content(short color, short *red, short *green, short *blue);

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


color_set(short pair, void *opt);[+]

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


copywin(const WINDOW *src, WINDOW *dst, int sminrow, int smincol, int dminrow, int dmincol, int dmaxrow, int dmaxcol);














































PS1:19-22                                     Screen Package


     Copies  the  contents  of  the window src starting at (
     sminrow, smincol) to the destination window dst  start-
     ing at ( dminrow, dmincol) and ending at either the end
     of the source window or ( dmaxrow,  dmaxcol)  whichever
     is  the  lesser.   The parameter overlay determines the
     nature of the copy.  If overlay is TRUE then  only  the
     non-space  characters  from  src are copied to dst.  If
     overlay is FALSE then all characters  are  copied  from
     src to dst.


curs_set(int visibility);



















































Screen Package                                     PS1:19-23


     Sets  the visibility of the screen cursor.  The parame-
     ter visibility 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 ERR is returned if the ter-
     minal cannot support the requested visibility mode.


crmode();[+]

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


delay_output(int ms);














































PS1:19-24                                     Screen Package


     Pause output for ms 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(char *sequence, int key_symbol);














































Screen Package                                     PS1:19-25


     Assigns the character sequence given in sequence to the
     key  symbol  key_symbol.   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  termcap  data-
     base but this function allows extensions to be added by
     the application.  If sequence is a  NULL  pointer  then
     all  the  sequences  associated with key_symbol will be
     removed, including any definitions inserted by termcap.


delch();



















































PS1:19-26                                     Screen Package


     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(SCREEN *screen);

















































Screen Package                                     PS1:19-27


     Delete the screen and frees all associated resources.


delwin(WINDOW *win);

     Deletes the window from existence.  All  resources  are
     freed  for  future use by calloc(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(WINDOW *orig, int nlines, int ncols, int by, int bx);

















































PS1:19-28                                     Screen Package


     Performs  a  function very similar to that of subwin().
     The difference being that with derwin() the  origin  of
     the  child window given by ( by, bx) is relative to the
     origin of the parent window orig 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(WINDOW *win);
















































Screen Package                                     PS1:19-29


     Creates an exact copy of the window win.


echo();[+]

     Sets the terminal to echo characters.


echochar(const chtype ch);[+]

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


endwin();
















































PS1:19-30                                     Screen Package


     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  sig-
     nal(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 "mv" command.


erasechar();[+]













































Screen Package                                     PS1:19-31


     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();


















































PS1:19-32                                     Screen Package


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


flushok(WINDOW *win, int boolf);

     Normally,  refresh() fflush('s); stdout when it is fin-
     ished.  flushok() allows you to control this.  if boolf
     is  non-zero  (i.e., non-zero) it will do the fflush(),
     otherwise it will not.


getattrs(WINDOW *win);


















































Screen Package                                     PS1:19-33


     Gets the attributes for win.


getbkgd(WINDOW *win);

     Gets the background rendition for win.


getcap(char *name);

     Get the terminal capability name.


getch();[+]

















































PS1:19-34                                     Screen Package


     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 noecho has been set,
     then the window is left unaltered.  In order to  retain
     control of the terminal, it is necessary to have one of
     noecho, cbreak, or rawmode set.  If you do not set one,
     whatever  routine  you call to read characters will set
     cbreak for you, and then reset  to  the  original  mode
     when finished.


getcury(WINDOW *win);


















































Screen Package                                     PS1:19-35


     Get current y position on win.


getcurx(WINDOW *win);

     Get current x position on win.


getbegy(WINDOW *win);

     Get start y position on win.


getbegx(WINDOW *win);

















































PS1:19-36                                     Screen Package


     Get start x position on win.


getmaxy(WINDOW *win);

     Get maximum y position on win.


getmaxx(WINDOW *win);

     Get maximum x position on win.


getnstr(char *str);[+]

















































Screen Package                                     PS1:19-37


     Get a string through the window and put it in the loca-
     tion pointed to by str.  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
     would cause the screen to scroll illegally.


getstr(char *str);[+]

     Get a string through the window and put it in the loca-
     tion  pointed  to  by str, 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(WINDOW *win);








































PS1:19-38                                     Screen Package


     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(WINDOW *win);

     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(WINDOW *win, int y, int x);


















































Screen Package                                     PS1:19-39


     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 win 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(FILE *fp);

















































PS1:19-40                                     Screen Package


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


getyx(WINDOW *win, int y, int x);

     Puts the current (y, x)  co-ordinates  of  win  in  the
     variables  y  and  x.  Since it is a macro, not a func-
     tion, you do not pass the address of y and x.


halfdelay(int timeout);

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


has_colors();











































Screen Package                                     PS1:19-41


     Check if terminal has colors.


hline(chtype ch, int count);

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


idcok(WINDOW *win, int boolf);


















































PS1:19-42                                     Screen Package


     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(WINDOW *win, int boolf);

     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();[+]


















































Screen Package                                     PS1:19-43


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


inchnstr(chtype *chstr, int 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 chstr.


inchstr(chtype *chstr);

















































PS1:19-44                                     Screen Package


     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
     chstr, which is assumed to be large  enough  to  handle
     it.


innstr(char *str, int 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 str.


init_color(short color, short red, short green, short blue);
















































Screen Package                                     PS1:19-45


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


init_pair(short pair, short fore, short back);

     Set  the foreground and background colors of pair pair.


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 Def_term (initially
     "dumb").  If the boolean My_term is non-zero,  Def_term
     is  always used.  If the system supports the TIOCGWINSZ
     ioctl(2) call, it is used to get the  number  of  lines
     and  columns  for  the  terminal, otherwise it is taken
     from the termcap description.


insch(char c);







































PS1:19-46                                     Screen Package


     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(int n);

     If  n is positive insert n lines above the current one.
     Every line below the current line will be shifted down,
     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();














































Screen Package                                     PS1:19-47


     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(char *str);

     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 str,  which  is  assumed  to  be
     large enough to handle it.


is_linetouched(WINDOW *win, int line);















































PS1:19-48                                     Screen Package


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


is_wintouched(WINDOW *win, int line);

     Returns TRUE if the window win 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(WINDOW *win, int boolf);














































Screen Package                                     PS1:19-49


     Sets the terminal flush on interrupt mode.  If boolf 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(int key_symbol, bool flag);

     Controls  the recognition of the key symbol key_symbol.
     By  setting  flag  to  FALSE  the  recognition  of  any
     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(int key);















































PS1:19-50                                     Screen Package


     Returns a description of the key key.


keypad(WINDOW *win, int boolf);

     Sets  the  boolean  flag  for  interpretation of escape
     sequences.  If boolf 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 <curses.h> contains the
     list of recognised keypad and function keys.  See  also
     notimeout().


killchar();[+]
















































Screen Package                                     PS1:19-51


     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(WINDOW *win, int boolf);[+]

     Sets  the boolean flag for leaving the cursor after the
     last change.  If boolf is non-zero, the cursor will  be
     left  after  the  last  update on the terminal, and the
     current (y, x) co-ordinates for  win  will  be  changed
     accordingly.  If boolf
      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();[+]













































PS1:19-52                                     Screen Package


     Returns  a string containing the verbose description of
     the terminal.


meta(WINDOW *win, bool bf);

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


move(int y, int 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(int y, int x, chtype ch);













































Screen Package                                     PS1:19-53


     Moves the cursor to the position (y, x) and then adds a
     character in the same manner as addch().


mvaddchstr(int y, int x, chtype *str);[+]

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


mvaddchnstr(int y, int x, chtype *str);[+]



















































PS1:19-54                                     Screen Package


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


mvaddstr(int y, int x, char *str);[+]

     Moves the cursor to the position (y, x) and then adds a
     string in the same manner as addstr().


mvaddnstr(int y, int x, char *str);[+]



















































Screen Package                                     PS1:19-55


     Moves the cursor to the position (y, x) and then adds a
     string in the same manner as addnstr().


mvcur(int lasty, int lastx, int newy, int newx);

     Moves the  terminal's  cursor  from  (lasty, lastx)  to
     (newy, newx)  in  an  approximation of optimal fashion.
     This routine uses the functions borrowed from  ex  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(WINDOW *win, int y, int x);














































PS1:19-56                                     Screen Package


     Moves  the  subwindow  win 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 win is
     not a subwindow or if the relocated  window  would  lie
     outside the parent window.


mvhline(int y, int x, chtype ch, int count);

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


mvprintw(int y, int x, const char *fmt, ...);

















































Screen Package                                     PS1:19-57


     Equivalent to:

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



mvscanw(int y, int x, const char *fmt, ...);

     Equivalent to:

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



mvvline(int y, int x, chtype ch, int count);














































PS1:19-58                                     Screen Package


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


mvwhline(WINDOW *win, int y, int x, chtype ch, int count);

     Moves  the  cursor to the position (y, x) on window win
     and then draws a horizontal line in the same manner  as
     whline().


mvwvline(WINDOW *win, int y, int x, chtype ch, int count);



















































Screen Package                                     PS1:19-59


     Moves  the  cursor to the position (y, x) on window win
     and then draws a horizontal line in the same manner  as
     wvline().


mvwin(WINDOW *win, int y, int x);

     Move  the home position of the window win 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(WINDOW *win, int y, int x, const char *fmt, ...);














































PS1:19-60                                     Screen Package


     Equivalent to:

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



mvwscanw(WINDOW *win, int y, int x, const char *fmt, ...);

     Equivalent to:

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



napms(int ms);














































Screen Package                                     PS1:19-61


     Sleep for ms milliseconds.


newpad(int lines, int cols);

     Create a new pad with lines lines and cols columns.


newterm(char *type, FILE *outfd, FILE *infd);

     Iinitialise the curses subsystem to use the terminal of
     type type connected via the input  and  output  streams
     infd,outfd.   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 type parameter is NULL
     then the $TERM variable is used as the terminal type.


newwin(int lines, int cols, int begin_y, int begin_x);










































PS1:19-62                                     Screen Package


     Create a new window with lines lines and  cols  columns
     starting  at  position  (begin_y, begin_x).   If either
     lines or cols is 0 (zero), that dimension will  be  set
     to  (LINES - begin_y) or (COLS - begin_x) respectively.
     Thus, to get a new window of dimensions LINES  x  COLS,
     use newwin(0, 0, 0, 0).


nl();

     Set  the terminal to nl mode, i.e., start/stop the sys-
     tem from mapping <RETURN> to <LINE-FEED>.  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();














































Screen Package                                     PS1:19-63


     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(WINDOW *win1, int boolf);















































PS1:19-64                                     Screen Package


     Sets  the  boolean  flag  for non-blocking getch().  If
     boolf 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();



















































Screen Package                                     PS1:19-65


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


noqiflush();[+]

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


noraw();

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


notimeout(WINDOW *win1, int boolf);
















































PS1:19-66                                     Screen Package


     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 boolf is non-
     zero,  getch()  will  wait  indefinitely between escape
     sequence characters, or until a delay set by  timeout()
     expires.


overlay(WINDOW *win1, WINDOW *win2);

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


overwrite(WINDOW *win1, WINDOW *win2);











































Screen Package                                     PS1:19-67


     Overwrite win1 on win2.  The contents of win1,  insofar
     as  they  fit,  are  placed  on  win2 at their starting
     (y, x) co-ordinates.  This is done destructively, i.e.,
     blanks on win1 become blank on win2.


pair_content(short pair, short *fore, short *back);

     Get  the foreground and background colors of pair pair.


pechochar(const chtype ch);[+]



















































PS1:19-68                                     Screen Package


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


pnoutrefresh(WINDOW *pad, int pbeg_y, int pbeg_x, int sbeg_y, int sbeg_x, int smax_y, int smax_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.


prefresh(WINDOW *pad, int pbeg_y, int pbeg_x, int sbeg_y, int sbeg_x, int smax_y, int smax_x);



















































Screen Package                                     PS1:19-69


     Synchronize the terminal screen with the desired pad.


printw(char *fmt, ...);

     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(WINDOW *win, FILE *fp);

















































PS1:19-70                                     Screen Package


     Writes the window data to a file.


qiflush();[+]

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


raw();

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


redrawwin(WINDOW *win);[+]

































____________________
   2 UNIX is a trademark of Unix System Laboratories.












Screen Package                                     PS1:19-71


     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 curscr the screen is cleared and repainted as it
     is currently.  This is very  useful  for  allowing  the
     redrawing  of  the  screen  when  the  user has garbage
     dumped on his terminal.


reset_prog_mode();











































PS1:19-72                                     Screen Package


     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(int lines, int columns);[+]














































Screen Package                                     PS1:19-73


     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(char *fmt, ...);














































PS1:19-74                                     Screen Package


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


scrl(int n);

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


scroll(WINDOW *win);


















































Screen Package                                     PS1:19-75


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


scrollok(WINDOW *win, int boolf);[+]

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


set_term(SCREEN *new);



















































PS1:19-76                                     Screen Package


     Sets the current screen for input and output to be  the
     one given.  The new 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();[+]
















































Screen Package                                     PS1:19-77


     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(WINDOW *win, int lines, int cols, int begin_y, int begin_x);












































PS1:19-78                                     Screen Package


     Create a new pad with  lines  lines  and  cols  columns
     starting  at position (begin_y, begin_x) inside the pad
     win.  This means that any change made to either pad  in
     the  area  covered  by  the subpad will be made on both
     pads.  begin_y, begin_x are specified relative  to  the
     relative (0, 0) of win.


subwin(WINDOW *win, int lines, int cols, int begin_y, int begin_x);

     Create  a  new window with lines lines and cols columns
     starting at position (begin_y, begin_x) inside the win-
     dow  win.   This  means  that any change made to either
     window in the area covered by  the  subwindow  will  be
     made  on  both windows.  begin_y, begin_x are specified
     relative to the overall screen, not the relative (0, 0)
     of  win.   If  either  lines  or cols is 0 (zero), that
     dimension will be set to (LINES - begin_y) or  (COLS  -
     begin_x) respectively.


termattrs();









































Screen Package                                     PS1:19-79


     Returns  the  attributes  that  can  be  applied to the
     screen.


term_attrs();

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


timeout(int delay);[+]

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


touchline(WINDOW *win, int y, int startx, int endx);










































PS1:19-80                                     Screen Package


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


touchoverlap(WINDOW *win1, WINDOW *win2);

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


touchwin(WINDOW *win);

















































Screen Package                                     PS1:19-81


     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(curscr);   to   redraw   the   screen.
     Initscr()  sets the signal SIGTSTP to trap to this rou-
     tine.


unctrl(char *ch);[+]















































PS1:19-82                                     Screen Package


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


unctrllen(char *ch);[+]

     Returns the length of the ASCII representation of ch.


underend();[+]

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


underscore();[+]















































Screen Package                                     PS1:19-83


     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_UNDERLINE).


ungetch(int 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.


untouchwin(WINDOW *win);















































PS1:19-84                                     Screen Package


     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(chtype ch, int count);

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


vwprintw(WINDOW *win, const char *fmt, va_list ap);











































Screen Package                                     PS1:19-85


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


vwscanw(WINDOW *win, const char *fmt, va_list ap);

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


wnoutrefresh(WINDOW *win);


















































PS1:19-86                                     Screen Package


     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(WINDOW *win, int line, int n);[+]

     Mark n lines starting at line in  the  window  as  cor-
     rupted.   This  is equivalent to wtouchln(win, line, n,
     1).


wresize(WINDOW *win, int lines, int columns);


















































Screen Package                                     PS1:19-87


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


wtouchln(WINDOW *win, int line, int n, int changed);

     If changed is 1 then n lines starting at  line  in  the
     window  are  touched.   If  changed  is  0 then n lines
     starting at line in the window are untouched.



     The following functions differ from the standard  func-
tions  only  in their specification of a window, rather than
the use of the default stdscr.


waddbytes(WINDOW *win, char* str, int len);
waddch(WINDOW *win, chtype ch);
waddchnstr(WINDOW *win, chtype *str, int len);
waddchstr(WINDOW *win, chtype *str, int len);
waddnstr(WINDOW *win, char *str, int len);
waddstr(WINDOW *win, char *str);
wattroff(WINDOW *win, int attr);
wattron(WINDOW *win, int attr);
wattrset(WINDOW *win, int attr);
wbkgd(WINDOW *win, chtype ch);
wbkgdset(WINDOW *win, chtype ch);
wborder(WINDOW *win, chtype left, chtype right, chtype top, chtype bottom, chtype topleft, chtype topright, chtype botleft);
wclear(WINDOW *win);
wclrtobot(WINDOW *win);
wclrtoeol(WINDOW *win);
wdelch(WINDOW *win);
wdeleteln(WINDOW *win);
wechochar(WINDOW *win, chtype ch);
werase(WINDOW *win);
wgetch(WINDOW *win);
wgetnstr(WINDOW *win, char *str, int len);
wgetstr(WINDOW *win, char *str);
whline(WINDOW *win, chtype ch, int count);
winch(WINDOW *win);[+]
winchnstr(WINDOW *win, chtype *chstr, int n);
winchstr(WINDOW *win, chtype *chstr);
winnstr(WINDOW *win, char *str, int n);
winsch(WINDOW *win, char c);
winsdelln(WINDOW *win, int n);
winsertln(WINDOW *win);
winstr(WINDOW *win, char *str);
wmove(WINDOW *win, int y, int, x");
wprintw(WINDOW *win, char *fmt, ...);
wrefresh(WINDOW *win);
wscanw(WINDOW *win, char *fmt, ...);










PS1:19-88                                     Screen Package


wscrl(WINDOW *win, int n);
wstandend(WINDOW *win);
wstandout(WINDOW *win);
wtimeout(WINDOW *win, int delay);
wunderend(WINDOW *win);
wunderscore(WINDOW *win);
wvline(WINDOW *win, chtype ch, int count);
mvwaddch(WINDOW *win, int y, int x, chtype ch);
mvwaddchstr(WINDOW *win, int y, int x, chtype *str);[+]
mvwaddchnstr(WINDOW *win, int y, int x, chtype *str);[+]
mvwaddnstr(WINDOW *win, int y, int x, char *str, int len);
mvwaddstr(WINDOW *win, int y, int x, char *str);
mvwgetnstr(WINDOW *win, int y, int x, char *str, int len);
mvwgetstr(WINDOW *win, int y, int x, char *str);
mvwhline(WINDOW *win, int y, int x, chtype ch, int count);
mvwvline(WINDOW *win, int y, int x, chtype ch, int count);















































Screen Package                                     PS1:19-89


1.  Examples

     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 systat(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 examples subdirectory.

1.1.  Simple Character Output

     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.

    #include <sys/types.h>
    #include <curses.h>
    #include <stdio.h>
    #include <signal.h>


    #define YSIZE 10
    #define XSIZE 20

    int quit();

    main()
    {
               int i, j, c;
               size_t len;
               char id[100];
               FILE *fp;
               char *s;

               initscr();                              /* Always call initscr() first */
               signal(SIGINT, quit);                   /* Make sure wou have a 'cleanup' fn */
               crmode();                               /* We want cbreak mode */
               noecho();                               /* We want to have control of chars */
               delwin(stdscr);                         /* Create our own stdscr */
               stdscr = newwin(YSIZE, XSIZE, 10, 35);
               flushok(stdscr, TRUE);                  /* Enable flushing of stdout */
               scrollok(stdscr, TRUE);                 /* Enable scrolling */
               erase();                                /* Initially, clear the screen */

               standout();
               move(0,0);










                         Appendix A


               while (1) {
                         c = getchar();
                         switch(c) {
                         case 'q':                     /* Quit on 'q' */
                                   quit();
                                   break;
                         case 's':                     /* Go into standout mode on 's' */
                                   standout();
                                   break;
                         case 'e':                     /* Exit standout mode on 'e' */
                                   standend();
                                   break;
                         case 'r':                     /* Force a refresh on 'r' */
                                   wrefresh(curscr);
                                   break;
                         default:                      /* By default output the character */
                                   addch(c);
                                   refresh();
                         }
               }
    }


    int
    quit()
    {
               erase();                      /* Terminate by erasing the screen */
               refresh();
               endwin();                     /* Always end with endwin() */
               delwin(curscr);               /* Return storage */
               delwin(stdscr);
               putchar('\n');
               exit(0);
    }






1.2.  Twinkle

     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.

    /*           $NetBSD: twinkle1.c,v 1.6 2005/05/23 04:04:49 christos Exp $                    */













                         Appendix A


    /*
     *
     *  Copyright (c) 1980, 1993
     *          The Regents of the University of California.  All rights reserved.
     *
     *  Redistribution and use in source and binary forms, with or without
     *  modification, are permitted provided that the following conditions
     *  are met:
     *  1. Redistributions of source code must retain the above copyright
     *     notice, this list of conditions and the following disclaimer.
     *  2. Redistributions in binary form must reproduce the above copyright
     *     notice, this list of conditions and the following disclaimer in the
     *     documentation and/or other materials provided with the distribution.
     *  3. Neither the name of the University nor the names of its contributors
     *     may be used to endorse or promote products derived from this software
     *     without specific prior written permission.
     *
     *  THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
     *  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
     *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
     *  ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
     *  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
     *  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
     *  OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     *  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
     *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
     *  OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
     *  SUCH DAMAGE.
     *
     *         @(#)twinkle1.c      8.1 (Berkeley) 6/8/93
     */
    #include             <curses.h>
    #include             <signal.h>

    /*
     * the idea for this program was a product of the imagination of
     * Kurt Schoens.  Not responsible for minds lost or stolen.
     */

    #define    NCOLS     80
    #define    NLINES    24
    #define    MAXPATTERNS         4

    typedef struct {
               int       y, x;
    } LOCS;

    static LOCS          Layout[NCOLS * NLINES];       /* current board layout */

    static int           Pattern,                      /* current pattern number */
                         Numstars;                     /* number of stars in pattern */

    static void puton(char);










                         Appendix A


    static void makeboard(void);
    static int ison(int, int);
    static void die(int);

    int
    main(void)
    {
               srand(getpid());                        /* initialize random sequence */

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

               for (;;) {
                         makeboard();                  /* make the board setup */
                         puton('*');                   /* put on '*'s */
                         puton(' ');                   /* cover up with ' 's */
               }
    }

    /*
     * On program exit, move the cursor to the lower left corner by
     * direct addressing, since current location is not guaranteed.
     * We lie and say we used to be at the upper right corner to guarantee
     * absolute addressing.
     */
    static void
    die(int n)
    {
               signal(SIGINT, SIG_IGN);
               mvcur(0, COLS - 1, LINES - 1, 0);
               endwin();
               exit(n);
    }


    /*
     * Make the current board setup.  It picks a random pattern and
     * calls ison() to determine if the character is on that pattern
     * or not.
     */
    static void
    makeboard(void)
    {
               int                 y, x;
               LOCS      *lp;

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










                         Appendix A


                         for (x = 0; x < NCOLS; x++)
                                   if (ison(y, x)) {
                                             lp->y = y;
                                             lp->x = x;
                                             lp++;
                                   }
               Numstars = lp - Layout;
    }

    /*
     * Return TRUE if (y, x) is on the current pattern.
     */
    static int
    ison(int y, int x)
    {
               switch (Pattern) {
                 case 0:           /* alternating lines */
                         return !(y & 01);
                 case 1:           /* box */
                         if (x >= LINES && y >= NCOLS)
                                   return FALSE;
                         if (y < 3 || y >= NLINES - 3)
                                   return TRUE;
                         return (x < 3 || x >= NCOLS - 3);
                 case 2:           /* holy pattern! */
                         return ((x + y) & 01);
                 case 3:           /* bar across center */
                         return (y >= 9 && y <= 15);
               }
               /* NOTREACHED */
    }

    static void
    puton(char ch)
    {
               LOCS      *lp;
               int       r;
               LOCS      *end;
               LOCS      temp;

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

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










                         Appendix A


Contents

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
Appendix A ............................................   89
1 Examples ............................................   89
   1.1 Simple Character Output ........................   89
   1.2 Twinkle ........................................   90





































