intro.3cur

<B>Digital的Unix操作系统VAX 4.2源码</B>

.TH intro 3cur
.SH Name
intro \- introduction to the X/Open Curses Package, 
which optimizes terminal screen handling and updating 
.SH Syntax
.B #include <cursesX.h>
.br
.B cc
[ 
.I options
]
.I files
.B \-lcursesX
[ 
.I libraries 
]
.SH Description
.NXR "intro(3cur) keyword"
.NXR "curses package"
.NXR "cursor" "optimizing movement"
.NXR "curses library"
.NXR "curses package" "main routines"
.NXR "screen" "updating"
.NXR "window" "defined"
.NXR "terminal" "updating screen"
.PP
The
.PN curses 
(cursor optimization) package is the X/Open set of library routines 
used for writing 
screen-management programs.
Cursor optimization minimizes the amount the cursor has to be moved
around the screen in order to update it.
Screen-management programs are used for tasks such as moving the cursor, 
printing a menu, dividing a terminal
screen into windows or drawing a display on a screen for data entry and
retrieval.
.PP
The 
.PN curses 
package is split into three parts: screen updating,
screen updating with user input, and
cursor motion optimization.
Screen-updating routines are used when parts of the screen need to be
changed but the overall image remains the same.
The cursor motion part of the package can be used separately for tasks such
as defining how the cursor moves in response to tabs and newline characters
.PP
The
.PN curses
routines do not write directly to the terminal screen (the physical screen):
instead, they write to a
window,
a two-dimensional array of characters which 
represents all or part of
the terminal screen. 
A window can be as big as the terminal screen or any smaller size down to
a single character.
.PP
The 
.PN <cursesX.h> 
header file supplies two default 
windows,  
.PN stdscr
(standard screen) and
.PN curscr
(current screen) for all programs using
.PN curses
routines.
The
.PN stdscr 
window is the size of the current terminal screen. 
The
.PN curscr
window is not normally accessed directly by the screen-management program;
changes are made to the appropriate window and then
the
.PN refresh 
routine is called.
The screen program keeps track of what is on the physical screen
and what is on
.PN stdscr .
When 
.PN refresh 
is called,
it compares the two screen images and then sends a stream
of characters to the terminal to make the physical screen look like
.PN stdscr .
.PP
The header file
.PN <cursesX.h>
defines
.PN stdscr
to be of the type
.PN WINDOW* . 
This is a pointer to a C structure
which includes the starting position of the window on the screen and the window
size.
.PP
Some 
.PN curses
routines are designed to work with a 
.PN pad .
A pad is a type of window whose size is not restricted by the
size of the screen. 
Use a pad when you only need part of a window on the 
screen at any one time, 
for example when running a spreadsheet application.
.PP
Other windows can be created with
.PN newwin 
and used instead of
.PN stdscr
for maintaining several different screen images, for example,
one window can control input/output and
another can display error messages.
The routine 
.PN subwin 
creates subwindows within windows.
When windows overlap, the contents of the current screen show the most
recently refreshed window.
.PP
Among the most basic routines are
.PN move 
and
.PN addch .
These routines are used to move the cursor around
and to add characters to the default window,
.PN stdscr. 
.PP
All
.PN curses
data is manipulated using the routines provided by the 
.PN curses
library.
You should not use routines or system calls from other libraries in a 
.PN curses 
program as they may cause undesirable results when you run the program.
.PP
.B Using Curses
.PP    
The 
.PN curses 
library has three types of routines; 
Main 
routines, TERMINFO routines 
and TERMCAP compatibility routines
.PP
The 
.PN terminfo
routines are a group of routines within the
.PN curses
library which 
provide a database containing descriptions of many terminals that
can be used with
.PN curses
programs.
The termcap compatibility routines are provided as
a conversion aid for programs using termcap.
.PP
Most screen handling can be achieved using the 
Main
routines.  
The 
following hints should help you make the most of the screen-handling 
routines.
.PP
The 
.PN <cursesX.h>
header file must always be included whenever
.PN curses
functions are used in a program. Note that the header file includes
.PN <sgtty.h>
to enable the terminal to use the features provided by ULTRIX.
All the manual definitions assume that
.PN <cursesX.h>
has been included in the code.
.PP
The header file defines global variables and data structures, and 
defines several
of the routines as macros.
The integer variables 
.PN LINES
and 
.PN COLS
are defined
so that when a 
.PN curses 
program is run on a particular terminal, 
.PN initscr 
assigns
the vertical and horizontal dimensions
of the terminal screen to these variables.
.PP
A
.PN curses 
program must start by calling the routine
.PN initscr 
to allocate memory space for the windows.
It should only be called once in a program,
as it can overflow
core memory if it is called repeatedly.
The routine 
.PN endwin 
is used to exit from the screen-handling routines.
.PP
Most interactive screen-oriented programs need character-at-a-time
input without echoing.
To achieve this, you should call:
.EX
nonl();
cbreak();
noecho();
.EE
immediately after calling 
.PN initscr .
All 
.PN curses
routines that move the cursor, move it relative to the home 
position in the
upper left corner of the screen. The 
.PN (LINES ,
.PN COLS )
coordinate at this position is (1,1). 
Note that the vertical coordinate
.PN y
is given first and the horizontal coordinate
.PN x
is given second.
The \-1 in the example program takes the home position into account
to place the cursor on the centre line of the terminal screen.
The example program displays 
.B MIDSCREEN
in the centre of the screen.
Use
the
.PN refresh 
routine after changing a screen to make the terminal screen look like
.PN stdscr .
.PP
.B
Example Program
.R
.EX 0
#include <cursesX.h>
main ()
{
.EE
.EX
initscr();     /*initialize terminal settings, data
		 ** structures and variables*/
move(LINES/2 \-1, COLS/2 \-4);
addstr("MID");
refresh();     /* send output to update terminal 
                **  screen */
addstr("SCREEN");
refresh();     /* send more output to terminal 
                **  screen */
endwin();      /*restore all terminal settings */
.EE
.EX 0
}
.EE
.SH Main Routines
.PP
Routines listed here can be called when using 
the 
.PN curses
library.
Routines that are preceded by a 
.B w
affect a specified window,
those preceded by a 
.B p
affect a specified pad.
All other routines affect the default window 
.PN stdscr .
Windows are specified by a numeric argument, for example: 
.PN winch
(\fIwin\fR)
where
.I win 
is the specified window.
.PP
.ds w \fIwin\fR
.ds s \fHstdscr\fR
.TS
tab (#);
l l.

addch(ch)#T{
Add a character to \*s (like \fHputchar\fP wraps to next
line at end of line)
T}
addstr(str)#Call addch with each character in \fIstr\fP
attroff(attrs)#Turn off named attributes
attron(attrs)#Turn on named attributes
attrset(attrs)#Set current attributes to \fIattrs\fP
baudrate(\|)#Display current terminal speed
beep(\|)#Sound beep on terminal
box(win, vert, hor)#Draw a box around edges of \*w,
#\fIvert\fP and \fIhor\fP are characters to use for vertical
#and horizontal edges of box
clear(\|)#Clear \*s
clearok(win, bf)#Clear screen before next redraw of \*w
clrtobot(\|)#Clear to bottom of \*s
clrtoeol(\|)#Clear to end of line on \*s
cbreak(\|)#Set cbreak mode
delay_output(ms)#Insert \fIms\fP millisecond pause in output
delch(\|)#Delete a character
deleteln(\|)#Delete a line
delwin(win)#Delete \*w
doupdate(\|)#Update screen from all wnoutrefresh
echo(\|)#Set echo mode
endwin(\|)#End window modes
erase(\|)#Erase \*s
erasechar(\|)#Return user's erase character
fixterm(\|)#Restore tty to in ``curses'' state
flash(\|)#Flash screen or beep
flushinp(\|)#Throw away any typeahead
getch(\|)#Get a character from tty
getstr(str)#Get a string through \*s