curses(3)



NAME

     curses - screen/window management library


SYNOPSIS

     cc demo.c -lcurses


DESCRIPTION

     Curses is a library of screen and  window  management  routines.   It  is
     modeled  after  the UNIX curses and ncurses libraries. Normally, programs
     written for curses should be easily ported to UNIX, and vice versa.

     To use the routines, the function initscr() must first be  called.   This
     creates  two  'windows'  for  the user: stdscr and curscr.  Stdscr is the
     default window for the user to make changes on, and curscr  reflects  the
     current  contents  of  the  physical  display screen.  The user writes or
     edits the stdscr window to his liking, then calls the refresh()  function
     to  make  curscr and the physical screen look like stdscr.  When the user
     program terminates, it should  call  the  endwin()  function  to  restore
     things to normal.

     There are all sorts of window  manipulation  routines  available  to  the
     programmer:  auxiliary windows may be created, edited, moved and deleted.
     The terminal may be set in many  different  modes,  output  text  may  be
     attributed with blink, blank, bold and reverse attributes.  Screen colors
     may also be set, foreground and background.   There  are  window-specific
     printf-  and  scanf-like  routines,  routines for scrolling, box-drawing,
     window overlaying, clearing routines etc.

     For more and detailed information, see the  library  source  codes.   All
     curses functions are preceded by a complete description.


FUNCTIONS

     Below is a list over the  available  functions,  together  with  a  brief
     description  of  what  they  do.  In general, functions whose names start
     with 'w' differ from the one without 'w' (like wmove  vs.  move)  signify
     that  a  specific  window is used. Without a 'w', sdtscr is implied.  The
     functions that start  with  'mv'  before  the  'genereic'  function  name
     signify that a cursor motion should be made before the actual work.  'mv'
     and 'w' combine as expected.

     Most routines that return an int will return the manifest constant ERR if
     there  is  a  failure  during  execution.   Routines  that  return a char
     actually return an int, so that ERR does not conflict with the  character
     code  0xff.   All  characters  from  0 to 0xff are allowed for usage with
     curses.

     Some  routines,  like  {mv}{w}  printw()  and  {mv}{w}scanw()  return   a
     meaningful positive value if the operation is successful.


     The curses package uses some predefined  types,  variables  and  manifest
     constants  that  are  also available to the programmer.  There are also a
     few globally accessible variables that  should  not  be  touched  by  the
     application  program.   Those  untouchable  variables have names starting
     with an underscore (_) to avoid conflicts.   The  user-accessible  types,
     variables  and  constants  are  (there  are  a  number of other constants
     defining character attribute names  and  function  key  names  -  consult
     <curses.h> for details):

     (manifest constants)
          TRUE                                boolean true
          FALSE                               boolean false
          ERR                                 unsuccessfull operation
          OK                                  successfull operation

     (types)
          WINDOW                              a window structure type
          bool                                boolean flag type

     (variables)
          WINDOW curscr                       physical display image
          WINDOW stdscr                       default user drawing board
          int LINES                           terminal height
          int COLS                            terminal width
          int NONL                            \n causes CR and LF when TRUE

     The following is an alphabetical list of the curses  functions,  together
     with  their  types,  parameters  and  a  short comment for each (win is a
     window, ch, vc, hc are characters, buf is a character buffer, attrs is an
     attribute  bit map, bf is a boolean flag.  Note that `characters' in this
     context usually can have 16 bits):

     int waddch(win,ch)                  put char in stdscr
     int addch(ch)
     int mvaddch(y,x,ch)
     int mvwaddch(win,y,x,ch)

     int waddstr(win,str)                put string in stdscr
     int addstr(str)
     int mvaddstr(y,x,str)
     int mvwaddstr(win,y,x,str)

     void wattroff(win,attrs)            clear attribute(s) in window
     void attroff(attrs)

     void wattron(win,attrs)             add attribute(s) in window
     void attron(attrs)

     void wattrset(win,attrs)            set window char attributes
     void attrset(attrs)
     int baudrate()                      dummy for compatibility

     void beep()                         ring the bell or visible bell  if  no
     bell available

     void flash()                        flash terminal screen or  rings  bell
     if no visible bell available

     void wbox(win,miny,minx,maxy,maxx,vc,hc) box  in  a  window,  with  given
     characters
     void box(win,vc,hc)

     void cbreak()                       set terminal cbreak mode

     void wclear(win)                    clear stdscr
     void clear()

     void clearok(win,bf)                marks window for screen clear

     int wclrtobot(win)                  clear from cursor to end of line  and
     all lines down this line
     int clrtobot()
     int mvclrtoeol(y,x)
     int mvwclrtobot(win,y,x)

     int wclrtoeol(win)                  clear from cursor to end of line
     int clrtoeol()
     int mvclrtoeol(y,x)
     int mvwclrtoeol(win,y,x)

     int wdelch(win)                     delete a char in a window
     int delch()
     int mvdelch(y,x)
     int mvwdelch(win,y,x)

     int wdeleteln(win)                  delete a line in a window
     int deleteln()
     int mvdeleteln(y,x)
     int mvwdeleteln(win,y,x)

     void delwin(win)                    delete a window or a subwindow
     void doupdate()                     update physical screen
     void echo()                         set terminal echo mode
     int endwin()                        cleanup and curses finitialization

     void werase(win)                    erase a window
     void erase()

     int erasechar()                     return char delete character
     int fixterm()                       dummy for compatibility
     void flushinp()                     kill pending keyboard input

     int wgetch(win)                     get char via a window
     int getch()
     int mvgetch(y,x)
     int mvwgetch(win,y,x)

     int wgetstr(win,str)                get string via window to a buffer
     int getstr(str)
     int mvgetstr(y,x,str)
     int mvwgetstr(win,y,x,str)

     void getyx(win,y,x)                 get a window's cursor position

     int gettmode()                      dummy for compatibility
     void idlok(win,bf)                  dummy for compatibility
     WINDOW *initscr()                   curses initialization (ret stdscr  or
     NULL)

     int winch(win)                      get char at window cursor
     int inch()
     int mvinch(y,x)
     int mvwinch(win,y,x)

     int winsch(win,ch)                  insert character in a window
     int insch(ch)
     int mvinsch(y,x,ch)
     int mvwinsch(win,y,x,ch)

     int winsertln(win)                  insert new line in a window
     int insertln()
     int mvinsertln(y,x)
     int mvwinsertln(win,y,x)

     void keypad(win,bf)                 marks a window for keypad usage
     int killchar()                      return line delete character
     char *longname()                    returns terminal description string
     void leaveok(win,bf)                marks  window  for   cursor   'update
     leave'
     void meta(win,bf)                   marks window for meta
     int move(y,x)                       move cursor in stdscr
     int mvcur(oldy,oldx,y,x)            move terminal cursor to <y,x>

     int mvprintw(y,x,fmt,args)          move & print string in stdscr

     int mvscanw(y,x,fmt,args)           move & get values via stdscr
     int mvwin(win,y,x)                  move window on physical screen
     int mvwprintw(win,x,y,fmt,args)     move & print string in a window
     int mvwscanw(win,y,x,fmt,args)      move & get values via a window
     WINDOW *newwin(lines,cols,begy,begx) create a new window
     void nl()                           set terminal cr-crlf mapping mode
     void nocbreak()                     unset terminal cbreak mod
     void nodelay(win,bf)                marks window for no input wait
     void noecho()                       unset terminal echo mode
     void nonl()                         unset terminal cr-crlf mapping mode
     void noraw()                        unset raw terminal mode
     void overlay(win1,win2)             overlay one window on another
     void overwrite(win1,win2)           overwrite one window on another
     int printw(fmt,args)                print string in stdscr
     void raw()                          set raw terminal mode
     void refrbrk(bf)                    set screen update break mode
     void refresh()                      refresh stdscr
     int resetterm()                     dummy for compatibility
     int resetty()                       restore terminal I/O modes
     int saveoldterm()                   dummy for compatibility
     int saveterm()                      dummy for compatibility
     int savetty()                       save terminal I/O modes
     int scanw(fmt,args)                 get values via stdscr
     void scroll(win)                    scroll scrolling region of a window
     void scrollok(win,bf)               marks a window to allow scroll
     void setcolors(A_COLOR(for,back))   sets the forground and background
                                         colors of stdscr
     void set_curs(visibility)           0 for invisible, 1 for visible, 2 for
     good
                                         visible
     int setsrcreg(miny,maxy)            define stdscr's scroll region
     int setterm()                       dummy for compatibility
     int setupterm(term,fd,errret)       set up terminal
     void standend()                     start normal chars in stdscr
     void standout()                     start standout chars in stdscr
     WINDOW *subwin(win,lines,cols,begy,begx)
                                         create a sub-window in window win
     int tabsize(ts)                     set/get tabsize of stdscr
     void touchwin(win)                  mark a window as totally modified
     char *unctrl(ch)                    char-to-string converter
     int wmove(win,y,x)                  move cursor in a window
     void wnoutrefresh(win)              create internal screen image
     int wprintw(win,fmt,args)           print string in a window
     void wrefresh(win)                  refresh window
     int wscanw(win,fmt,args)            get values via a window
     void wsetcolors(win,A_COLOR(for,back)) sets the forground and
                                         background colors  of  the  specified
     window
     int wsetsrcreg(win,miny,maxy)       define a window's scrolling region
     void wstandend(win)                 start normal chars in window
     void wstandout(win)                 start standout chars in window
     int wtabsize(win,ts)                set/get tabsize of a window




BUGS

     Function keys are not available under the MINIX version.