1 .\" Copyright (c) 1980, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)intro.3 8.1 (Berkeley) 6/4/93
37 This is a description of how to actually use the screen package.
38 For simplicity, we assume all updating, reading, etc.
41 although a different window can of course be specified.
42 .sh 2 "Initialization"
44 In order to use the screen package,
45 the routines must know about terminal characteristics,
51 These functions are performed by
53 Since it must allocate space for the windows,
54 it can overflow core when attempting to do so.
55 On this rather rare occasion,
61 be called before any of the routines which affect windows are used.
63 the program will core dump as soon as either
68 However, it is usually best to wait to call it
69 until after you are sure you will need it,
70 like after checking for startup errors.
71 Terminal status changing routines
76 should be called after
79 After the initial window allocation done by
81 specific window characteristics can be set.
82 Scrolling can be enabled by calling
84 If you want the cursor to be left after the last change, use
88 will move the cursor to the window's current \*y after updating it.
89 Additional windows can be created by using the functions
94 allows you to delete an exisiting window.
99 control the size of the terminal. They are initially implicitly set by
101 but can be altered explicitly by the user followed by a call to
103 Note that any call to
105 will always delete any existing
109 before creating new ones so this change is best done before the initial call to
115 used to change what will go on a window are
120 adds a character at the current \*y,
121 returning ERR if it would cause the window to illegally scroll,
123 printing a character in the lower right-hand corner
124 of a terminal which automatically scrolls
125 if scrolling is not allowed.
127 changes the current \*y to whatever you want them to be.
128 It returns ERR if you try to move off the window.
129 As mentioned above, you can combine the two into
131 to do both things in one call.
133 The other output functions
140 to add characters to the window.
142 After a change has been made to the window,
145 when you want the portion of the terminal covered by the window
146 to reflect the change.
147 In order to optimize finding changes,
149 assumes that any part of the window not changed
152 of that window has not been changed on the terminal,
154 that you have not refreshed a portion of the terminal
155 with an overlapping window.
156 If this is not the case,
162 are provided to make it look like a desired part of window has been changed,
165 to check that whole subsection of the terminal for changes.
171 it will make the screen look like the image of
173 This is useful for implementing a command
174 which would redraw the screen in case it got messed up.
177 Input is essentially a mirror image of output.
178 The complementary function to
186 to echo the character.
187 Since the screen package needs to know what is on the terminal at all times,
188 if characters are to be echoed,
189 the tty must be in raw or cbreak mode.
192 sets it to be cbreak,
193 and then reads in the character.
196 In order to perform certain optimizations,
200 some things must be done
201 before the screen routines start up.
202 These functions are performed in
208 In order to clean up after the routines,
212 It restores tty modes to what they were
216 The terminal state module uses the variable
218 to save the original terminal state which is then restored upon a call to
221 anytime after the call to initscr,
223 should be called before exiting. Note however, that
225 should always be called
229 which free the storage of the windows.