1 02/08/88  CURSES Operation Details
  2 
  3 Insert and delete line and character:
  4 
  5 The algorithm used by CURSES takes into account insert and delete
  6 line and character functions, if available, in the terminal.  Calling
  7 the routine
  8                     idlok(stdscr, TRUE);
  9 
 10 will enable insert/delete line.  By default, CURSES will not use
 11 insert/delete line.  This was not done for performance reasons, since
 12 there is no speed penalty involved.  Rather, experience has shown
 13 that some programs do not need this facility, and that if CURSES uses
 14 insert/delete line, the result on the screen can be visually
 15 annoying.  Since many simple programs using CURSES do not need this,
 16 the default is to avoid insert/delete line.  Insert/delete character
 17 is always considered.
 18 
 19 
 20 Additional terminals:
 21 
 22 CURSES will work even if absolute cursor addressing is not possible,
 23 as long as the cursor can be moved from any location to any other
 24 location.  It considers local motions, parameterized motions, home,
 25 and carriage return.
 26 
 27 CURSES is aimed at full duplex, alphanumeric, video terminals.  No
 28 attempt is made to handle half-duplex, synchronous, hard copy, or
 29 bitmapped terminals.  Bitmapped terminals can be handled by
 30 programming them to emulate an ordinary alphanumeric terminal.  This
 31 does not take advantage of the bitmap capabilities, but it is the
 32 fundamental nature of CURSES to deal with alphanumeric terminals.
 33 
 34 
 35 The CURSES handles terminals with the "magic cookie glitch" in their
 36 video attributes.  The term "magic cookie" means that a change in
 37 video attributes is implemented by storing a "magic cookie" in a
 38 location on the screen.  The "cookie" takes up a space , preventing
 39 an exact implementation of what the programmer wanted.  CURSES takes
 40 the extra space into account, and moves part of the line to the
 41 right, as necessary.  In some cases, this will unavoidably result in
 42 losing text from the right hand edge of the screen.  Advantage is
 43 taken of existing spaces.
 44 
 45 
 46 Multiple terminals:
 47 
 48 Some applications need to display text on more than one terminal,
 49 controlled by the same process.  Even if the terminals are of
 50 different types, CURSES can handle this.
 51 
 52 All information about the current terminal is kept in a global
 53 variable
 54 
 55           struct screen *SP;
 56 
 57 Although the screen structure is hidden from the user, the C compiler
 58 will accept declarations of variables which are pointers.  The user
 59 program should declare one screen pointer variable for each terminal
 60 it wishes to handle.
 61 
 62 
 63 The routine
 64 
 65           struct screen *newterm(type, fd)
 66 
 67 will set up a new terminal of the given terminal type which does
 68 output on file descriptor fd.  A call to initscr is essentially
 69 newterm(getenv("TERM"),stdout).  A program wishing to use more than
 70 one terminal should use newterm for each terminal and save the value
 71 returned as a reference to that terminal.
 72 
 73 
 74 To switch to a different terminal, call
 75 
 76           set_term(term)
 77 
 78 The old value of SP will be returned.  The programmer should not
 79 assign directly to SP because certain other global variables must
 80 also be changed.
 81 
 82 All CURSES routines always affect the current terminal.  To handle
 83 several terminals, switch to each one in turn with set_term, and then
 84 access it.  Each terminal must be set up with newterm, and closed
 85 down with endwin.
 86 
 87 
 88 Video attributes:
 89 
 90 Video attributes can be displayed in any combination on terminals
 91 with this capability.  They are treated as an extension of the
 92 standout capability, which is still present.
 93 
 94 Each character position on the screen has 16 bits of information
 95 associated with it.  Seven of these bits are the character to be
 96 displayed, leaving separate bits for nine video attributes.  These
 97 bits are used for standout, underline, reverse video, blink, dim,
 98 bold, blank, protect, and alternate character set.  Standout is taken
 99 to be whatever highlighting works best on the terminal, and should be
100 used by any program that does not need specific or combined
101 attributes.  Underlining, reverse video, blink, dim, and bold are the
102 usual video attributes.  Blank means that the character is displayed
103 
104 
105 as a space, for security reasons.  Protected and alternate character
106 set depend on the particular terminal.  The use of these last three
107 bits is subject to change and not recommended.  Note also that not
108 all terminals implement all attributes - in particular, no current
109 terminal implements both dim and bold.
110 
111 The routines to use these attributes include
112 
113           attrset(attrs)                wattrset(win, attrs)
114           attron(attrs)                 wattron(win, attrs)
115           attroff(attrs)                wattroff(win, attrs)
116           standout()                    wstandout(win)
117           standend()                    wstandend(win)
118 
119 
120 Attributes, if given, can be any combination of a A_STANDOUT,
121 A_UNDERLINE, A_REVERSE, A_BLINK, A_DIM, A_BOLD, A_INVIS, A_PROTECT,
122 and A_ALTCHARSET.  These constants, defined in CURSES.h, can be
123 combined with the C | (or) operator to get multiple attributes.
124 attrset sets the current attributes to the given attrs; attron turns
125 on the given attrs in addition to any attributes that are already on;
126 attroff turns off the given attributes, without affecting any others.
127 standout and standend are equivalent to attron(A_STANDOUT) and
128 attrset(A_NORMAL).
129 
130 If the particular terminal does not have the particular attribute or
131 combination requested, CURSES will attempt to use some other
132 attribute in its place.  If the terminal has no highlighting at all,
133 all attributes will be ignored.
134 
135 
136 Special keys:
137 
138 Many terminals have special keys, such as arrow keys, keys to erase
139 the screen, insert or delete text, and keys intended for user
140 functions.  The particular sequences these terminals send differs
141 from terminal to terminal.  CURSES allows the programmer to handle
142 these keys.
143 
144 A program using special keys should turn on the keypad by calling
145 
146           keypad(stdscr, TRUE)
147 
148 at initialization.  This will cause special characters to be passed
149 through to the program by the function getch.  These keys have
150 constants which are listed in the section called "Input" in the
151 information segment introduction.gi.info
152 
153 
154 They have values starting at 0401, so they should not be stored in a
155 char variable, as significant bits will be lost.
156 
157 A program using special keys should avoid using the escape key, since
158 most sequences start with escape, creating an ambiguity.  CURSES will
159 set a one second alarm to deal with this ambiguity, which will cause
160 delay response to the escape key.  It is a good idea to avoid escape
161 in any case, since there is eventually pressure for nearly any screen
162 oriented program to accept arrow key input.
163 
164 
165 Scrolling region:
166 
167 There is a programmer accessible scrolling region.  Normally, the
168 scrolling region is set to the entire window, but the calls
169 
170           setscrreg(top, bot)
171           wsetscrreg(win, top, bot)
172 
173 set the scrolling region for stdscr or the given window to any
174 combination of top and bottom margins.  When scrolling past the
175 bottom margin of the scrolling region, the lines in the region will
176 move up one line, destroying the top line of the region.  If
177 scrolling has been enabled with scrollok, scrolling will take place
178 only within that window.  Note that the scrolling region is a
179 software feature, and only causes a window data structure to scroll.
180 
181 
182 This may or may not translate to use of the hardware scrolling region
183 feature of a terminal, or insert/delete line.
184 
185 
186 MINICURSES:
187 
188 CURSES copies from the current window to an internal screen image for
189 every call to refresh.  If the programmer is only interested in
190 screen output optimization, and does not want the windowing or input
191 functions, an interface to the lower level routines is available.
192 This will make the program somewhat smaller and faster.  The
193 interface is a subset of full CURSES, so that conversion between the
194 levels in not necessary to switch from MINICURSES to full CURSES.
195 
196 
197 The following functions of CURSES and terminfo are available to the
198 user of MINICURSES:
199 
200 addch(ch)           addstr(str)         attroff(at)         attron(at)
201 attrset(at)         clear()             erase()             initscr
202 move(y,x)           mvaddch(y,x,ch)     mvaddstr(y,x,str)   newterm
203 refresh()           standend()          standout()
204 
205 
206 The following functions of CURSES and terminfo are not  available to
207 the user of MINICURSES:
208 
209 box                 clrtobot            clrtoeol            delch
210 deleteln            delwin              getch               getstr
211 inch                insch               insertln            longname
212 makenew             mvdelch             mvgetch             mvgetstr
213 mvinch              mvinsch             mvprintw            mvscanw
214 mvwaddch            mvwaddstr           mvwdelch            mvwgetch
215 mvwgetstr           mvwin               mvwinch             mvwinsch
216 mvwprintw           mvwscanw            newwin              overlay
217 overwrite           printw              putp                scanw
218 scroll              setscrreg           subwin              touchwin
219 vidattr             waddch              waddstr             wclear
220 
221 
222 wclrtobot           wclrtoeol           wdelch              wdeleteln
223 werase              wgetch              wgetstr             winsch
224 winsertln           wmove               wprintw             wrefresh
225 wscanw              wsetscrreg
226 
227 The subset mainly requires the programmer to avoid use of more than
228 the one window stdscr.  Thus, all functions beginning with "w" are
229 generally undefined.  Certain high level functions that are
230 convenient but not essential are also not available, including printw
231 and scanw.  Also, the input routine getch cannot be used with
232 MINICURSES.  Features implemented at a low level, such as use of
233 hardware insert/delete line and video attributes, are available in
234 both versions.  Also, mode setting routines such as crmode and noecho
235 are allowed.
236 
237 To access MINICURSES, add -def MINICURSES to the CFLAGS in the
238 makefile.  If routines are requested that are not in the subset, they
239 will cuase a linkage error upon execution.
240 
241 
242 TTY mode functions:
243 
244 In addition to the save/restore routines savetty() and resetty(),
245 standard routines are available for going into and out of normal tty
246 mode.  These routines are resetterm(), which puts the terminal back
247 in the mode it was in when CURSES was started; fixterm(), which
248 undoes the effects of resetterm, that is, restores the "current
249 CURSES mode"; and saveterm(), which saves the current state to be
250 used by fixterm().  endwin automatically calls resetterm.  These
251 routines are also available at the terminfo level.
252 
253 
254 Typeahead check:
255 
256 If the user types something during an update, the update will stop,
257 pending a future update.  This is useful when the user hits several
258 keys, each of which causes a good deal of output.  For example, in a
259 screen editor, if the user presses the "forward screen" key, which
260 draws the next screen full of text, several times rapidly, rather
261 than drawing screens of text, the updates will be cut short, and only
262 the last screen full will actually be displayed.  This feature is
263 automatic and cannot be disabled.
264 
265 
266 getstr:
267 
268 No matter what the setting of echo is, strings typed in here are
269 echoed at the current cursor location.  The users erase and kill
270 characters are understood and handled.  This makes it unnecessary for
271 an interactive program to deal with erase, kill and echoing when the
272 user is typing a line of text.
273 
274 
275 longname:
276 
277 The longname function does not need any arguments.  It returns a
278 pointer to a static area containing the actual long name of the
279 terminal.
280 
281 
282 Nodelay mode:
283 
284 The call
285 
286           nodelay(stdscr, TRUE)
287 
288 will put the terminal in "nodelay mode".  While in this mode, any
289 call to getch will return -1 if there is nothing waiting to be read
290 immediately.  This is useful for writing programs requiring "real
291 time" behavior where the users watch action on the screen and press a
292 key when they want something to happen.  For example, the cursor can
293 be moving across the screen, in real time.  When it reaches a certain
294 point, the user can press an arrow key to change direction at that
295 point.
296 
297 
298 Portability:
299 
300 Several useful routines are provided to improve portability.  The
301 implementation of these routines is different from system to system,
302 and the differences can be isolated from the user program by
303 including them in CURSES.
304 
305 Functions erasechar() and killchar() return the characters which
306 erase one character, and kill the entire input line, respectively.
307 The function baudrate() will return the current baud rate, as an
308 integer.  (For example, at 9600 baud, the integer 9600 will be
309 returned, not the value B9600 from <sgtty.h>.) The routine flushinp()
310 will cause all typeahead to be thrown away.
311 
312 
313 
314