![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to intro.3 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.3 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.3 6.2 (Berkeley) 3/17/89
17: .\"
18: .sh 1 Usage
19: .pp
20: This is a description of how to actually use the screen package.
21: In it, we assume all updating, reading, etc.
22: is applied to
23: .Vn stdscr .
24: All instructions will work on any window,
25: with changing the function name and parameters as mentioned above.
26: .sh 2 "Starting up"
27: .pp
28: In order to use the screen package,
29: the routines must know about terminal characteristics,
30: and the space for
31: .Vn curscr
32: and
33: .Vn stdscr
34: must be allocated.
35: These functions are performed by
36: .Fn initscr .
37: Since it must allocate space for the windows,
38: it can overflow core when attempting to do so.
39: On this rather rare occasion,
40: .Fn initscr
41: returns ERR.
42: .Fn initscr
43: must
44: .bi always
45: be called before any of the routines which affect windows are used.
46: If it is not,
47: the program will core dump as soon as either
48: .Vn curscr
49: or
50: .Vn stdscr
51: are referenced.
52: However, it is usually best to wait to call it
53: until after you are sure you will need it,
54: like after checking for startup errors.
55: Terminal status changing routines
56: like
57: .Fn nl
58: and
59: .Fn cbreak
60: should be called after
61: .Fn initscr .
62: .pp
63: Now that the screen windows have been allocated,
64: you can set them up for the run.
65: If you want to, say, allow the window to scroll,
66: use
67: .Fn scrollok .
68: If you want the cursor to be left after the last change, use
69: .Fn leaveok .
70: If this isn't done,
71: .Fn refresh
72: will move the cursor to the window's current \*y after updating it.
73: New windows of your own can be created, too, by using the functions
74: .Fn newwin
75: and
76: .Fn subwin .
77: .Fn delwin
78: will allow you to get rid of old windows.
79: If you wish to change the official size of the terminal by hand,
80: just set the variables
81: .Vn LINES
82: and
83: .Vn COLS
84: to be what you want,
85: and then call
86: .Fn initscr .
87: This is best done before,
88: but can be done either before or after,
89: the first call to
90: .Fn initscr ,
91: as it will always delete any existing
92: .Vn stdscr
93: and/or
94: .Vn curscr
95: before creating new ones.
96: .pp
97: .sh 2 "The Nitty-Gritty"
98: .sh 3 Output
99: .pp
100: Now that we have set things up,
101: we will want to actually update the terminal.
102: The basic functions
103: used to change what will go on a window are
104: .Fn addch
105: and
106: .Fn move .
107: .Fn addch
108: adds a character at the current \*y,
109: returning ERR if it would cause the window to illegally scroll,
110: .i i.e. ,
111: printing a character in the lower right-hand corner
112: of a terminal which automatically scrolls
113: if scrolling is not allowed.
114: .Fn move
115: changes the current \*y to whatever you want them to be.
116: It returns ERR if you try to move off the window when scrolling is not allowed.
117: As mentioned above, you can combine the two into
118: .Fn mvaddch
119: to do both things in one fell swoop.
120: .pp
121: The other output functions,
122: such as
123: .Fn addstr
124: and
125: .Fn printw ,
126: all call
127: .Fn addch
128: to add characters to the window.
129: .pp
130: After you have put on the window what you want there,
131: when you want the portion of the terminal covered by the window
132: to be made to look like it,
133: you must call
134: .Fn refresh .
135: In order to optimize finding changes,
136: .Fn refresh
137: assumes that any part of the window not changed
138: since the last
139: .Fn refresh
140: of that window has not been changed on the terminal,
141: .i i.e. ,
142: that you have not refreshed a portion of the terminal
143: with an overlapping window.
144: If this is not the case,
145: the routines
146: .Fn touchwin ,
147: .Fn touchline ,
148: and
149: .Fn touchoverlap
150: are provided to make it look like a desired part of window has been changed,
151: thus forcing
152: .Fn refresh
153: check that whole subsection of the terminal for changes.
154: .pp
155: If you call
156: .Fn wrefresh
157: with
158: .Vn curscr ,
159: it will make the screen look like
160: .Vn curscr
161: thinks it looks like.
162: This is useful for implementing a command
163: which would redraw the screen in case it get messed up.
164: .sh 3 Input
165: .pp
166: Input is essentially a mirror image of output.
167: The complementary function to
168: .Fn addch
169: is
170: .Fn getch
171: which,
172: if echo is set,
173: will call
174: .Fn addch
175: to echo the character.
176: Since the screen package needs to know what is on the terminal at all times,
177: if characters are to be echoed,
178: the tty must be in raw or cbreak mode.
179: If it is not,
180: .Fn getch
181: sets it to be cbreak,
182: and then reads in the character.
183: .sh 3 Miscellaneous
184: .pp
185: All sorts of fun functions exists for maintaining and changing information
186: about the windows.
187: For the most part,
188: the descriptions in section 5.4. should suffice.
189: .sh 2 "Finishing up"
190: .pp
191: In order to do certain optimizations,
192: and,
193: on some terminals,
194: to work at all,
195: some things must be done
196: before the screen routines start up.
197: These functions are performed in
198: .Fn getttmode
199: and
200: .Fn setterm ,
201: which are called by
202: .Fn initscr .
203: In order to clean up after the routines,
204: the routine
205: .Fn endwin
206: is provided.
207: It restores tty modes to what they were
208: when
209: .Fn initscr
210: was first called.
211: Thus,
212: anytime after the call to initscr,
213: .Fn endwin
214: should be called before exiting.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.