1 04/15/88  CURSES
  2 
  3 This segment briefly describes CURSES and contains a lists of all
  4 CURSES functions, TERMINFO routines, TERMCAP compatibiity routines,
  5 function keys, and video attributes.
  6 
  7 
  8 For information on the differences between UNIX CURSES and Multics
  9 CURSES, type
 10 
 11           help curses_changes.gi.info
 12 
 13 For a information on using CURSES, type
 14 
 15           help curses_user_guide.gi.info
 16 
 17 and for information on TERMINFO, TERM and TIC, type
 18 
 19           help terminal_information.gi.info
 20 
 21 
 22 Name:
 23 
 24 curses -- CRT screen handling and optimization package
 25 
 26 
 27 Synopsis:
 28 
 29 include <curses.h>
 30 cc [ flags ] files -lb >sl3p>cc>e>libcurses.archive [ libraries ]
 31 
 32 
 33 Description:
 34 
 35 These routines give the user a method of updating screens with
 36 reasonable optimization.  In order to initialize the routines, the
 37 routine initscr() must be called before any of the other routines
 38 that deal with windows and screens are used.  The routine endwin()
 39 should be called before exiting.  To get character-at-a-time input
 40 without echoing, (most interactive, screen oriented-programs want
 41 this) after calling initscr() you should call "nonl(); cbreak();
 42 noecho()."
 43 
 44 The full curses interface permits manipulation of data structures
 45 called "windows" which can be thought of as two dimensional arrays of
 46 characters representing all or part of a CRT screen.  A default
 47 window called stdscr is supplied, and others can be created with
 48 
 49 
 50 newwin.  Windows are referred to by variables declared "WINDOW *",
 51 the type WINDOW is defined in curses.h to be a C structure.  These
 52 data sructures are manipulated with functions described below, among
 53 which the most basic are move, and addch.  (More general versions of
 54 these functions are included with names beginninng with 'w', allowing
 55 you to specify a window.  The routines not beginning with 'w' affect
 56 stdscr.)  Then refresh() is called, telling the routines to make the
 57 users CRT screen look like stdscr.
 58 
 59 MINICURSES is a subset of curses which does not allow manipulation of
 60 more than one window.  To invoke this subset, use -def MINICURSES as
 61 a cc option.  This level is smaller and faster than full curses.
 62 
 63 If the environment variable TERMINFO is defined, any program using
 64 curses will check for a local terminal definition before checking in
 65 
 66 
 67 the standard place.  For example, if the standard place is
 68 sl3p>cc>e>terminfo, and TERM is set to "vt100", then normally the
 69 compiled file is found in >sl3p>cc>e>terminfo>v>vt100.  (The "v" is
 70 copied from the first letter of "vt100" to avoid creation of huge
 71 directories.) However, if TERMINFO is set to
 72 >udd>Calgary>Mark>myterms, curses will first check
 73 >udd>Calgary>Mark>myterms>v>vt100, and if that fails, will then check
 74 >sl3p>cc>e>terminfo>v>vt100.  This is useful for developing
 75 experimental definitions or when write permission in
 76 >sl3p>cc>e>terminfo is not available.
 77 
 78 
 79 Functions:
 80 
 81 Routines listed here may be called when using the full curses.  Those
 82 marked with an asterisk may be called when using MINICURSES.
 83 
 84 addch(ch)*          add a character to stdscr (like putchar)
 85                     (wraps to next line at end of line)
 86 addstr(str)*        calls addch with each character in str
 87 attroff(attrs)*     turn off attributes named
 88 attron(attrs)*      turn on attributes named
 89 attrset(attrs)*     set current attributes to attrs
 90 baudrate()*         current terminal speed
 91 beep()*             sound beep on terminal
 92 
 93 
 94 box(win, vert, hor) draw a box around edges of win
 95                     vert and hor are chars to use for vert. and hor.
 96                     edges of box
 97 clear()             clear stdscr
 98 clearok(win,bf)     clear screen before next redraw of win
 99 clrtobot()          clear to botton of stdscr
100 clrtoeol()          clear to end of line on stdscr
101 cbreak()*           set cbreak mode
102 delay_output(ms)*   insert ms millisecond pause in output
103 delch()             delete a character
104 deleteln()          delete a line
105 delwin(win)         delete win
106 doupdate()          update screen from all wnooutrefresh
107 echo()*             set echo mode
108 endwin()*           end window modes
109 
110 
111 erase()             erase stdscr
112 erasechar ()        return user's erase character
113 fixterm()           restore tty to "in curses" state
114 flash()             flash screen or beep
115 flushinp()*         throw away any typeahead
116 getch()*            get a char from tty
117 getstr(str)         get a string through stdscr
118 gettmode()          establish current tty modes
119 getyx(win, y, x)    get (y, x) co-ordinates
120 has_ic()            true if terminal can do insert character
121 has_il()            true if terminal can do insert line
122 idlok(win, bf)*     use terminal's insert/delete line if bf!= 0
123 inch ()             get char at current (y, x) co-ordinates
124 initscr ()*         initialize screens
125 insch (c)           insert a char
126 
127 
128 insertln()          insert a line
129 intrflush (win, bf) interrupts flush output if bf is TRUE
130 keypad (win, bf)    enable keypad input
131 killchar()          return current user's kill character
132 leaveok(win, flag)  OK to leave cursor anywhere after refresh if
133                     flag!=0 for win, otherwise cursor must be left
134                     at current position.
135 longname()          return verbose name of terminal
136 meta (win, flag)*   allow meta characters on input if flag!=0
137 move(y, x)*         move to (y, x) on stdscr
138 mvaddch (y, x, ch)  move (y, x) then addch (ch)
139 mvaddstr (y, x, str) similar...
140 mvcur (oldrow, oldcol, newrow, newcol) low level cursor motion
141 mvdelch (y, x)      like delch, but move (y, x) first
142 mvgetch (y, x)      etc.
143 
144 
145 mvgetstr (y, x)
146 mvinch (y, x)
147 mvinsch (y, x, c)
148 mvprintw(y, x. fmt, args)
149 mvscanw(y, x, fmt, args)
150 mvwaddch(win, y, x, ch)
151 mvwaddstr(win, y, x. str)
152 mvwdelch (win, y, x)
153 mvwgetch(win, y, x)
154 mvwgetstr(win, y, x)
155 mvwin(win, by, bx)
156 mvwinch(win, y, x)
157 mvwinsch(win, y, x, c)
158 mvwprintw(win, y, x, fmt, args)
159 mvwscanw(win, y, x, fmt, args)
160 
161 
162 newpad(nlines, ncols) create a new pad with given dimensions
163 newterm(type, fd)   set up new terminal of given type to output on fd
164 newwin(lines, cols, begin_y, begin_x) create a new window
165 nl()*               set newline mapping
166 nocbreak()*         unset cbreak mode
167 nodelay(win, bf)    enable nodelay input mode through getch
168 noecho()*           unset echo mode
169 nonl()*             unset newline mapping
170 noraw()*            unset raw mode
171 overlay(win1, win2) overlay win1 on win2
172 overwrite(win1, win2) overwrite win1 on top of win2
173 pnoutrefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)
174                     like prefresh but with no output until
175                     doupdate called
176 
177 
178 prefresh(pad, pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol)
179                     refresh from pad starting with given upper left
180                     corner of pad with output to given portion of screen
181 printw(fmt, arg1, arg2, ...) printf on stdscr
182 raw()*              set raw mode
183 refresh()*          make current screen look like stdscr
184 resetterm()*        set tty modes to "out of curses" state
185 resetty()*          reset tty flags to stored value
186 saveterm()*         save current modes as "in curses" state
187 savetty()*          store current tty flags
188 scanw(fmt, arg1, arg2, ...) scanf through stdscr
189 scroll(win)         scroll win one line
190 scrollok(win, flag) allow terminal to scroll if flag!= 0
191 set_term(new)       now talk to terminal new
192 setscrreg(t, b)     set user scrolling region to lines t through b
193 
194 
195 setterm(type)       establish terminal with given type
196 setupterm(term, filenum, errret)
197 standend()*         clear standout mode attribute
198 standout()*         set standout mode attribute
199 subwin(win, lines, cols, begin_y, begin_x) create a subwindow
200 touchwin(win)       change all of win
201 traceoff()          turn off debugging trace output
202 traceon()           turn on debugging trace output
203 typeahead(fd)       use file descriptor fd to check typeahead
204 unctrl(ch)*         printable version of ch
205 waddch(win, ch)     add char to win
206 waddstr(win, str)   add string to win
207 wattroff(win, attrs) turn off attrs in win
208 wattron(win, attrs) turn on attrs in win
209 wattrset(win, attrs) set attrs in win to attrs
210 
211 
212 wclear(win)         clear win
213 wclrtobot)win)      clear to bottom of win
214 wclrtoeol(win)      clear to end of line on win
215 wdelch(win, c)      delete char from win
216 wdeleteln(win)      delete line from win
217 werase(win)         erase win
218 wgetch(win)         get a char through win
219 wgetstr(win, str)   get a string through win
220 winch(win)          get char at current (y, x) in win
221 winsch(win, c)      insert char into win
222 winsertln(win)      insert line into win
223 wmove(win, y, x)    set current (y, x) co-ordinates on win
224 wnoutrefresh(win)   refresh but no screen output
225 wprintw(win, fmt, arg1, arg2, ...) printf on win
226 wrefresh(win)       make screen look like win
227 
228 
229 wscan(win, fmt, arg1, arg2, ...) scanf through win
230 wsetscrreg(win, t, b) set scrolling region of win
231 wstandend(win)      clear standout attribute in win
232 wstandout(win)      set standout attribute in win
233 
234 
235 TERMINFO Level Routines:
236 
237 These routines should be called by programs wishing to deal directly
238 with the terminfo database.  Due to the low level of this interface,
239 it is discouraged.  Initially, setupterm should be called.  This will
240 define the set of terminal dependent variables (which are defined in
241 the info segment terminfo.gi.info).  The include files <curses.h>
242 and <term.h> should be included to get the definitions for these
243 strings, numbers, and flags.  Parmeterized strings should be passed
244 through tparm to instantiate them.  All terminfo strings (including
245 the output of tparm) should be printed with tputs or putp.  Before
246 exiting, resetterm should be called to restore the tty modes.
247 (Programs desiring shell escapes or suspending with control Z can
248 call resetterm before the shell is called and fixterm after returning
249 from the shell.)
250 
251 
252 fixterm()           restore tty modes for terminfo use
253                     (called by setupterm)
254 resetterm()         reset tty modes to state before program entry
255 setupterm(term, fd, rc) read in database.  Terminal type is the
256                     character string term, all output is to
257                     file descriptor fd.  A status value is
258                     returned in the integer pointed to by rc: 1 is
259                     normal.  The simplest call would be
260                     setupterm(NULL, 1, NULL) which uses all the
261                     defaults.
262 tparm(str, p1, p2, ..., p9) instantiate string with parms p(p1...pn)
263 tputs(str, affcnt, putc) apply padding info to string str.
264                     affcnt is the number of lines affected, or 1 if
265                     not applicable.  Putc is a putchar-like function
266                     to which the characters are passed, one at a time.
267 
268 
269 putp(str)           handy function that calls tputs(str, 1, putchar).
270 vidputs(attrs, putc) output the string to put terminal in vide
271                     attribute mode attrs, which is any combination
272                     of the attributes listed below.  Chars are passed
273                     to putchar-like function putc.
274 vidattr(attrs)      Like vidputs but outputs through putchar
275 
276 
277 Termcap Compatibility Routines:
278 
279 These routines were included as a conversion aid for programs that
280 use termcap.  Their parameters are the same as for termcap.  They are
281 emulated using the terminfo database.  They may go away at a later
282 date.
283 
284 tgetent(bp, name)   look up termcap entry for name
285 tgetflag(id)        get boolean entry for id
286 tgetnum(id)         get numeric entry for id
287 tgetstr(id, area)   get string entry for id
288 tgoto(cap, col, row) apply parms to given cap
289 tputs(cap, affcnt, fn) apply padding to cap calling fn as putchar
290 
291 
292 Attributes:
293 
294 The following video attributes can be passed to the functions attron,
295 attroff, attrset.
296 
297 A_STANDOUT          Terminal's best highlighting mode
298 A_UNDERLINE         Underlining
299 A_REVERSE           Reverse video
300 A_BLINK             Blinking
301 A_DIM               Half bright
302 A-BOLD              Extra bright or bold
303 A-BLANK             Blanking (invisible)
304 A_PROTECT           Protected
305 A_ALTCHARSET        Alternate character set
306 
307 
308 Function Keys:
309 
310 The following function keys might be returned by getch if keypad has
311 been enabled.  Note that not all of these are currently supported,
312 due to lack of definitions in terminfo or the terminal not transmitting
313 a unique code when the key is pressed.
314 
315 Name                Value     Key Name
316 
317 KEY_BREAK           0401      break key (unreliable)
318 KEY_DOWN            0402      The four arrow keys ...
319 KEY_UP              0403
320 KEY_LEFT            0404
321 KEY_RIGHT           0405      ...
322 KEY_HOME            0406      Home key (upward+left arrow)
323 
324 
325 KEY_BACKSPACE       0407      backspace (unreliable)
326 FEY_FO              0410      Function keys. Space for 64 is
327                               reserved.
328 KEY_F(n)    (KEY_F0+(n))      Formula for fn.
329 KEY_DL              0510      Delete line
330 KEY_IL              0511      Insert line
331 KEY_DC              0512      Delete character
332 KEY_IC              0513      Insert char or enter insert mode
333 KEY_EIC             0514      Exit inset char mode
334 KEY_CLEAR           0515      Clear screen
335 KEY_EOS             0516      Clear to end of screen
336 KEY_EOL             0517      Clear to end of line
337 KEY_SF              0520      Scroll 1 line forward
338 KEY_SR              0521      Scroll 1 line backwards (reverse)
339 KEY_NPAGE           0522      Next page
340 
341 
342 KEY_PPAGE           0523      Previous page
343 KEY_STAB            0524      Set tab
344 KEY_CTAB            0525      Clear tab
345 KEY_CATAB           0526      Clear all tabs
346 KEY_ENTER           0527      Enter or send (unreliable)
347 KEY_SRESET          0530      soft (partial) reset (unreliable)
348 KEY_RESET           0531      reset or hard reset (unreliable)
349 KEY_PRINT           0532      print or copy
350 KEY_LL              0533      home down or botton (lower left)
351