diff options
Diffstat (limited to 'lib/libcurses/PSD.doc/intro.3')
| -rw-r--r-- | lib/libcurses/PSD.doc/intro.3 | 228 |
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. |
