CURSES(3x,L) AIX Technical Reference CURSES(3x,L) ------------------------------------------------------------------------------- curses PURPOSE Controls cursor movement and windowing. LIBRARY Curses Library (libcurses.a) SYNTAX #include #include DESCRIPTION Note: The curses package of subroutines is included here only for compatibility with existing programs. For information about the enhanced screen-handling subroutine library, see "extended curses library." The system calls curses and extended curses cannot both be used by the same program. The curses subroutine package updates the screen with reasonable optimization. The term.h header file is only needed if terminfo level routines are needed (see "Terminfo Level Subroutines"). In order to initialize the routines, the routine initscr must be called before any of the other routines that deal with windows and screens are used. The routine endwin should be called before exiting. To get character-at-a-time input without echoing, call the nonl, cbreak, and noecho routines. Most interactive, screen-oriented programs require the character-at-a-time input without echoing. Note: Unpredictable results occur when non-curses forms of terminal I/O are used (such as system() calls or stdio functions) with curses controlled terminal I/O, unless special steps are taken to resynchronize the physical terminal with curses data structures. For example, after issuing non-curses I/O commands, call clearok (stdscr, TRUE) and refresh() to completely refresh the terminal. You may lose your non-curses output, however. To ensure that the cursor is in a particular position after non-curses I/O, call move (0,0), refresh() and then execute a move to the desired location. The full curses interface permits manipulation of data structures called windows, which can be thought of as two-dimensional arrays of characters representing all or part of a screen. Default windows called stdscr and curscr are supplied, and others can be created with the newwin routine. Windows are referred to by variables declared WINDOW *. The type WINDOW is defined in Processed August 6, 1991 CURSES(3x,L) 1 CURSES(3x,L) AIX Technical Reference CURSES(3x,L) curses.h to be a C structure. These data structures are manipulated with the routines described below, among which the most basic are move and addch, which modify stdscr. After manipulating the data structures, the refresh subroutine is called, which updates the screen to look like stdscr. Routines beginning with the new definition of w allow window specification. Routines not beginning with a w affect stdscr. For further information about video mode support, see "Configuring the Virtual Terminal." Minicurses is a subset of curses that does not allow manipulation of more than one window. To invoke this subset, use -DMINICURSES as a cc option. This level is smaller and faster than the full curses. If the environment variable TERMINFO is defined, any program using curses checks for a local terminal definition before checking in /usr/lib/terminfo. For example, if TERM is set to vt100, the compiled file is normally found in /usr/lib/terminfo/v/vt100. (The directory name v is copied from the first letter of vt100 to avoid creating huge directories.) If, for example, TERMINFO is set to /usr/mark/myterms, curses first checks /usr/mark/myterms/v/vt100. If this file does not exist, curses then checks /usr/lib/terminfo/v/vt100. This is useful for developing experimental definitions or when write permission in /usr/lib/terminfo is not available. The following parameter names are of the type. int win, p1, p2, p3; char *str; int p1, p2, p3; Note: The plotting library, plot and the curses library, curses both use the names erase and move. The curses versions are macros. If you need both libraries, put the plot code in a different source file than the curses code, or include the following statements in the plot code: #undef move() #undef erase() ROUTINES The routines listed here can be called when using the full curses. Those marked with an asterisk can be called when using minicurses. Note: In the following routines, flag is a Boolean variable and should have a value of TRUE or FALSE. addch(int ch);* Add the character ch to stdscr (like putchar), wrapping to the next line at the end of a line. waddch(window *win, int ch); Add the character ch to win. Processed August 6, 1991 CURSES(3x,L) 2 CURSES(3x,L) AIX Technical Reference CURSES(3x,L) mvwaddch(window *w, int y, int x, int ch); Move cursor position to (y, x) then add the character ch to win. addstr(int str);* Call addch with each character in str. mvaddstr(int y, int x; int str); Move cursor position to (y, x) then add str. waddstr(window *win, int str); Add the string str to win. mvwaddstr(window *win, int y, int x, int str); Move cursor position to (y, x) then add the string str to win. attroff(int attrs); Turn off the attributes named in attrs. attron(int attrs); Turn on the attributes named in attrs. attrset(int attrs); Set current attributes to those specified in attrs. baudrate ( );* Set current terminal speed. beep ( );* Sound beep on terminal. box(window *win, int vert, int hor); Draw a box around edges of win. The vert and hor parameters are the characters to use for vertical and horizontal edges of the box. cbreak ( );* Set cbreak mode. nocbreak ( );* Unset cbreak mode. clear ( ); Clear stdscr. clearok(window *win, int bf); Clear screen before next redraw of win. clrtobot ( ); Clear to bottom of stdscr. clrtoeol ( ); Clear to end of line on stdscr. delay_output(int ms);* Insert ms millisecond pause in output. nodelay(window *win, int bf); Enable nodelay input mode through getch. delch ( ); Delete a character from stdscr. Processed August 6, 1991 CURSES(3x,L) 3 CURSES(3x,L) AIX Technical Reference CURSES(3x,L) deleteln ( ); Delete a line from stdscr. The insertln, deleteln, and scroll routines give unexpected results on the standard window when used within a subwindow. These results will not be visible until you use refresh or wrefresh to display the standard window. To avoid these problems, use newreview rather than subwin when you need to use deleteln. delwin(window *win); Delete window win. doupdate ( ); Update screen from all wnoutrefresh. echo ( );* Set echo mode. noecho ( );* Unset echo mode. endwin ( );* End window modes. erase ( ); Erase stdscr. erasechar ( ); Return user's erase character. fixterm ( ); Restore terminal to in curses state. flash ( ); Flash screen or beep. flushinp ( );* Throw away any type-ahead. getch ( );* Get a character from tty. getstr(int *str); Get a string through stdscr. gettmode ( ); Establish current tty modes. getyx(window *win, int y, int x); Get (y, x) coordinates. has_ic ( ); Returns the value of TRUE if terminal can insert characters. has_il ( ); Returns the value of TRUE if terminal can insert lines. idlok(window *win, int bf);* Use terminal's insert/delete line if flag!=0. inch ( ); Get character at current (y, x) coordinates. initscr ( );* Initialize screens. insch(c); Insert a character. Processed August 6, 1991 CURSES(3x,L) 4 CURSES(3x,L) AIX Technical Reference CURSES(3x,L) insertln ( ); Insert a line. The insertln, deleteln, and scroll routines give unexpected results on the standard window when used within a subwindow. These results will not be visible until you use refresh or wrefresh to display the standard window. To avoid these problems, use newview rather than subwin when you need to use insertln. intrflush(window *win, int bf);* Interrupt flush output if flag is true. keypad(WINDOW *win, int flag);* Enable keypad and function keys. killchar ( ); Return current user's kill character. leaveok(window *win, int flag); Permit cursor to be left anywhere after refresh if FALSE for win; otherwise cursor must be left at current position. longname ( ); Return verbose name of terminal. meta(window *win, int flag); Allow metacharacters on input if FALSE. move(int y, int x); Moves cursor to (y, x) on stdscr. mvaddch(int y, int x, int ch); Move cursor position to (y, x) then add ch. mvcur(int oldrow, int oldcol, int newrow, int newcol); Move cursor from current position to another position. mvdelch(int y, int x); Move cursor position to (y, x) then delete a character. mvgetch(int y, int x); Move cursor position to (y, x) then get a character from tty. mvgetstr(int y, int x, int str); Move cursor position to (y, x) then get a string through stdscr. mvinch(int y, int x,); Move cursor position to (y, x) then get the character at current (y, x) coordinates. mvinsch(int y, int x, int c); Move cursor position to (y, x) then insert the character c. Processed August 6, 1991 CURSES(3x,L) 5 CURSES(3x,L) AIX Technical Reference CURSES(3x,L) mvprintw(int y, int x, int fmt, int args); Move cursor position to (y, x) then get printf on stdscr. mvscanw(int y, int x, int fmt, int args); Move cursor position to (y, x) then scan through stdscr. mvwdelch(window, *win, int y, int x); Move cursor position to (y, x) then delete a character from win. mvwgetch(window *win, int y, int x); Move cursor position to (y, x) then get a character through win. mvwgetstr(window *win, int y, int x, int str); Move cursor position to (y, x) then get a string through win. mvwin(window *win, int by, int bx); Move win so that the upper left-hand corner is located at (y, x). mvwinch(window *win, int y, int x); Move cursor position to (y, x) then get the character at current (y, x) in win. mvwinsch(window *win, int y, int x, int c); Move cursor position to (y, x) then insert the character c into win. mvwprint(window *win, int y, int x, char *fmt, int args); Move cursor position to (y, x) then printf on stdscr. mvwscanw(window *win, int y, int x, char *fmt, int args); Move cursor position to (y, x) then scanf through stdscr. window * newpad(int nlines, int ncols); Create a new pad with given dimensions. struct screen *newterm(char *type, FILE *outfd, FILE *infd); Set up new terminal of given type to output on fd. window *newwin(int nlines, int ncols, int by, int bx); Create a new window. nl ( )*; Set newline mapping. nonl ( )*; Unset newline mapping. overlay(window *win1, window *win2); Overlay win1 on win2. Processed August 6, 1991 CURSES(3x,L) 6 CURSES(3x,L) AIX Technical Reference CURSES(3x,L) overwrite(window *win1, window *win2); Overwrite win1 on top of win2. printw(char *fmt, va_dcl); Printw on stdscr. raw ( );* Set raw mode. refresh ( );* Make curscr look like stdscr. 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. 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. noraw ( );* Unset raw mode. resetterm ( );* Set tty modes to out of curses state. resetty ( );* Reset tty flags to stored value. saveterm ( );* Save current modes as in curses state. savetty ( );* Store current tty flags. scanw(char *fmt, va_dcl); Scanf through stdscr. scroll(window *win); Scroll win one line. The insertln, deleteln, and scroll routines give unexpected results on the standard window when used within a subwindow. These results will not be visible until you use refresh or wrefresh to display the standard window. To avoid these problems, use newview rather than subwin if you need to use scroll. scrollok(window *win, int bf); Allow terminal to scroll if flag=FALSE. set_term(char *type); Enable talk to terminal new. setscrreg(int t, int b) Set user scrolling region to lines short t through short b. Processed August 6, 1991 CURSES(3x,L) 7 CURSES(3x,L) AIX Technical Reference CURSES(3x,L) setterm(char *type); Establish terminal with a given type. standend ( )* Clear standout mode attribute. standout ( )* Set standout mode attribute. subwin(window *orig, int num_lines, int num_cols, int begy, int begx); Create a subwindow. The insertln, deleteln, and scroll routines give unexpected results on the standard window when used within a subwindow. These results will not be visible until you use refresh or wrefresh to display the standard window. To avoid these problems, use newview rather than subwin in these situations. touchwin(window *win); Forces the next call to refresh( ) to write the entire window. traceoff ( ) Turn off debugging trace output. traceon ( ) Turn on debugging trace output. typeahead(int fd); Check file descriptor fd to check type-ahead. unctrl(ch)* Use printable version of ch. wattroff(window *win, int attrs); Turn off attrs in win. wattron(WINDOW *win, int attrs); Turn on attrs in win. wattrset(window *win, int attrs); Set attributes in win to attrs. wclear(WINDOW *win); Clear win. wclrtobot(WINDOW *win); Clear to bottom of win. wclrtoeol(WINDOW *win); Clear to end of line on win. wdelch(WINDOW *win); Delete the character at the current cursor coordinates in win. wdeleteln(WINDOW *win); Delete line from win werase(WINDOW *win); Erase win. wgetch(WINDOW *win); Get a character through win. Processed August 6, 1991 CURSES(3x,L) 8 CURSES(3x,L) AIX Technical Reference CURSES(3x,L) wgetstr(WINDOW *win, char *str); Get the string str through win. winch(WINDOW *win); Get the character at current cursor coordinates in win. winsch(WINDOW *win, chtype c); Insert the character c into win. winsertln(WINDOW *win); Insert line into win. wmove(WINDOW *win, int y, int x); Move the cursor to (y, x) coordinates on win. wnoutrefresh(WINDOW *win); Refresh but no screen output. wprintw(WINDOW *win, char *fmt, va_dcl); printf on win. wrefresh(WINDOW *win); Make screen look like win. wscanw(WINDOW *win, char *fmt, va_dcl); scanf through win. wsetscrreg(WINDOW *win, int t, int b); Set scrolling region of win to lines short t through short b. wstandend(WINDOW *win); Clear standout attribute in win. wstandout(WINDOW *win); Set standout attribute in win. TERMINFO LEVEL SUBROUTINES These routines should be called by programs that have to deal directly with the terminfo data base. Due to the low level of this interface, its use is discouraged. The header files curses.h and term.h should be included (in that order) to get the definitions for these strings, numbers, and flags. You should call setupterm before using any of the other terminfo subroutines. This defines the set of terminal-dependent variables defined in the terminfo file. If the 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 smaller code, but only one terminal can be used at a time for the program. Capabilities with a Boolean value have the value 1 if the capability is present Processed August 6, 1991 CURSES(3x,L) 9 CURSES(3x,L) AIX Technical Reference CURSES(3x,L) and 0 if it is not. Numeric capabilities have a value of -1 if the capability is missing and a value of 0 or greater if it is present. String capabilities have a NULL value if the capability is missing and otherwise have type char * and point to a character string that contains the capability. Special character codes that use the backslash and circumflex characters (\ and ^) are transformed into the appropriate ASCII characters. Padding information of the form $