man/man3/curses.3

   1 .TH CURSES 3
   2 .SH NAME
   3 curses \- screen/window management library
   4 .SH SYNOPSIS
   5 cc demo.c -lcurses
   6 .SH DESCRIPTION
   7 Curses is a library of screen and window management routines.  It is modeled
   8 after the UNIX curses and ncurses libraries. Normally, programs written for
   9 curses should be easily ported to UNIX, and vice versa.
  10 .PP
  11 To use the routines, the function initscr() must first be called.
  12 This creates two 'windows' for the user: stdscr and curscr.  Stdscr is the
  13 default
  14 window for the user to make changes on, and curscr reflects the current
  15 contents of the physical display screen.  The user writes or edits the stdscr
  16 window to his liking, then calls the refresh() function to make curscr
  17 and the physical screen look like stdscr.  When the user program terminates,
  18 it should call the endwin() function to restore things to normal.
  19 .PP
  20 There are all sorts of window manipulation routines available to the
  21 programmer: auxiliary windows may be created, edited, moved and deleted.  The
  22 terminal may be set in many different modes, output text may be attributed
  23 with blink, blank, bold and reverse attributes.  Screen colors may also be
  24 set, foreground and background.  There are window-specific
  25 printf- and scanf-like routines, routines for scrolling, box-drawing,
  26 window overlaying, clearing routines etc.
  27 .PP
  28 For more and detailed information, see the library source codes.  All curses
  29 functions are preceded by a complete description.
  30 .SH FUNCTIONS
  31 Below is a list over the available functions, together with a brief
  32 description of what they do.  In general, functions whose names start with 'w'
  33 differ from the one without 'w' (like wmove vs. move) signify that
  34 a specific window is used. Without a 'w', sdtscr is implied.  The functions
  35 that start with 'mv' before the 'genereic' function name signify that a
  36 cursor motion should be made before the actual work.  'mv' and 'w' combine
  37 as expected.
  38 .PP
  39 Most routines that return an int will return the manifest constant ERR if
  40 there is a failure during execution.  Routines that return a char actually
  41 return an int, so that ERR does not conflict with the character code 0xff.
  42 All characters from 0 to 0xff are allowed for usage with curses.
  43 .PP
  44 Some routines, like {mv}{w} printw() and {mv}{w}scanw() return a meaningful
  45 positive value if the operation is successful.
  46 .PP
  47 The curses package uses some predefined types, variables and manifest
  48 constants that are also available to the programmer.  There are also a few
  49 globally accessible variables that should not be touched by the application
  50 program.  Those untouchable variables have names starting with an
  51 underscore (_) to avoid conflicts.  The user-accessible types, variables
  52 and constants are (there are a number of other constants defining character
  53 attribute names and function key names - consult <curses.h> for details):
  54 .sp
  55 .nf
  56 .ta 3i
  57 (manifest constants)
  58 .RS
  59 TRUE    boolean true
  60 FALSE   boolean false
  61 ERR     unsuccessfull operation
  62 OK      successfull operation
  63 .RE
  64 .sp
  65 (types)
  66 .RS
  67 WINDOW  a window structure type
  68 bool    boolean flag type
  69 .RE
  70 .sp
  71 (variables)
  72 .RS
  73 WINDOW curscr   physical display image
  74 WINDOW stdscr   default user drawing board
  75 int LINES       terminal height
  76 int COLS        terminal width
  77 int NONL        \\n causes CR and LF when TRUE
  78 .RE
  79 .sp
  80 .fi
  81 The following is an alphabetical list of the curses functions, together
  82 with their types, parameters and a short comment for each (win is a window,
  83 ch, vc, hc are characters, buf is a character buffer, attrs is an
  84 attribute bit map, bf is a boolean flag.  Note that `characters' in this
  85 context usually can have 16 bits):
  86 .nf
  87 .sp
  88 int waddch(win,ch)      put char in stdscr
  89 int addch(ch)
  90 int mvaddch(y,x,ch)
  91 int mvwaddch(win,y,x,ch)
  92
  93 int waddstr(win,str)    put string in stdscr
  94 int addstr(str)
  95 int mvaddstr(y,x,str)
  96 int mvwaddstr(win,y,x,str)
  97
  98 void wattroff(win,attrs)        clear attribute(s) in window
  99 void attroff(attrs)
 100
 101 void wattron(win,attrs) add attribute(s) in window
 102 void attron(attrs)
 103
 104 void wattrset(win,attrs)        set window char attributes
 105 void attrset(attrs)
 106
 107 int baudrate()  dummy for compatibility
 108
 109 void beep()     ring the bell or visible bell if no bell available
 110
 111 void flash()    flash terminal screen or rings bell if no visible bell available
 112
 113 void wbox(win,miny,minx,maxy,maxx,vc,hc)        box in a window, with given characters
 114 void box(win,vc,hc)
 115
 116 void cbreak()   set terminal cbreak mode
 117
 118 void wclear(win)        clear stdscr
 119 void clear()
 120
 121 void clearok(win,bf)    marks window for screen clear
 122
 123 int wclrtobot(win)      clear from cursor to end of line and all lines down this line
 124 int clrtobot()
 125 int mvclrtoeol(y,x)
 126 int mvwclrtobot(win,y,x)
 127
 128 int wclrtoeol(win)      clear from cursor to end of line
 129 int clrtoeol()
 130 int mvclrtoeol(y,x)
 131 int mvwclrtoeol(win,y,x)
 132
 133 int wdelch(win) delete a char in a window
 134 int delch()
 135 int mvdelch(y,x)
 136 int mvwdelch(win,y,x)
 137
 138 int wdeleteln(win)      delete a line in a window
 139 int deleteln()
 140 int mvdeleteln(y,x)
 141 int mvwdeleteln(win,y,x)
 142
 143 void delwin(win)        delete a window or a subwindow
 144 void doupdate() update physical screen
 145 void echo()     set terminal echo mode
 146 int endwin()    cleanup and curses finitialization
 147
 148 void werase(win)        erase a window
 149 void erase()
 150
 151 int erasechar() return char delete character
 152 int fixterm()   dummy for compatibility
 153 void flushinp() kill pending keyboard input
 154
 155 int wgetch(win) get char via a window
 156 int getch()
 157 int mvgetch(y,x)
 158 int mvwgetch(win,y,x)
 159
 160 int wgetstr(win,str)    get string via window to a buffer
 161 int getstr(str)
 162 int mvgetstr(y,x,str)
 163 int mvwgetstr(win,y,x,str)
 164
 165 void getyx(win,y,x)     get a window's cursor position
 166
 167 int gettmode()  dummy for compatibility
 168 void idlok(win,bf)      dummy for compatibility
 169 WINDOW *initscr()       curses initialization (ret stdscr or NULL)
 170
 171 int winch(win)  get char at window cursor
 172 int inch()
 173 int mvinch(y,x)
 174 int mvwinch(win,y,x)
 175
 176 int winsch(win,ch)      insert character in a window
 177 int insch(ch)
 178 int mvinsch(y,x,ch)
 179 int mvwinsch(win,y,x,ch)
 180
 181 int winsertln(win)      insert new line in a window
 182 int insertln()
 183 int mvinsertln(y,x)
 184 int mvwinsertln(win,y,x)
 185
 186 void keypad(win,bf)     marks a window for keypad usage
 187 int killchar()  return line delete character
 188 char *longname()        returns terminal description string
 189 void leaveok(win,bf)    marks window for cursor 'update leave'
 190 void meta(win,bf)       marks window for meta
 191 int move(y,x)   move cursor in stdscr
 192 int mvcur(oldy,oldx,y,x)        move terminal cursor to <y,x>
 193
 194 int mvprintw(y,x,fmt,args)      move & print string in stdscr
 195
 196 int mvscanw(y,x,fmt,args)       move & get values via stdscr
 197 int mvwin(win,y,x)      move window on physical screen
 198 int mvwprintw(win,x,y,fmt,args) move & print string in a window
 199 int mvwscanw(win,y,x,fmt,args)  move & get values via a window
 200 WINDOW *newwin(lines,cols,begy,begx)    create a new window
 201 void nl()       set terminal cr-crlf mapping mode
 202 void nocbreak() unset terminal cbreak mod
 203 void nodelay(win,bf)    marks window for no input wait
 204 void noecho()   unset terminal echo mode
 205 void nonl()     unset terminal cr-crlf mapping mode
 206 void noraw()    unset raw terminal mode
 207 void overlay(win1,win2) overlay one window on another
 208 void overwrite(win1,win2)       overwrite one window on another
 209 int printw(fmt,args)    print string in stdscr
 210 void raw()      set raw terminal mode
 211 void refrbrk(bf)        set screen update break mode
 212 void refresh()  refresh stdscr
 213 int resetterm() dummy for compatibility
 214 int resetty()   restore terminal I/O modes
 215 int saveoldterm()       dummy for compatibility
 216 int saveterm()  dummy for compatibility
 217 int savetty()   save terminal I/O modes
 218 int scanw(fmt,args)     get values via stdscr
 219 void scroll(win)        scroll scrolling region of a window
 220 void scrollok(win,bf)   marks a window to allow scroll
 221 void setcolors(A_COLOR(for,back))       sets the forground and background
 222         colors of stdscr
 223 void set_curs(visibility)       0 for invisible, 1 for visible, 2 for good
 224         visible
 225 int setsrcreg(miny,maxy)        define stdscr's scroll region
 226 int setterm()   dummy for compatibility
 227 int setupterm(term,fd,errret)   set up terminal
 228 void standend() start normal chars in stdscr
 229 void standout() start standout chars in stdscr
 230 WINDOW *subwin(win,lines,cols,begy,begx)
 231         create a sub-window in window win
 232 int tabsize(ts) set/get tabsize of stdscr
 233 void touchwin(win)      mark a window as totally modified
 234 char *unctrl(ch)        char-to-string converter
 235 int wmove(win,y,x)      move cursor in a window
 236 void wnoutrefresh(win)  create internal screen image
 237 int wprintw(win,fmt,args)       print string in a window
 238 void wrefresh(win)      refresh window
 239 int wscanw(win,fmt,args)        get values via a window
 240 void wsetcolors(win,A_COLOR(for,back))  sets the forground and
 241         background colors of the specified window
 242 int wsetsrcreg(win,miny,maxy)   define a window's scrolling region
 243 void wstandend(win)     start normal chars in window
 244 void wstandout(win)     start standout chars in window
 245 int wtabsize(win,ts)    set/get tabsize of a window
 246 .SH BUGS
 247 Function keys are not available under the MINIX version.
 248 .\" $PchId: curses.3,v 1.3 1996/02/22 21:26:28 philip Exp $