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