248 lines
6.8 KiB
Groff
248 lines
6.8 KiB
Groff
|
.\" $NetBSD: intro.1,v 1.7 2003/08/07 16:44:27 agc Exp $
|
||
|
|
.\"
|
||
|
|
.\" 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. 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.1 8.1 (Berkeley) 6/4/93
|
||
|
|
.\"
|
||
|
|
.bp
|
||
|
|
.sh 1 Overview
|
||
|
|
.pp
|
||
|
|
In making available the generalized terminal descriptions in \*(tc,
|
||
|
|
much information was made available to the programmer,
|
||
|
|
but little work was taken out of one's hands.
|
||
|
|
The purpose of this package is to allow the C programmer
|
||
|
|
to do the most common type of terminal dependent functions,
|
||
|
|
those of movement optimization and optimal screen updating,
|
||
|
|
without doing any of the dirty work,
|
||
|
|
and with nearly as much ease as is necessary to simply print
|
||
|
|
or read things.
|
||
|
|
.sh 2 "Terminology"
|
||
|
|
.pp
|
||
|
|
In this document, the following terminology is used:
|
||
|
|
.de Ip
|
||
|
|
.sp
|
||
|
|
.in 5n
|
||
|
|
.ti 0n
|
||
|
|
.b "\\$1" :
|
||
|
|
..
|
||
|
|
.Ip window
|
||
|
|
An internal representation
|
||
|
|
containing an image of what a section of the terminal screen may look like
|
||
|
|
at some point in time.
|
||
|
|
This subsection can either encompass the entire terminal screen,
|
||
|
|
or any smaller portion down to a single character within that screen.
|
||
|
|
.Ip terminal
|
||
|
|
Sometimes called
|
||
|
|
.b terminal
|
||
|
|
.b screen .
|
||
|
|
The package's idea of what the terminal's screen currently looks like,
|
||
|
|
.i i.e. ,
|
||
|
|
what the user sees now.
|
||
|
|
This is a special
|
||
|
|
.i screen :
|
||
|
|
.Ip screen
|
||
|
|
This is a subset of windows which are as large as the terminal screen,
|
||
|
|
.i i.e. ,
|
||
|
|
they start at the upper left hand corner
|
||
|
|
and encompass the lower right hand corner.
|
||
|
|
One of these,
|
||
|
|
.Vn stdscr ,
|
||
|
|
is automatically provided for the programmer.
|
||
|
|
.rm Ip
|
||
|
|
.sh 2 "Compiling Applications"
|
||
|
|
.pp
|
||
|
|
In order to use the library,
|
||
|
|
it is necessary to have certain types and variables defined.
|
||
|
|
Therefore, the programmer must have a line:
|
||
|
|
.(l
|
||
|
|
.b "#include <curses.h>"
|
||
|
|
.)l
|
||
|
|
at the top of the program source.
|
||
|
|
Compilations should have the following form:
|
||
|
|
.(l
|
||
|
|
.ie t \fBcc\fR [ \fIflags\fR ] file ... \fB\-lcurses \-ltermcap\fR
|
||
|
|
.el \fIcc\fR [ flags ] file ... \fI\-lcurses \-ltermcap\fR
|
||
|
|
.)l
|
||
|
|
.sh 2 "Screen Updating"
|
||
|
|
.pp
|
||
|
|
In order to update the screen optimally,
|
||
|
|
it is necessary for the routines to know what the screen currently looks like
|
||
|
|
and what the programmer wants it to look like next.
|
||
|
|
For this purpose,
|
||
|
|
a data type
|
||
|
|
(structure)
|
||
|
|
named
|
||
|
|
.Vn WINDOW
|
||
|
|
is defined
|
||
|
|
which describes a window image to the routines,
|
||
|
|
including its starting position on the screen
|
||
|
|
(the \*y of the upper left hand corner)
|
||
|
|
and its size.
|
||
|
|
One of these
|
||
|
|
(called
|
||
|
|
.Vn curscr
|
||
|
|
for
|
||
|
|
.i "current screen" )
|
||
|
|
is a screen image of what the terminal currently looks like.
|
||
|
|
Another screen
|
||
|
|
(called
|
||
|
|
.Vn stdscr ,
|
||
|
|
for
|
||
|
|
.i "standard screen" )
|
||
|
|
is provided
|
||
|
|
by default
|
||
|
|
to make changes on.
|
||
|
|
.pp
|
||
|
|
A window is a purely internal representation.
|
||
|
|
It is used to build and store
|
||
|
|
a potential image of a portion of the terminal.
|
||
|
|
It doesn't bear any necessary relation
|
||
|
|
to what is really on the terminal screen.
|
||
|
|
It is more like an array of characters on which to make changes.
|
||
|
|
.pp
|
||
|
|
When one has a window which describes
|
||
|
|
what some part the terminal should look like,
|
||
|
|
the routine
|
||
|
|
.Fn refresh
|
||
|
|
(or
|
||
|
|
.Fn wrefresh
|
||
|
|
if the window is not
|
||
|
|
.Vn stdscr )
|
||
|
|
is called.
|
||
|
|
.Fn refresh
|
||
|
|
makes the terminal,
|
||
|
|
in the area covered by the window,
|
||
|
|
look like that window.
|
||
|
|
Note, therefore, that changing something on a window
|
||
|
|
.i does
|
||
|
|
.bi not
|
||
|
|
.i "change the terminal" .
|
||
|
|
Actual updates to the terminal screen
|
||
|
|
are made only by calling
|
||
|
|
.Fn refresh
|
||
|
|
or
|
||
|
|
.Fn wrefresh .
|
||
|
|
This allows the programmer to maintain several different ideas
|
||
|
|
of what a portion of the terminal screen should look like.
|
||
|
|
Also, changes can be made to windows in any order,
|
||
|
|
without regard to motion efficiency.
|
||
|
|
Then, at will,
|
||
|
|
the programmer can effectively say
|
||
|
|
.q "make it look like this" ,
|
||
|
|
and the package will execute the changes in an optimal way.
|
||
|
|
.sh 2 "Naming Conventions"
|
||
|
|
.pp
|
||
|
|
As hinted above,
|
||
|
|
the routines can use several windows,
|
||
|
|
but two are always available:
|
||
|
|
.Vn curscr ,
|
||
|
|
which is the image of what the terminal looks like at present,
|
||
|
|
and
|
||
|
|
.Vn stdscr ,
|
||
|
|
which is the image of what the programmer wants the terminal to look like next.
|
||
|
|
The user should not access
|
||
|
|
.Vn curscr
|
||
|
|
directly.
|
||
|
|
Changes should be made to
|
||
|
|
the appropriate screen,
|
||
|
|
and then the routine
|
||
|
|
.Fn refresh
|
||
|
|
(or
|
||
|
|
.Fn wrefresh )
|
||
|
|
should be called.
|
||
|
|
.pp
|
||
|
|
Many functions are set up to deal with
|
||
|
|
.Vn stdscr
|
||
|
|
as a default screen.
|
||
|
|
For example, to add a character to
|
||
|
|
.Vn stdscr ,
|
||
|
|
one calls
|
||
|
|
.Fn addch
|
||
|
|
with the desired character.
|
||
|
|
If a different window is to be used,
|
||
|
|
the routine
|
||
|
|
.Fn waddch
|
||
|
|
(for
|
||
|
|
.b w indow-specific
|
||
|
|
.Fn addch )
|
||
|
|
is provided\**.
|
||
|
|
.(f
|
||
|
|
\**
|
||
|
|
Actually,
|
||
|
|
.Fn addch
|
||
|
|
is really a
|
||
|
|
.q #define
|
||
|
|
macro with arguments,
|
||
|
|
as are most of the "functions" which act upon
|
||
|
|
.Vn stdscr .
|
||
|
|
.)f
|
||
|
|
This convention of prepending function names with a
|
||
|
|
.Bq w
|
||
|
|
when they are to be applied to specific windows
|
||
|
|
is consistent.
|
||
|
|
The only routines which do
|
||
|
|
.i not
|
||
|
|
do this are those
|
||
|
|
to which a window must always be specified.
|
||
|
|
.pp
|
||
|
|
In order to move the current \*y from one point to another,
|
||
|
|
the routines
|
||
|
|
.Fn move
|
||
|
|
and
|
||
|
|
.Fn wmove
|
||
|
|
are provided.
|
||
|
|
However,
|
||
|
|
it is often desirable to first move and then perform some I/O operation.
|
||
|
|
In order to avoid clumsiness,
|
||
|
|
most I/O routines can be preceded by the prefix
|
||
|
|
.Bq mv
|
||
|
|
and the desired \*y can then be added to the arguments to the function.
|
||
|
|
For example,
|
||
|
|
the calls
|
||
|
|
.(l
|
||
|
|
move(y\*,x);
|
||
|
|
addch(ch);
|
||
|
|
.)l
|
||
|
|
can be replaced by
|
||
|
|
.(l
|
||
|
|
mvaddch(y\*,x\*,ch);
|
||
|
|
.)l
|
||
|
|
and
|
||
|
|
.(l
|
||
|
|
wmove(win\*,y\*,x);
|
||
|
|
waddch(win\*,ch);
|
||
|
|
.)l
|
||
|
|
can be replaced by
|
||
|
|
.(l
|
||
|
|
mvwaddch(win\*,y\*,x\*,ch);
|
||
|
|
.)l
|
||
|
|
Note that the window description pointer
|
||
|
|
.Vn win ) (
|
||
|
|
comes before the added \*y.
|
||
|
|
If a window pointer is needed, it is always the first parameter passed.
|