BSD 4.4 Lite Lib Sources

1 files changed, 228 insertions, 0 deletions

diff --git a/lib/libcurses/PSD.doc/intro.3 b/lib/libcurses/PSD.doc/intro.3
new file mode 100644
index 0000000..d0ba9a2
--- /dev/null
+++ b/lib/libcurses/PSD.doc/intro.3
@@ -0,0 +1,228 @@
+.\" Copyright (c) 1980, 1993
+.\"	The Regents of the University of California.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"	@(#)intro.3	8.1 (Berkeley) 6/4/93
+.\"
+.sh 1 Usage
+.pp
+This is a description of how to actually use the screen package.
+For simplicity, we assume all updating, reading, etc.
+is applied to
+.Vn stdscr , 
+although a different window can of course be specified.
+.sh 2 "Initialization"
+.pp
+In order to use the screen package,
+the routines must know about terminal characteristics,
+and the space for
+.Vn curscr
+and
+.Vn stdscr
+must be allocated.
+These functions are performed by
+.Fn initscr .
+Since it must allocate space for the windows,
+it can overflow core when attempting to do so.
+On this rather rare occasion,
+.Fn initscr
+returns ERR.
+.Fn Initscr
+must
+.bi always
+be called before any of the routines which affect windows are used.
+If it is not,
+the program will core dump as soon as either
+.Vn curscr
+or
+.Vn stdscr
+are referenced.
+However, it is usually best to wait to call it
+until after you are sure you will need it,
+like after checking for startup errors.
+Terminal status changing routines
+like
+.Fn nl
+and
+.Fn cbreak
+should be called after
+.Fn initscr .
+.pp
+After the initial window allocation done by 
+.Fn initscr ,
+specific window characteristics can be set.
+Scrolling can be enabled by calling
+.Fn scrollok .
+If you want the cursor to be left after the last change, use
+.Fn leaveok .
+If this isn't done,
+.Fn refresh
+will move the cursor to the window's current \*y after updating it.
+Additional windows can be created by using the functions
+.Fn newwin
+and
+.Fn subwin .
+.Fn Delwin
+allows you to delete an exisiting window.
+The variables
+.Vn LINES
+and
+.Vn COLS
+control the size of the terminal.  They are initially implicitly set by 
+.Fn initscr ,
+but can be altered explicitly by the user followed by a call to 
+.Fn initscr .
+Note that any call to 
+.Fn initscr ,
+will always delete any existing
+.Vn stdscr
+and/or
+.Vn curscr
+before creating new ones so this change is best done before the initial call to
+.Fn initscr .
+.pp
+.sh 2 "Output"
+.pp
+The basic functions
+used to change what will go on a window are
+.Fn addch
+and
+.Fn move .
+.Fn Addch
+adds a character at the current \*y,
+returning ERR if it would cause the window to illegally scroll,
+.i i.e. ,
+printing a character in the lower right-hand corner
+of a terminal which automatically scrolls
+if scrolling is not allowed.
+.Fn Move
+changes the current \*y to whatever you want them to be.
+It returns ERR if you try to move off the window.
+As mentioned above, you can combine the two into
+.Fn mvaddch
+to do both things in one call.
+.pp
+The other output functions 
+(such as
+.Fn addstr
+and
+.Fn printw )
+all call
+.Fn addch
+to add characters to the window.
+.pp
+After a change has been made to the window,
+you must call 
+.Fn refresh .
+when you want the portion of the terminal covered by the window
+to reflect the change.
+In order to optimize finding changes,
+.Fn refresh
+assumes that any part of the window not changed
+since the last
+.Fn refresh
+of that window has not been changed on the terminal,
+.i i.e. ,
+that you have not refreshed a portion of the terminal
+with an overlapping window.
+If this is not the case,
+the routines
+.Fn touchwin ,
+.Fn touchline ,
+and
+.Fn touchoverlap
+are provided to make it look like a desired part of window has been changed,
+thus forcing
+.Fn refresh
+to check that whole subsection of the terminal for changes.
+.pp
+If you call
+.Fn wrefresh
+with
+.Vn curscr ,
+it will make the screen look like the image of 
+.Vn curscr .
+This is useful for implementing a command
+which would redraw the screen in case it got messed up.
+.sh 2 Input
+.pp
+Input is essentially a mirror image of output.
+The complementary function to
+.Fn addch
+is
+.Fn getch
+which,
+if echo is set,
+will call
+.Fn addch
+to echo the character.
+Since the screen package needs to know what is on the terminal at all times,
+if characters are to be echoed,
+the tty must be in raw or cbreak mode.
+If it is not,
+.Fn getch
+sets it to be cbreak,
+and then reads in the character.
+.sh 2 "Termination"
+.pp
+In order to perform certain optimizations,
+and, 
+on some terminals,
+to work at all,
+some things must be done
+before the screen routines start up.
+These functions are performed in
+.Fn getttmode
+and
+.Fn setterm ,
+which are called by
+.Fn initscr .
+In order to clean up after the routines,
+the routine
+.Fn endwin
+is provided.
+It restores tty modes to what they were
+when
+.Fn initscr
+was first called.
+The terminal state module uses the variable 
+.Vn curses_termios
+to save the original terminal state which is then restored upon a call to 
+.Fn endwin .
+Thus,
+anytime after the call to initscr,
+.Fn endwin
+should be called before exiting.  Note however, that 
+.Fn endwin 
+should always be called 
+.b before
+the final calls to
+.Fn delwin ,
+which free the storage of the windows.