Commit | Line | Data |
---|---|---|
ea56bb60 KB |
1 | .\" Copyright (c) 1980 The Regents of the University of California. |
2 | .\" All rights reserved. | |
9c6a28be | 3 | .\" |
ea56bb60 KB |
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 | .\" | |
1c15e888 | 16 | .\" @(#)intro.3 6.2 (Berkeley) 3/17/89 |
9c6a28be KM |
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 | |
1268a632 | 59 | .Fn cbreak |
9c6a28be KM |
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, | |
1268a632 | 110 | .i i.e. , |
9c6a28be KM |
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, | |
1268a632 | 141 | .i i.e. , |
9c6a28be KM |
142 | that you have not refreshed a portion of the terminal |
143 | with an overlapping window. | |
144 | If this is not the case, | |
1268a632 KM |
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 | |
9c6a28be | 152 | .Fn refresh |
1268a632 | 153 | check that whole subsection of the terminal for changes. |
9c6a28be KM |
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. |