freebsd/lib/libcurses/PSD.doc/intro.1

.\" 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.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.