The capabilities of your program are limited, in part, by the capabilities of the terminal on which it runs. This section provides information about initializing terminals and identifying their capabilities. For further information on terminals, see the following articles:
With curses, you can use one or more terminals for input and output. The terminal subroutines enable you to establish new terminals, to switch input and output processing, and to retrieve terminal capabilities.
You can start curses on a single default screen using the initscr subroutine. This should be sufficient for most applications. However, if your application sends output to more than one terminal, you should use the newterm subroutine. Call this subroutine for each terminal. If your application wants an indication of error conditions so that it can continue to run in a line-oriented mode if the terminal cannot support a screen-oriented program, you should also use the newterm subroutine.
When it completes, a program must call the endwin subroutine for each terminal it used. If you call the newterm subroutine more than once for the same terminal, the first terminal referred to must be the last one for which you call the endwin subroutine.
The set_term subroutine switches input and output processing between different terminals.
Curses supplies the following subroutines to help you determine the capabilities of a terminal:
The longname subroutine returns a pointer to a static area containing a verbose description of the current terminal. This area is defined only after a call to the initscr or newterm subroutine. If you intend to use the longname subroutine with multiple terminals, you should know that each call to the newterm subroutine overwrites this area. Calls to the set_term subroutine do not restore the value. Instead, save this area between calls to the newterm subroutine.
The has_ic subroutine returns TRUE if the terminal has insert and delete character capabilities.
The has_il subroutine returns TRUE if the terminal has insert and delete line capabilities or can simulate the capabilities using scrolling regions. Use the has_il subroutine to check whether it is appropriate to turn on physical scrolling using the scrollok or idlok subroutines.
Special input characters include the flow-control characters, the interrupt character, the erase character, and the kill character. Four mutually-exclusive Curses modes let the application control the effect of the input characters.
This achieves normal line-at-a-time processing with all special characters handled outside the application. This achieves the same effect as canonical-mode input processing. The state of the ISIG and IXON flags are not changed upon entering this mode by calling nocbreak( ), and are set upon entering this mode by calling noraw( ).
The implementation supports erase and kill characters from any supported locale, no matter what the width of the character is.
Characters typed by the user are immediately available to the application and Curses does not perform special processing on either the erase character or the kill character. An application can select cbreak mode to do its own line editing but to let the abort character be used to abort the task. This mode achieves the same effect as non-canonical-mode, Case B input processing (with MIN set to 1 and ICRNL cleared). The state of the ISIG and IXON flags are not changed upon entering this mode.
The effect is the same as cbreak, except that input functions wait until a character is available or an interval defined by the application elapses, whichever comes first. This mode achieves the same effect as non-canonical-mode, Case C input processing (with TIME set to the value specified by the application). The state of the ISIG and IXON flags are not changed upon entering this mode.
Raw mode gives the application maximum control over terminal input. The application sees each character as it is typed. This achieves the same effect as non-canonical mode, Case D input processing. The ISIG and IXON flags are cleared upon entering this mode.
The terminal interface settings are recorded when the process calls initscr( ) or newterm( ) to initialize Curses and restores these settings when endwin( ) is called. The initial input mode for Curses operations is unspecified unless the implementation supports Enhanced Curses compliance, in which the initial input mode is cbreak mode.
The behavior of the BREAK key depends on other bits in the display driver that are not set by Curses.
Two mutually-exclusive delay modes specify how quickly certain Curses functions return to the application when there is no terminal input waiting when the function is called:
The effect of No Delay Mode on function key processing is unspecified.
Echo mode determines whether Curses echoes typed characters to the screen. The effect of Echo mode is analogous to the effect of the ECHO flag in the local mode field of the termios structure associated with the terminal device connected to the window. However, Curses always clears the ECHO flag when invoked, to inhibit the operating system from performing echoing. The method of echoing characters is not identical to the operating system's method of echoing characters, because Curses performs additional processing of terminal input.
If in Echo mode, Curses performs its own echoing. Any visible input character is stored in the current or specified window by the input function that the application called, at that window's cursor position, as though addch( ) were called, with all consequent effects such as cursor movement and wrapping.
If not in Echo mode, any echoing of input must be performed by the application. Applications often perform their own echoing in a controlled area of the screen, or do not echo at all, so they disable Echo mode.
It may not be possible to turn off echo processing for synchronous and network asynchronous terminals because echo processing is done directly by the terminals. Applications running on such terminals should be aware that any characters typed will appear on the screen at wherever the cursor is positioned.
The subroutines that control input and output determine how your application retrieves and displays data to users.
The raw subroutine puts the terminal into RAW mode. In RAW mode, characters typed by the user are immediately available to the program. Additionally, the interrupt, quit, suspend, and flow-control characters are passed uninterpreted instead of generating a signal as they do in CBREAK mode. The noraw subroutine takes the terminal out of RAW mode.
The cbreak subroutine performs a subset of the functions performed by the raw subroutine. The cbreak subroutine puts the terminal into CBREAK mode. In CBREAK mode, characters typed by the user are immediately available to the program and erase or kill character processing is not done. Unlike RQW mode, interrupt and flow characters are acted upon. Otherwise, the tty driver buffers the characters typed until a new line or carriage return is typed.
Note: CBREAK mode disables translation by the tty driver.
The nocbreak subroutine takes the terminal out of CBREAK mode.
The echo subroutine puts the terminal into ECHO mode. In ECHO mode, curses writes characters typed by the user to the terminal at the physical cursor position. The noecho subroutine takes the terminal out of ECHO mode.
The delay_output subroutine sets the output delay to the specified number of milliseconds. You should not use this subroutine extensively because it uses padding characters instead of a processor pause.
The nl and nonl subroutines, respectively, control whether curses translates new lines into carriage returns and line feeds on output, and whether curses translates carriage returns into new lines on input. Initially, these translations do occur. By disabling these translations, the curses subroutine library has more control over the line-feed capability, resulting in faster cursor motion.
When curses is initialized, it checks the TERM environment variable to identify the terminal type. Then, curses looks for a definition explaining the capabilities of the terminal. Usually this information is kept in a local directory specified by the TERMINFO environment variable or in the /usr/share/lib/terminfo directory. All curses programs first check to see if the TERMINFO environment variable is defined. If this variable is not defined, the /usr/share/lib/terminfo directory is checked.
For example, if the TERM variable is set to vt100 and the TERMINFO variable is set to the /usr/mark/myterms file, curses checks for the /usr/mark/myterms/v/vt100 file. If this file does not exist, curses checks the /usr/share/lib/terminfo/v/vt100 file. For an explanation of the terminfo database, see the terminfo file format.
Additionally, the LINES and COLUMNS environment variables can be set to override the terminal description.
Use the terminfo subroutines when your program needs to deal directly with the terminfo database. For example, use these subroutines to program function keys. In all other cases, curses subroutines are more suitable and their use is recommended.
Your program should begin by calling the setupterm subroutine. Normally, this subroutine is called indirectly by a call to the initscr or newterm subroutine. The setupterm subroutine reads the terminal-dependent variables defined in the terminfo database. The terminfo database includes boolean, numeric, and string variables. After reading the database, the setupterm subroutine initializes the cur_term variable with the terminal definition. When working with multiple terminals, you can use the set_curterm subroutine to set the cur_term variable to a specific terminal. All of terminfo boolean, numeric, and string variables use the values defined for the specified terminal.
Another subroutine, restartterm, is similar to the setupterm subroutine. However, it is called after memory is restored to a previous state. For example, you would call the restartterm subroutine after a call to the scr_restore subroutine. The restartterm subroutine assumes that the input and output options are the same as when memory was saved, but that the terminal type and baud rate may differ.
The del_curterm subroutine frees the space containing the capability information for a specified terminal.
Include the curses.h and term.h files in your program in the following order:
#include <curses.h> #include <term.h>
These files contain the definitions for the strings, numbers, and flags in the terminfo database.
Pass all parametized strings through the tparm subroutine to instantiate them. You should print all terminfo strings and the output of the tparm subroutine with the tputs or putp subroutine.
Use the following subroutines to obtain and pass terminal capabilities:
When your program exits you should restore the tty modes to their original state. To do this, call the reset_shell_mode subroutine. If your program uses cursor addressing, it should output the enter_ca_mode string at startup and the exit_ca_mode string when it exits.
Programs that use shell escapes should call the reset_shell_mode subroutine and output the exit_ca_mode string before calling the shell. After returning from the shell, the program should output the enter_ca_mode string and call the reset_prog_mode subroutine. This process differs from standard curses operations which call the endwin subroutine on exit.
Use the following subroutines for low-level screen manipulations:
If your program uses the termcap file for terminal information, the termcap subroutines are included as a conversion aid. The parameters are the same for the termcap subroutines. Curses emulates the subroutines using the terminfo database. The following termcap subroutines are supplied:
| tgetent | Emulates the setupterm subroutine. |
| tgetflag | Returns the boolean entry for a termcap identifier. |
| tgetnum | Returns the numeric entry for a termcap identifier. |
| tgetstr | Returns the string entry for a termcap identifier. |
| tgoto | Duplicates the tparm subroutine. The output from the tgoto subroutine should be passed to the tputs subroutine. |
The captoinfo command converts termcap descriptions to terminfo descriptions. The following example illustrates how the captoinfo command works:
captoinfo /usr/lib/libtermcap/termcap.src
This command converts the /usr/lib/libtermcap/termcap.src file to terminfo source. The captoinfo command writes the output to standard output and preserves comments and other information in the file. For more information, see the captoinfo command.
Note: To maintain compatibility with the AIX 3.2 version of curses, you can install a version of the captoinfo command that converts termcap data to the AIX 3.2-style terminfo data. See "AIX Version 3.2 Curses Compatibility" for details.
The following functions save and restore the state of terminal modes:
| savetty | Saves the state of the tty modes. |
| resetty | Restores the state of the tty modes to what they were the last time the savetty subroutine was called. |
Curses Overview for Programming
This section indicates to the application writer some considerations to be borne in mind when driving synchronous, networked synchronous (NWA) or non-standard directly-connected asynchronous terminals.
Such terminals are often used in a mainframe environment and communicate to the host in block mode. That is, the user types characters at the terminal then presses a special key to initiate transmission of the characters to the host.
Frequently, although it may be possible to send arbitrary sized blocks to the host, it is not possible or desirable to cause a character to be transmitted with only a single keystroke.
This can cause severe problems to an application wishing to make use of single-character input.
The Curses interface can be used in the normal way for all operations pertaining to output to the terminal, with the possible exception that on some terminals the refresh( ) routine may have to redraw the entire screen contents in order to perform any update.
If it is additionally necessary to clear the screen before each such operation, the result could be undesirable.
Because of the nature of operation of synchronous (block-mode) and NWA terminals, it might not be possible to support all or any of the Curses input functions. In particular, the following points should be noted: