document distributed with 4.3BSD

[unix-history] / usr / src / lib / libcurses / PSD.doc / intro.1

.\" Copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)intro.1	6.1 (Berkeley) %G%
.\"
.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 (hopefully) with nearly as much ease as is necessary to simply print
or read things.
.pp
The package is split into three parts:
(1) Screen updating;
(2) Screen updating with user input;
and
(3) Cursor motion optimization.
.pp
It is possible to use the motion optimization
without using either of the other two,
and screen updating and input can be done
without any programmer knowledge of the motion optimization,
or indeed the \*(et \*(db itself.
.sh 2 "Terminology (or, Words You Can Say to Sound Brilliant)"
.pp
In this document,
the following terminology is kept to with reasonable consistency:
.de Ip
.sp
.in 5n
.ti 0n
.bi "\\$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
.bi terminal
.bi 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 Things"
.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.
The header file
.b <curses.h>
needs to include
.b <sgtty.h> ,
so the one should not do so oneself\**.
.(f
\**
The screen package also uses the Standard I/O library,
so
.b <curses.h>
includes
.b <stdio.h> .
It is redundant
(but harmless)
for the programmer to do it, too.
.)f
Also,
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 let the package worry about the best way to do this.
.sh 2 "Naming Conventions"
.pp
As hinted above,
the routines can use several windows,
but two are automatically given:
.Vn curscr ,
which knows what the terminal looks like,
and
.Vn stdscr ,
which is what the programmer wants the terminal to look like next.
The user should never really 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 deal with
.Vn stdscr
as a default.
.)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 clumsyness,
most I/O routines can be preceded by the prefix
.Bq mv
and the desired \*y then can 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 such pointers are need,
they are always the first parameters passed.