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