1 02/08/88  Introduction to CURSES
  2 
  3 This is an introduction to CURSES and TERMINFO.  It is intended for
  4 the programmer who must write a screen-oriented program using the
  5 CURSES package.
  6 
  7 For CURSES to be able to produce terminal dependent output, it has to
  8 know what kind of terminal you have.  The UNIX system convention for
  9 this is to put the name of the terminal in the variable TERM in the
 10 environment.  Thus, a user on a DEC VT100 would set TERM = vt100 when
 11 logging in.  CURSES uses this convention.
 12 
 13 
 14 Output:
 15 
 16 A program using CURSES always starts by calling initscr( ).  (See
 17 Figure 12-1.) Other modes can then be set as needed by the program.
 18 Possible modes include cbreak( ), and idlok(stdscr,TRUE).  These
 19 modes will be explained later.  During the execution of the program,
 20 output to the screen is done with routines such as addch(ch) and
 21 printw(fmt,args).  (These routines behave just like putchar and
 22 printf except that they go through CURSES.) The cursor can be moved
 23 with the call move(row,col).  These routines only output to a data
 24 structure called a window, not to the actual screen.  A window is a
 25 representation of a CRT screen, containing such things as an array of
 26 characters to be displayed on the screen, a cursor, a current set of
 27 video attributes, and various modes and options.  You don't
 28 
 29 
 30 need to worry about windows unless you use more than one of them,
 31 except to realize that a window is buffering your requests to output
 32 to the screen.
 33 
 34 To send all accumulated output, it is necessary to call refresh( ).
 35 
 36 (This can be thought of as a flush.) Finally, before the program
 37 exits, it should call endwin ( ), which restores all terminal
 38 settings and positions the cursor at the bottom of the screen.
 39 
 40 
 41 _____________________________________________________________
 42 
 43 #include <CURSES.h>
 44 ...
 45           initscr();  /*  Initialization  */
 46 
 47           cbreak(); /* Various optional mode settings  */
 48           nonl() ;
 49           noecho();
 50 ...
 51           while (!done)  {/* Main body of program */
 52               ...
 53               /* Sample calls to draw on screen  */
 54               move (row, col);
 55 
 56 
 57               addch(ch);
 58               printw("Formatted print with value %d\n", value);
 59               ...
 60               /* Flush output */
 61               refresh();
 62               ...
 63           }
 64 
 65           endwin(); /* Clean up */
 66           exit (0);
 67 
 68           Figure 12-1  Framework of a CURSES Program
 69 _____________________________________________________________
 70 
 71 
 72 Some programs assume all screens are 24 lines by 80 columns.  It is
 73 important to understand that many are not.  The variables LINES and
 74 COLS are defined by initscr with the current screen size.  Programs
 75 should use them instead of assuming a 24x80 screen.
 76 
 77 No output to the terminal actually happens until refresh is called.
 78 Instead, routines such as move and addch draw on a window data
 79 structure called stdscr (standard screen).  CURSES always keeps track
 80 of what is on the physical screen, as well as what is in stdscr.
 81 
 82 
 83 When refresh is called, CURSES compares the two screen images and
 84 sends a stream of characters to the terminal that will turn the
 85 current screen into what is desired.  CURSES considers many different
 86 ways to do this, taking into account the various capabilities of the
 87 terminal, and similarities between what is on the screen and what is
 88 desired.  It usually outputs as few characters as is possible.  This
 89 function is called cursor optimization and is the source of the name
 90 of the CURSES package.
 91 
 92 Note, due to the hardware scrolling of terminals, writing to the
 93 lower right-hand character position is impossible.
 94 
 95 
 96 Input:
 97 
 98 CURSES can do more than just draw on the screen.  Functions are also
 99 provided for input from the keyboard.  The primary function is
100 getch() which waits for the user to type a character on the keyboard,
101 and then returns that character.  This function is like getchar
102 except that it goes through CURSES.  Its use is recommended for
103 programs using the cbreak() or noecho() options, since several
104 terminal or system dependent options become available that are not
105 possible with getchar.
106 
107 Options available with getch include keypad which allows extra keys
108 such as arrow keys, function keys, and other special keys that
109 transmit escape sequences, to be treated as just another key.  (The
110 values returned for these keys are listed below.) KEY_LEFT in
111 
112 
113 CURSES.h.  The values for these keys are over octal 400, so they
114 should be stored in a variable larger than a char.) nodelay mode
115 causes the value -1 to be returned if there is no input waiting.
116 Normally, getch will wait until a character is typed.  Finally, the
117 routine getstr(str) can be called, allowing input of an entire line,
118 up to a new line.  This routine handles echoing and the erase and
119 kill characters of the user.  Examples of the use of these options
120 are in later example programs.
121 
122 The following function keys might be returned by getch if keypad has
123 been enabled.  Note that not all of these are currently supported,
124 due to lack of definitions in terminfo or the terminal not
125 transmitting a unique code when the key is pressed.
126 
127 
128 Name                     Value     Key name
129 
130 KEY_BREAK                0401      Break key(unreliable)
131 KEY_DOWN                 0402      The four arrow keys...
132 KEY_UP                   0403
133 KEY_LEFT                 0404
134 KEY_RIGHT                0405      ...
135 KEY_HOME                 0406      Home key (upward+left arrow)
136 KEY_BACKSPACE            0407      Backspace (unreliable)
137 KEY_F0                   0410      Function keys. Space for 64 keys
138                                    is reserved.
139 
140 
141 KEY_F(n)          KEY_F0+(n))      Formula for fn.
142 KEY_DL                   0510      Delete line
143 KEY_IL                   0511      Insert line
144 KEY_DC                   0512      Delete character
145 KEY_IC                   0513      Insert char or enter insert mode
146 KEY_EIC                  0514      Exit insert char mode
147 KEY_CLEAR                0515      Clear screen
148 KEY_EOS                  0516      Clear to end of screen
149 KEY_EOL                  0517      Clear to end of line
150 KEY_SF                   0520      Scroll 1 line forward
151 KEY_SR                   0521      Scroll 1 line backwards (reverse)
152 KEY_NPAGE                0522      Next page
153 
154 
155 KEY_PPAGE                0523      Previous page
156 KEY_STAB                 0524      Set tab
157 KEY_CTSB                 0525      Clear tab
158 KEY_CATAB                0526      Clear all tabs
159 KEY_ENTER                0527      Enter or send (unreliable)
160 KEY_SRESET               0530      Soft (partial) reset (unreliable)
161 KEY_RESET                0531      Reset or hard reset (unreliable)
162 KEY_PRINT                0532      Print or copy
163 KEY_LL                   0533      Home down or bottom (lower left)
164 
165