NAME
curses_screen,
filter,
ripoffline,
use_env,
newterm,
set_term,
delscreen,
endwin,
initscr,
isendwin,
is_term_resized,
resize_term,
resizeterm,
setterm,
set_tabsize —
curses terminal and
screen routines
LIBRARY
Curses Library (libcurses, -lcurses)
SYNOPSIS
#include <curses.h>
void
filter(
void);
int
ripoffline(
int
line,
int (*init)(WINDOW
*win, int cols));
void
use_env(
bool
value);
SCREEN *
newterm(
char
*type,
FILE *outfd,
FILE *infd);
SCREEN *
set_term(
SCREEN
*screen);
void
delscreen(
SCREEN
*screen);
int
endwin(
void);
WINDOW *
initscr(
void);
bool
isendwin(
void);
bool
is_term_resized(
int
lines,
int cols);
int
resize_term(
int
lines,
int cols);
int
resizeterm(
int
lines,
int cols);
int
setterm(
char
*name);
int
set_tabsize(
int
value);
extern int LINES;
extern int COLS;
DESCRIPTION
These functions initialize terminals and screens.
The
newterm() function initialises the curses data structures
and pointers ready for use by curses. The
type argument
points to a
terminfo(5) entry,
or it may be
NULL
in which case the TERM environment
variable is used. The
outfd and
infd are the output and input file descriptors for the
terminal. The
newterm() function must only be called once
per terminal.
The
set_term() function can be used to switch between the
screens defined by calling
newterm(), a pointer to the
previous screen structure that was in use will be returned on success.
Calling
delscreen() will destroy the given screen and free all
allocated resources.
Calling
endwin() will end the curses session and restore the
saved terminal settings.
The curses session must be initialised by calling
initscr()
which saves the current terminal state and sets up the terminal and internal
data structures to support the curses application. This function call must be,
with few exceptions, the first Curses library call made. The exception to this
rule is the
newterm() call which may be called prior to
initscr(). The size of the curses screen is determined by
checking the
tty(4) size and then
the
terminfo(5) entries for
the terminal type. If the environment variables
LINES
or
COLUMNS
are set, then these will be used instead.
When either
newterm() or
initscr() are
called, the Curses library sets up signal handlers for
SIGTSTP
and
SIGWINCH
. If a
signal handler is already installed for
SIGWINCH
, this
will also be called when the Curses library handler is called.
The
isendwin() function can be used to determine whether or
not a refresh of the screen has occurred since the last call to
endwin().
The size of the screen may be changed by calling
resize_term()
with the updated number of lines and columns. This will resize the curses
internal data structures to accommodate the changed terminal geometry. The
curscr
and
stdscr
windows and
any of their subwindows will be resized to fit the new screen size. The
application must redraw the screen after a call to
resize_term(). The
resizeterm() function
is a wrapper for
resize_term() and adjusts other structure
data that handles window dimensions. The
is_term_resized()
function tests if either of the above functions need to be called.
The
setterm() function sets the terminal type for the current
screen to the one passed, initialising all the curses internal data structures
with information related to the named terminal. The
name
argument must be a valid name or alias in the
terminfo(5) database for this
function to succeed.
The
filter() function changes the way the terminal is
initialised. A subsequent call to
initscr() or
newterm() performs the following additonal actions:
- Disable use of clear, cud,
cud1, cup, cuu, cuu1 and vpa.
- Set the value of the home
string to the value of the cr string.
- Set lines equal to 1.
The
ripoffline() function will rip a line from
stdscr
at the top if
line is
positive, or at the bottom if negative. When
initscr() or
newterm() is called, a window will be created for each line
ripped and passed to the
init function pointer alongwith
the number of columns in the window. This init function cannot use the
LINES
or
COLS
variables and
cannot call
wrefresh(3) or
doupdate(3), but may call
wnoutrefresh(3).
ripoffline() can be called up to five times.
The
use_env() function determines whether the environment
variables
LINES
and
COLUMNS
override the normal values. The default is true. Any call to
use_env() must precede calls to
initscr(),
newterm(), or
setupterm().
The
set_tabsize() function will set
TABSIZE of the current screen to
tabsize.
RETURN VALUES
Functions returning pointers will return
NULL
if an
error is detected. The functions that return an int will return one of the
following values:
OK
- The function completed successfully.
ERR
- An error occurred in the function.
SEE ALSO
curses_window(3),
tty(4),
terminfo(5),
signal(7)
STANDARDS
The
NetBSD Curses library complies with the X/Open
Curses specification, part of the Single Unix Specification.
HISTORY
The Curses package appeared in
4.0BSD. The
resizeterm() function is a
ncurses
extension to the Curses library and was added in
NetBSD
1.6. The
is_term_resized(),
resize_term() and
set_tabsize() functions
are
ncurses extension to the Curses library and was added in
NetBSD 8.0.
BUGS
There is currently an issue with cursor movement in a 1 line sized window which
causes the screen to scroll up. This can obviously be seen when using
ripoffline().