Next: , Previous: , Up: The basic curses library   [Contents][Index]

5.2.3 Curses screen initialization and manipulation routines

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.

Procedure: 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.

Procedure: cols
Procedure: lines

These procedures, if called after initscr has been called, will return the size of the screen at the time initscr was called.

Procedure: newterm type outport inport

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.

Procedure: endwin

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.

Procedure: isendwin?

The isendwin? routine returns #t if endwin has been called without any subsequent calls to refresh, and #f otherwise.

Procedure: set-term new

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.

Procedure: delscreen screen

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: , Previous: , Up: The basic curses library   [Contents][Index]