Commit | Line | Data |
---|---|---|
d3c0043c KA |
1 | .bp |
2 | .sh 1 Overview | |
3 | .pp | |
4 | In making available the generalized terminal descriptions in \*(tc, | |
5 | much information was made available to the programmer, | |
6 | but little work was taken out of one's hands. | |
7 | The purpose of this package is to allow the C programmer | |
8 | to do the most common type of terminal dependent functions, | |
9 | those of movement optimization and optimal screen updating, | |
10 | without doing any of the dirty work, | |
11 | and (hopefully) with nearly as much ease as is necessary to simply print | |
12 | or read things. | |
13 | .pp | |
14 | The package is split into three parts: | |
15 | (1) Screen updating; | |
16 | (2) Screen updating with user input; | |
17 | and | |
18 | (3) Cursor motion optimization. | |
19 | .pp | |
20 | It is possible to use the motion optimization | |
21 | without using either of the other two, | |
22 | and screen updating and input can be done | |
23 | without any programmer knowledge of the motion optimization, | |
24 | or indeed the \*(et \*(db itself. | |
25 | .sh 2 "Terminology (or, Words You Can Say to Sound Brilliant)" | |
26 | .pp | |
27 | In this document, | |
28 | the following terminology is kept to with reasonable consistency: | |
29 | .de Ip | |
30 | .sp | |
31 | .in 5n | |
32 | .ti 0n | |
33 | .bi "\\$1" : | |
34 | .. | |
35 | .Ip window | |
36 | An internal representation | |
37 | containing an image of what a section of the terminal screen may look like | |
38 | at some point in time. | |
39 | This subsection can either encompass the entire terminal screen, | |
40 | or any smaller portion down to a single character within that screen. | |
41 | .Ip "terminal" | |
42 | Sometimes called | |
43 | .bi terminal | |
44 | .bi screen . | |
45 | The package's idea of what the terminal's screen currently looks like, | |
46 | i.e., what the user sees now. | |
47 | This is a special | |
48 | .i screen : | |
49 | .Ip screen | |
50 | This is a subset of windows which are as large as the terminal screen, | |
51 | i.e., they start at the upper left hand corner | |
52 | and encompass the lower right hand corner. | |
53 | One of these, | |
54 | .Vn stdscr , | |
55 | is automatically provided for the programmer. | |
56 | .rm Ip | |
57 | .sh 2 "Compiling Things" | |
58 | .pp | |
59 | In order to use the library, | |
60 | it is necessary to have certain types and variables defined. | |
61 | Therefore, the programmer must have a line: | |
62 | .(l | |
63 | .b "#include <curses.h>" | |
64 | .)l | |
65 | at the top of the program source. | |
66 | The header file | |
67 | .b <curses.h> | |
68 | needs to include | |
69 | .b <sgtty.h> , | |
70 | so the one should not do so oneself\**. | |
71 | .(f | |
72 | \** | |
73 | The screen package also uses the Standard I/O library, | |
74 | so | |
75 | .b <curses.h> | |
76 | includes | |
77 | .b <stdio.h> . | |
78 | It is redundant | |
79 | (but harmless) | |
80 | for the programmer to do it, too. | |
81 | .)f | |
82 | Also, | |
83 | compilations should have the following form: | |
84 | .(l | |
85 | .ie t \fBcc\fR [ \fIflags\fR ] file ... \fB\-lcurses \-ltermlib\fR | |
86 | .el \fIcc\fR [ flags ] file ... \fI\-lcurses \-ltermlib\fR | |
87 | .)l | |
88 | .sh 2 "Screen Updating" | |
89 | .pp | |
90 | In order to update the screen optimally, | |
91 | it is necessary for the routines to know what the screen currently looks like | |
92 | and what the programmer wants it to look like next. | |
93 | For this purpose, | |
94 | a data type | |
95 | (structure) | |
96 | named | |
97 | .Vn WINDOW | |
98 | is defined | |
99 | which describes a window image to the routines, | |
100 | including its starting position on the screen | |
101 | (the \*y of the upper left hand corner) | |
102 | and its size. | |
103 | One of these | |
104 | (called | |
105 | .Vn curscr | |
106 | for | |
107 | .i "current screen" ) | |
108 | is a screen image of what the terminal currently looks like. | |
109 | Another screen | |
110 | (called | |
111 | .Vn stdscr , | |
112 | for | |
113 | .i "standard screen" ) | |
114 | is provided | |
115 | by default | |
116 | to make changes on. | |
117 | .pp | |
118 | A window is a purely internal representation. | |
119 | It is used to build and store | |
120 | a potential image of a portion of the terminal. | |
121 | It doesn't bear any necessary relation | |
122 | to what is really on the terminal screen. | |
123 | It is more like an array of characters on which to make changes. | |
124 | .pp | |
125 | When one has a window which describes | |
126 | what some part the terminal should look like, | |
127 | the routine | |
128 | .Fn refresh | |
129 | (or | |
130 | .Fn wrefresh | |
131 | if the window is not | |
132 | .Vn stdscr ) | |
133 | is called. | |
134 | .Fn refresh | |
135 | makes the terminal, | |
136 | in the area covered by the window, | |
137 | look like that window. | |
138 | Note, therefore, that changing something on a window | |
139 | .i does | |
140 | .bi not | |
141 | .i "change the terminal" . | |
142 | Actual updates to the terminal screen | |
143 | are made only by calling | |
144 | .Fn refresh | |
145 | or | |
146 | .Fn wrefresh . | |
147 | This allows the programmer to maintain several different ideas | |
148 | of what a portion of the terminal screen should look like. | |
149 | Also, changes can be made to windows in any order, | |
150 | without regard to motion efficiency. | |
151 | Then, at will, | |
152 | the programmer can effectively say | |
153 | .q "make it look like this," | |
154 | and let the package worry about the best way to do this. | |
155 | .sh 2 "Naming Conventions" | |
156 | .pp | |
157 | As hinted above, | |
158 | the routines can use several windows, | |
159 | but two are automatically given: | |
160 | .Vn curscr , | |
161 | which knows what the terminal looks like, | |
162 | and | |
163 | .Vn stdscr , | |
164 | which is what the programmer wants the terminal to look like next. | |
165 | The user should never really access | |
166 | .Vn curscr | |
167 | directly. | |
168 | Changes should be made to | |
169 | the appropriate screen, | |
170 | and then the routine | |
171 | .Fn refresh | |
172 | (or | |
173 | .Fn wrefresh ) | |
174 | should be called. | |
175 | .pp | |
176 | Many functions are set up to deal with | |
177 | .Vn stdscr | |
178 | as a default screen. | |
179 | For example, to add a character to | |
180 | .Vn stdscr , | |
181 | one calls | |
182 | .Fn addch | |
183 | with the desired character. | |
184 | If a different window is to be used, | |
185 | the routine | |
186 | .Fn waddch | |
187 | (for | |
188 | .b w indow-specific | |
189 | .Fn addch ) | |
190 | is provided\**. | |
191 | .(f | |
192 | \** | |
193 | Actually, | |
194 | .Fn addch | |
195 | is really a | |
196 | .q #define | |
197 | macro with arguments, | |
198 | as are most of the "functions" which deal with | |
199 | .Vn stdscr | |
200 | as a default. | |
201 | .)f | |
202 | This convention of prepending function names with a | |
203 | .Bq w | |
204 | when they are to be applied to specific windows | |
205 | is consistent. | |
206 | The only routines which do | |
207 | .i not | |
208 | do this are those | |
209 | to which a window must always be specified. | |
210 | .pp | |
211 | In order to move the current \*y from one point to another, | |
212 | the routines | |
213 | .Fn move | |
214 | and | |
215 | .Fn wmove | |
216 | are provided. | |
217 | However, | |
218 | it is often desirable to first move and then perform some I/O operation. | |
219 | In order to avoid clumsyness, | |
220 | most I/O routines can be preceded by the prefix | |
221 | .Bq mv | |
222 | and the desired \*y then can be added to the arguments to the function. | |
223 | For example, | |
224 | the calls | |
225 | .(l | |
226 | move(y\*,x); | |
227 | addch(ch); | |
228 | .)l | |
229 | can be replaced by | |
230 | .(l | |
231 | mvaddch(y\*,x\*,ch); | |
232 | .)l | |
233 | and | |
234 | .(l | |
235 | wmove(win\*,y\*,x); | |
236 | waddch(win\*,ch); | |
237 | .)l | |
238 | can be replaced by | |
239 | .(l | |
240 | mvwaddch(win\*,y\*,x\*,ch); | |
241 | .)l | |
242 | Note that the window description pointer | |
243 | .Vn win ) ( | |
244 | comes before the added \*y. | |
245 | If such pointers are need, | |
246 | they are always the first parameters passed. |