Next: Errors and Exceptions, Previous: Features determined at compile time, Up: The basic curses library [Contents][Index]
initscr is normally the first curses routine to call when
initializing a program. A few special routines sometimes need to be
called before it; these are slk-init, %filter,
use-env. For multiple-terminal
applications, newterm may be called before initscr.
The initscr code determines the terminal type and initializes
all curses data structures. initscr also causes the first call
to refresh to clear the screen.
The #<window> returned by initscr should be held in a
variable that exists for the lifetime of a curses program. If it is
garbage collected, the window will become unusable.
If errors occur, initscr throws and error and exits; otherwise,
a #<window> referencing stdscr is returned.
These procedures, if called after initscr has been called,
will return the size of the screen at the time initscr was called.
The procedure newterm initializes curses for a given terminal
type type on specific curses port inport and
outport. The newterm function relies on some relatively
obscure GNU C library functions and thus may not be available on
non-GNU systems.
The routine newterm should be called once for each terminal.
It returns a variable of type #<screen> which should be saved
as a reference to that terminal. type is the type of the
terminal to be used in place of $TERM. outport is a port
that will receive the output to the terminal.
IMPORTANT: These ports must be file ports. The underlying ncurses
library extracts the file descriptor from the port and uses that to
write to the screen. Also, these ports will be closed by
newterm and cannot be reused.
newterm will internally use a duplicate port to the file
pointed to by inport. inport won’t be used except to get a
file descriptor for the underlying file.
Immediately following the call to newterm, one should create a window
for the terminal by using the stdscr procedure. So the standard way
to initialize it would be something like.
(newterm "vt220" outport inport) (define stdscr (stdscr))
This routine will throw an error if the terminal could not be created.
A program that outputs to more than one terminal should use the
newterm routine for each terminal instead of initscr. A
program that needs to inspect capabilities, so it can continue to run
in a line-oriented mode if the terminal cannot support a
screen-oriented program, would also use newterm. The program
must also call endwin for each terminal being used before
exiting from curses. If newterm is called more than once for
the same terminal, the first terminal referred to must be the last one
for which endwin is called.
A program should always call endwin before exiting or escaping
from curses mode temporarily. This routine restores TTY modes, moves
the cursor to the lower left-hand corner of the screen and resets the
terminal into the proper non-visual mode. Calling refresh or
doupdate after a temporary escape causes the program to resume
visual mode.
Its return value is #t if the terminal can be restored to its
behavior (as in reset-shell-mode), or #f otherwise. If
the terminal was created by newterm, then this will usually
return #f since input file had no previous mode.
The isendwin? routine returns #t if endwin has
been called without any subsequent calls to refresh, and
#f otherwise.
The set-term routine is used to switch between different
terminals. If the program has created multiple terminal using the
newterm procedure, then set-term can be called to set
one of those terminal to be the current terminal on which all the
curses procedures will operate. The screen reference new
becomes the new current terminal. This is the only routine which
manipulates #<screen> types; all other routines affect only the
current terminal.
The return value is unspecified.
The delscreen routine frees storage associated with the screen
data structure. The endwin routine does not do this, so
delscreen should be called after endwin if a particular
screen is no longer needed. Trying to use a screen after it has
been freed will likely result in “bad state” errors.
The return value is unspecified.
Next: Errors and Exceptions, Previous: Features determined at compile time, Up: The basic curses library [Contents][Index]