OSF

NAME

curses Library − Controls cursor movement and windowing

LIBRARY

Curses Library (libcurses.a)

SYNOPSIS

#include <curses.h>
#include <term.h>

DESCRIPTION

The curses library is a screen manipulation package. 

The full curses interface allows you to manipulate structures called windows, which can be thought of as two-dimensional arrays of characters representing all or part of the screen.  A default window (called stdscr) is supplied, and you can create others using the newwin() function.  Windows are referred to by variables declared as type WINDOW ∗, defined in the curses.h header file.  (The term.h header file should be used only for using the terminfo level functions.) 

Routine names beginning with "w" allow you to specify a window.  Routine names not beginning with a "w" affect only stdscr. 

The minicurses package is a subset of curses that does not allow you to manipulate more than one window.  This subset is invoked with the -DMINICURSES option to cc.  This subset is smaller and faster than the full curses interface. 

If your program needs only one terminal, you can specify the -DSINGLE flag to the C compiler. This results in static references instead of dynamic references to capabilities. The result is more concise code, but only one terminal can be used at a time for the program. 

To initialize the functions which are described in the curses library, you must call the initscr() function before using any other functions which affect windows and screens, and the endwin() function before exiting. 

Screen Dimensions

The screen is a matrix of character positions that can contain any character from the terminal’s character set.  The actual dimensions of the matrix are different for each type of terminal. These dimensions are defined when the initscr() function calls the terminfo initialization function, setupterm(). The functions enforce the following limits on the terminal:

       •If the terminal specification defines less than 5 lines, the functions use a value of 24 lines. 

       •If the terminal specification defines less than 5 columns, the functions use a value of 80 columns. 

Note that line values (y coordinates) are specified first to the library functions which request line and column values. 

To update the screen, the functions must know what the screen currently looks like and what it should be changed to. The functions define the WINDOW data type to hold this information. This data type is a structure that describes a window image to the functions, including the starting position on the screen (the (line, col) coordinates of the upper left corner) and size. 

You can think of a window as an array of characters on which to make changes. Using the window, a program builds and stores an image of a portion of the terminal that it later transfers to the actual screen. When the window is complete, use one of the following functions to transfer the window to the terminal:

refreshTransfers the contents of stdscr to the terminal. 

wrefreshTransfers the contents of a named window (not stdscr) to the terminal. 

This two-step process maintains several different copies of a window in memory and selects the proper one to display at any time.  In addition, the program can change the contents of the screen in any order. When it has made all of the changes, the library functions update the terminal in an efficient manner. 

The Curses Routines

The curses functions are summarized below:

int addch( chtype ch );
Add a character to stdscr, wrapping to the next line at the end of a line (like putchar()).  May be called with minicurses. 

int waddch( WINDOW ∗win, chtype ch );
Add character ch to window win. 

int mvwaddch( WINDOW ∗win, int y, int x, chtype ch );
Move to position (y, x), then add character ch to window win. 

int addstr( char ∗str );
Call addch() with each character in string str.  May be used with minicurses. 

int mvaddstr( int y, int x, char ∗str );
Move to position (y, x), then add string str. 

int waddstr( WINDOW ∗win, char ∗str );
Add string str to window win. 

int mvwaddstr( WINDOW ∗win, int y, int x, char ∗str );
Move to position (y, x), then add string str to window win. 

int attroff( chtype attrs );
Turn offattributes named in list attrs.  May be used with minicurses. 

int attron( chtype attrs );
Turn onattributes named in list attrs.  May be used with minicurses. 

int attrset( chtype attrs );
Set currentattributes to those specified in list attrs.  May be used with minicurses. 

int baudrate ( void );
Query current terminal speed. May be used with minicurses. 

int beep ( void );
Sound beep on terminal. May be used with minicurses. 

int box( WINDOW ∗win, chtype vert, chtype hor );
Draw a box around edges of window win. The vert and hor parameters are the characters to use for vertical and horizontal edges of the box. 

int cbreak ( void );
Set cbreak() mode.  May be used with minicurses. 

int nocbreak ( void );
Unset cbreak() mode.  May be used with minicurses. 

int clear ( void );
Clear stdscr. 

int clearok( WINDOW ∗win, bool bool_flag );
Clear screen before next redraw of window win if bool_flag is true. 

int clrtobot ( void );
Clear to bottom of stdscr. 

int clrtoeol ( void );
Clear to end of line on stdscr. 

int delay_output( int ms );
Insert pause of ms milliseconds in output.  May be used with minicurses. 

int nodelay( WINDOW ∗win, bool bool_flag );
Enable nodelay() input mode through getch() on window win if bool_flag is true. 

int delch ( void );
Delete a character.

int deleteln ( void );
Delete a line.

int delwin( WINDOW ∗win );
Delete window win. 

int doupdate ( void );
Update screen from all wnoutrefresh(). 

int echo ( void );
Set echo mode. May be used with minicurses. 

int noecho ( void );
Unset echo mode. May be used with minicurses. 

int endwin ( void );
End window mode. May be used with minicurses. 

int erase ( void );
Erase stdscr. 

char erasechar ( void );
Return user’s erase character.

int fixterm ( void );
"Restore terminal to "in curses" state.

int flash ( void );
Flash screen or beep.

int flushinp ( void );
Throw away any data in type-ahead. May be used with minicurses. 

int flushok ( WINDOW ∗win, bool bool_flag );
Set the flush-on-refresh flag for window win to be bool_flag. 

int getch ( void );
Get a character from stdscr.  May be used with minicurses.The following list contains the function keys that might be returned by the getch() function if keypad() has been enabled.  Due to lack of definitions in terminfo, or due to the terminal not transmitting a unique code when the key is pressed, not all of these keys are supported. 

KEY_BREAK
Break key (unreliable)

KEY_DOWN
Down arrow key

KEY_UPUp arrow key

KEY_LEFTLeft arrow key

KEY_RIGHT
Right arrow key

KEY_HOME
Home key

KEY_BACKSPACE
Backspace (unreliable)

KEY_F(n)Function key Fn, where n is an integer from 0 to 63

KEY_DLDelete line

KEY_ILInsert line

KEY_DCDelete character

KEY_ICInsert character or enter insert mode

KEY_EICExit insert character mode

KEY_CLEAR
Clear screen

KEY_EOSClear to end of screen

KEY_EOLClear to end of line

KEY_SFScroll one line forward

KEY_SRScroll one line backwards (reverse)

KEY_NPAGE
Next page

KEY_PPAGE
Previous page

KEY_STABSet tab

KEY_CTABClear tab

KEY_CATAB
Clear all tabs

KEY_ENTER
Enter or send (unreliable)

KEY_SRESET
Soft (partial) reset (unreliable)

KEY_RESET
Reset or hard reset (unreliable)

KEY_PRINT
Print or copy

KEY_LLHome down or bottom (lower left)

KEY_A1Upper left key of keypad

KEY_A3Upper right key of keypad

KEY_B2Center key of keypad

KEY_C1Lower left key of keypad

KEY_C3Lower right key of keypad

char ∗getcap ( char ∗cap_name );
Get terminal capability cap_name. 

int getstr( char ∗str );
Get the string through stdscr. 

int gettmode ( void );
Get current tty modes. 

int getyx( WINDOW ∗win, int y, int x );
Get (y, x) coordinates from window win. 

bool has_ic ( void );
Has value of TRUE if terminal can insert character.

bool has_il ( void );
Has value of TRUE if terminal can insert line.

int idlok( WINDOW ∗win, bool bool_flag );
Use terminal’s insert/delete line on window win if bool_flag is true.  May be used with minicurses. 

chtype inch ( void );
Get character at current (y, x) coordinates. 

WINDOW ∗initscr ( void );
Initialize screens. May be used with minicurses. 

int insch( chtype ch );
Insert character ch. 

int insertln ( void );
Insert a line.

int intrflush( WINDOW ∗win, bool bool_flag );
Interrupt flush output on window win if bool_flag is true. 

int keypad( WINDOW ∗win, bool bool_flag );
Enable keypad input on window win if bool_flag is true. 

char killchar ( void );
Return current user’s kill() character. 

int leaveok( WINDOW ∗win, bool bool_flag );
Permit cursor to be left anywhere after refresh for window win if bool_flag is true; otherwise cursor must be left at current position. 

char ∗longname ( void );
Return verbose name of terminal.

char ∗longname( char ∗termbuf, char ∗name );
Set name to the full name of the terminal described by termbuf.  Used in programs that are compiled with the -D_BSD option to provide BSD compatibility. 

char meta( WINDOW ∗win, bool bool_flag );
Allow metacharacters on input from window win if bool_flag is true.  May be used with minicurses. 

int move( int y, int x );
Move to position (y, x) on stdscr.  May be used with minicurses. 

int mvaddch( int y, int x, chtype ch );
Move to position (y, x), then add character ch. 

char mvcur( int y1, int x1, int y2, int x2 );
Move cursor from current position (y1,x1) to new position (y2,x2). 

int mvdelch( int y, int x );
Move to position (y, x), then delete a character. 

int mvgetch( int y, int x );
Move to position (y, x), then get a character from the terminal. 

int mvgetstr( int y, int x, char ∗str );
Move to position (y, x), then get the str string from the terminal. 

chtype mvinch( int y, int x );
Move to position (y, x) then get the character at current (y, x) coordinates. 

int mvinsch( int y, int x, chtype ch );
Move to position (y, x) then insert the character ch. 

int mvprintw( int y, int x, char ∗fmt [, args ] );
Move to position (y, x), then get print on stdscr. 

int mvscanw( int y, int x, char ∗fmt [, args ] );
Move to position (y, x), then scan through stdscr. 

int mvwdelch( WINDOW ∗win, int y, int x );
Move to position (y, x), then delete a character from win. 

int mvwgetch( WINDOW ∗win, int y, int x );
Move to position (y, x), then get a character through win. 

int mvwgetstr( WINDOW ∗win, int y, int x, char ∗str );
Move to position (y, x), then get a string through win. 

int mvwin( WINDOW ∗win, int y, int x );
Move win so that the upper left corner is located at position (y, x). 

chtype mvwinch( WINDOW ∗win, int y, int x );
Move to position (y, x) in win, then get the character at the new position. 

int mvwinsch( WINDOW ∗win, int y, int x, chtype ch );
Move to position (y, x), then insert the character ch into win. 

int mvwprintw( WINDOW ∗win, int y, int x, char ∗fmt [, args ] );
Move to position (y, x) then printf() on stdscr. 

int mvwscanw( WINDOW ∗win, int y, int x, char ∗fmt [, args ] );
Move (y, x) then scanf() through stdscr. 

WINDOW ∗newpad( int nlines, int ncols );
Create a new pad with given dimensions.

SCREEN ∗newterm( char ∗type, FILE outfd, FILE infd );
Set up new terminal of given type to output on outfd and input from infd. 

WINDOW ∗newwin( int lines, int cols, int begin_y, int begin_x );
Create a new window.

int nl ( void );
Set new line mapping. May be used with minicurses. 

int nonl ( void );
Unset new line mapping. May be used with minicurses. 

int overlay( WINDOW ∗win1, WINDOW ∗win2 );
Overlay win1 on win2. The overlaying window (win1) takes as its origin the window being overlayed (win2). 

int overwrite( WINDOW ∗win1, WINDOW ∗win2 );
Overwrite win1 on win2. 

int printw( char ∗fmt [, arg1, arg2, ... ] );
Print on stdscr. 

int raw ( void );
Set raw mode. May be used with minicurses. 

int refresh ( void );
Make current screen look like stdscr.  May be used with minicurses. 

int prefresh( WINDOW ∗pad, int pminrow, int pmincol, int sminrow, int smincol,
int smaxrow, int smaxcol ); Refresh from pad starting with given upper left corner of pad with output to given portion of screen. 

int pnoutrefresh(WINDOW ∗pad, int pminrow, int pmincol,
int sminrow, int smincol, int smaxrow, int smaxcol); Refresh like prefresh(), but with no output until doupdate() is called. 

int noraw ( void );
Unset raw mode. May be used with minicurses. 

int resetterm ( void );
Set tty" modes to "out of curses" state.  May be used with minicurses. 

int resetty ( void );
Reset tty flags to stored value.  May be used with minicurses. 

int saveterm ( void );
"Save current modes as "in curses" state. May be used with minicurses. 

int savetty ( void );
Store current tty flags.  May be used with minicurses. 

int scanw( char ∗fmt [, arg1, arg2, ... ] );
Scanf through stdscr. 

int scroll( WINDOW ∗win );
Scroll win one line. 

int scrollok( WINDOW ∗win, bool bool_flag );
Allow terminal to scroll if bool_flag is true. 

SCREEN ∗set_term( SCREEN ∗new );
Enable talk to terminal new. 

int setscrreg( int top, int bottom );
Set user scrolling region to lines top through bottom. 

void setterm( char ∗type );
Establish terminal with a given type.

int standend ( void );
Clear standout mode attribute. May be used with minicurses. 

int standout ( void );
Set standout mode attribute. May be used with minicurses. 

WINDOW ∗subwin( WINDOW ∗win, int lines, int cols, int begin_y, int begin_x );
Create a subwindow.

int touchline( WINDOW ∗win, int y, int firstcol, int numcol );
Mark numcol columns, starting at column firstcol, of line y as changed. 

int touchoverlap( WINDOW ∗win1, WINDOW ∗win2 );
Mark overlap of win1 on win2 as changed. 

int touchwin( WINDOW ∗win );
Change all of win. 

int traceoff ( void );
Turn off debugging trace output.

int traceon ( void );
Turn on debugging trace output.

int typeahead( FILE fd );
Check file descriptor fd to check type-ahead. 

char ∗unctrl( chtype ch );
Use printable version of ch.  May be used with minicurses. 

int wattroff( WINDOW ∗win, int attrs );
Turn off attrs in win. 

int wattron( WINDOW ∗win, int attrs );
Turn on attrs in win. 

int wattrset( WINDOW ∗win, int attrs );
Set attributes in win to attrs. 

int wclear( WINDOW ∗win );
Clear win. 

int wclrtobot( WINDOW ∗win );
Clear to bottom of win. 

int wclrtoeol( WINDOW ∗win );
Clear to end of line on win. 

int wdelch( WINDOW ∗win );
Delete the current character from win. 

int wdeleteln( WINDOW ∗win );
Delete line from win. 

int werase( WINDOW ∗win );
Erase win. 

int wgetch( WINDOW ∗win );
Get a character through win. 

int wgetstr( WINDOW ∗win, char ∗str );
Get the string str through win. 

chtype winch( WINDOW ∗win );
Get the character at current (y, x) in win. 

int winsch( WINDOW ∗win, chtype ch );
Insert the character ch into win. 

int winsertln( WINDOW ∗win );
Insert line into win. 

int wmove( WINDOW ∗win, int y, int x );
Set current (y, x) coordinates on win. 

int wnoutrefresh( WINDOW ∗win );
Refresh but no screen output.

int wprintw( WINDOW ∗win, char ∗fmt [, arg1, arg2, ... ] );
printf() on win. 

int wrefresh( WINDOW ∗win );
Make screen look like win. 

int wscanw( WINDOW ∗win, char ∗fmt [, arg1, arg2,...  ] );
 scanf() through win. 

int wsetscrreg( WINDOW ∗win, int top, int bottom );
Set scrolling region of win. 

int wstandend( WINDOW ∗win );
Clear standout attribute in win. 

int wstandout( WINDOW ∗win );
Set standout attribute in win. 

Terminfo Level Functions

These functions should be called by programs that have to deal directly with the terminfo database. Due to the low level of this interface, its use is discouraged. 

To use the terminfo level functions of curses, include the curses.h and term.h files, in that order, to get the definitions for these strings, numbers, and flags. Programs should call the setupterm() function before using any of the other terminfo functions. The setupterm() function defines the set of terminal-dependent variables defined in the terminfo file. 

All terminfo strings (including the output of the tparm() parameter) should be printed using the tputs() or putp() function.  Before exiting, your program should call the reset_shell_mode() function to restore the tty modes. Programs desiring shell escapes can call the reset_shell_mode() function before the shell is called, and the reset_prog_mode() function after returning from the shell. 

int delay_output ( int ms );
Sets the output delay, in milliseconds.

int def_prog_mode( void );
Saves the current terminal mode as program mode, in cur_term->Nttyb. 

int def_shell_mode( void );
Saves the shell mode as normal mode, in cur_term->Ottyb. The def_shell_mode() function is called automatically by setupterm() function. 

int putp( char ∗str );
Calls tputs()( char ∗str, 1, putchar()). 

int reset_prog_mode ( void );
Puts the terminal into program mode.

int reset_shell_mode ( void );
Puts the terminal into shell mode. All programs must call the reset_shell_mode() function before they exit. The higher-level function endwin() automatically does this. 

int setupterm( char ∗term, int fd, int rc );
Reads in the database. The term parameter is a character string that specifies the terminal name. If term is 0 (zero), then the value of the TERM environment variable is used. One of the following status values is stored into the integer pointed to by the rc parameter:

1Successful completion. 

0No such terminal. 

-1An error occurred while locating the terminfo database.  If the rc parameter is 0 (zero), then no status value is returned, and an error causes the setupterm() function to print an error message and exit, rather than return. The fd parameter is the file descriptor of the terminal being used for output.  The setupterm() function calls the TIOCGWINSZ ioctl function to determine the number of lines and columns on the display. If termdef cannot supply this information, then the setupterm() function uses the values in the terminfo database. The simplest call is setupterm(0,1,0), which uses all the defaults.  After the call to the setupterm() function, the global variable cur_term is set to point to the current structure of terminal capabilities.  It is possible for a program to use more than one terminal at a time by calling the setupterm() function for each terminal and saving and restoring cur_term.  The setupterm() function also initializes the global variable ttytype as an array of characters to the value of the list of names for the terminal. The list comes from the beginning of the terminfo description. 

char ∗tparm( char ∗format [ , arg, ... ]);
Instantiates the format string format, and one or more arguments of varying type.  The character string returned has the given parameters applied. 

void tputs( char ∗str, int affcnt, int (∗putc)();
Applies padding information to string str. The affcnt parameter is the number of lines affected, or 1 if not applicable. The putc parameter function is similar to putchar() to which the characters are passed one at a time.  Some strings are of a form similar to $<20>, which is an instruction to pad for 20 milliseconds.

void vidputs( int ∗attrs, int (∗putc)();
Outputs the string to put terminal in video attribute mode attrs. Characters are passed to the putc function. The attrs are defined in curses.h. The previous mode is retained by this function. 

void vidattr( int attrs );
Like vidputs(), but outputs through putchar(). 

Termcap Compatibility Functions

These functions are included for compatibility with programs that require termcap. Their parameters are the same as for termcap, and they are emulated using the terminfo database. 

int tgetent( char ∗bp, char ∗name );
Looks up the termcap entry for name. Both bp and name are strings. The name parameter is a terminal name; bp is ignored. Calls the setupterm() function. 

int tgetflag( char ∗id );
Returns the Boolean entry for id, which is a 2-character string that contains a termcap identifier. 

int tgetnum( char ∗id );
Returns the numeric entry for id, which is a 2-character string that contains a termcap identifier. 

char ∗tgetstr( char ∗id, char ∗area );
Returns the string entry for id, which is a 2-character string that contains a termcap identifier. The area parameter is ignored. 

char ∗tgoto( char ∗cap, int col, int row );
Applies parameters to the given cap. Calls the tparm() function. 

void tputs( char ∗cap, int affcnt, int (∗fn)();
Applies padding to cap calling fn as putchar(). 

RELATED INFORMATION

Files: terminfo(4)