229 lines
6.4 KiB
Groff
229 lines
6.4 KiB
Groff
|
.\" 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.
|