fns.doc

早期freebsd实现

.\" Copyright (c) 1992, 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.
.\"
.\"     @(#)fns.doc	8.1 (Berkeley) 6/4/93
.\"
.Ds
.Fn addch "char ch" \(dg
.De
Add the character
.Vn ch
on the window
at the current \*y.
If the character is a newline
(\'\en\')
the line will be cleared to the end,
and the current \*y will be changed to the
beginning off the next line
if newline mapping is on,
or to the next line at the same x co-ordinate
if it is off.
A return
(\'\er\')
will move to the beginning of the line on the window.
Tabs
(\'\et\')
will be expanded into spaces
in the normal tabstop positions of
every eight characters.
\*(Es
.Ds
.Fn addstr "char *str" \(dg
.De
Add the string pointed to by
.Vn str
on the window at the current \*y.
\*(Es
In this case, it will put on as much as it can.
.Ds
.Fn baudrate "" \(dg
.De
Returns the output baud rate of the terminal.
This is a system dependent constant
(defined in
.b <sys/tty.h>
on BSD systems,
which is included by
.b <curses.h> ).
.Ds
.Fn box "WINDOW win" "char vert" "char hor"
.De
.Pp
Draws a box around the window using
.Vn vert
as the character for drawing the vertical sides, and
.Vn hor
for drawing the horizontal lines.
If scrolling is not allowed,
and the window encompasses the lower right-hand corner of the terminal,
the corners are left blank to avoid a scroll.
.Ds
.Fn cbreak "" \(dg
.De
Set or the terminal to cbreak mode.
.Ds
.Fn clear "" \(dg
.De
Resets the entire window to blanks.
If
.Vn win
is a screen,
this sets the clear flag,
which will cause a clear-screen sequence to be sent
on the next
.Fn refresh
call.
This also moves the current \*y
to (0\*,0).
.Ds
.Fn clearok "WINDOW *scr" "int boolf" \(dg
.De
Sets the clear flag for the screen
.Vn scr .
If
.Vn boolf
is non-zero,
this will force a clear-screen to be printed on the next
.Fn refresh ,
or stop it from doing so if
.Vn boolf
is 0.
This only works on screens,
and,
unlike
.Fn clear ,
does not alter the contents of the screen.
If
.Vn scr
is
.Vn curscr ,
the next
.Fn refresh
call will cause a clear-screen,
even if the window passed to
.Fn refresh
is not a screen.
.Ds
.Fn clrtobot "" \(dg
.De
Wipes the window clear from the current \*y to the bottom.
This does not force a clear-screen sequence on the next refresh
under any circumstances.
\*(Nm
.Ds
.Fn clrtoeol "" \(dg
.De
Wipes the window clear from the current \*y to the end of the line.
\*(Nm
.Ds
.Fn crmode "" \(dg
.De
Identical to 
.Fn cbreak .
The misnamed macro
.Fn crmode
and
.Fn nocrmode
is retained for backwards compatibility
with ealier versions of the library.
.Ds
.Fn delch ""
.De
Delete the character at the current \*y.
Each character after it on the line shifts to the left,
and the last character becomes blank.
.Ds
.Fn deleteln ""
.De
Delete the current line.
Every line below the current one will move up,
and the bottom line will become blank.
The current \*y will remain unchanged.
.Ds
.Fn delwin "WINDOW *win"
.De
Deletes the window from existence.
All resources are freed for future use by
.b calloc (3).
If a window has a
.Fn subwin
allocated window inside of it,
deleting the outer window
the subwindow is not affected,
even though this does invalidate it.
Therefore,
subwindows should be deleted before their
outer windows are.
.Ds
.Fn echo "" \(dg
.De
Sets the terminal to echo characters.
.Ds
.Fn endwin ""
.De
Finish up window routines before exit.
This restores the terminal to the state it was before
.Fn initscr
(or
.Fn gettmode
and
.Fn setterm )
was called.
It should always be called before exiting and before the final calls to 
.Fn delwin .
It does not exit.
This is especially useful for resetting tty stats
when trapping rubouts via
.b signal (2).
.Ds
.Fn erase "" \(dg
.De
Erases the window to blanks without setting the clear flag.
This is analagous to
.Fn clear ,
except that it never causes a clear-screen sequence to be generated
on a
.Fn refresh .
\*(Nm
.Ds
.Fn erasechar "" \(dg
.De
Returns the erase character
for the terminal,
.i i.e. ,
the character used by the user to erase a single character from the input.
.Ds
.Fn flushok "WINDOW *win" "int boolf"
.De
Normally,
.Fn refresh
.Fn fflush 's
.Vn stdout
when it is finished.
.Fn flushok
allows you to control this.
if
.Vn boolf
is non-zero
(\c
.i i.e. ,
non-zero)
it will do the
.Fn fflush ,
otherwise it will not.
.Ds
.Fn getch "" \(dg
.De
Gets a character from the terminal and (if necessary)
echos it on the window.
\*(Es
Otherwise, the character gotten is returned.
If
.i noecho
has been set, then the window is left unaltered.
In order to retain control of the terminal,
it is necessary to have one of
.i noecho ,
.i cbreak ,
or
.i rawmode
set.
If you do not set one,
whatever routine you call to read characters will set
.i cbreak
for you,
and then reset to the original mode when finished.
.Ds
.Fn getstr "char *str" \(dg
.De
Get a string through the window
and put it in the location pointed to by
.Vn str ,
which is assumed to be large enough to handle it.
It sets tty modes if necessary,
and then calls
.Fn getch
(or
.Fn wgetch )
to get the characters needed to fill in the string
until a newline or EOF is encountered.
The newline stripped off the string.
\*(Es
.Ds
.Fn gettmode ""
.De
Get the tty stats.
This is normally called by
.Fn initscr .
.Ds
.Fn getyx "WINDOW *win" "int y" "int x"
.De
Puts the current \*y of
.Vn win
in the variables
.Vn y
and
.Vn x .
Since it is a macro,
not a function,
you do not pass the address
of
.Vn y
and
.Vn x .
.Ds
.Fn idlok "WINDOW *win" "int boolf"
.De
Reserved for future use.
This will eventually signal to
.Fn refresh
that it is all right to use the insert and delete line sequences
when updating the window.
.Ds
.Fn inch "" \(dg
.De
Returns the character at the current position on the given window.
This does not make any changes to the window.
.Ds
.Fn initscr ""
.De
Initialize the screen routines.
This must be called before any of the screen routines are used.
It initializes the terminal-type data and such,
and without it none of the routines can operate.
If standard input is not a tty,
it sets the specifications to the terminal
whose name is pointed to by
.Vn Def\*_term
(initially "dumb").
If the boolean
.Vn My\*_term
is non-zero,
.Vn Def\*_term
is always used.
If the system supports the
.b TIOCGWINSZ
.i ioctl(2)
call,
it is used to get the number of lines and columns for the terminal,
otherwise it is taken from the
.b termcap
description.
.Ds
.Fn insch "char c"
.De
Insert
.Vn c
at the current \*y
Each character after it shifts to the right,
and the last character disappears.
\*(Es
.Ds
.Fn insertln ""
.De
Insert a line above the current one.
Every line below the current line
will be shifted down,
and the bottom line will disappear.
The current line will become blank,
and the current \*y will remain unchanged.
.Ds
.Fn killchar "" \(dg
.De
Returns the line kill character
for the terminal,
.i i.e. ,
the character used by the user to erase an entire line from the input.
.Ds
.Fn leaveok "WINDOW *win" "int boolf" \(dg
.De
Sets the boolean flag for leaving the cursor after the last change.
If
.Vn boolf
is non-zero,
the cursor will be left after the last update on the terminal,
and the current \*y for
.Vn win
will be changed accordingly.
If 
.Vn boolf
 is 0 the cursor will be moved to the current \*y.
This flag
(initially 0)
retains its value until changed by the user.
.Ds
.Fn move "int y" "int x"
.De
Change the current \*y of the window to
.Vn y\*,x ). (
\*(Es
.Ds
.Fn mvcur "int lasty" "int lastx" "int newy" "int newx"
.De
Moves the terminal's cursor from
.Vn lasty\*,lastx ) (
to
.Vn newy\*,newx ) (
in an approximation of optimal fashion.
This routine uses the functions borrowed from
.i ex
version 2.6.