intro(3cur)
Name
intro − introduction to the X/Open Curses Package, which optimizes terminal screen handling and updating
Syntax
#include <cursesX.h>
cc [ options ] files −lcursesX [ libraries ]
Description
The curses (cursor optimization) package is the X/Open set of library routines used for writing screen-management programs. Cursor optimization minimizes the amount the cursor has to be moved around the screen in order to update it. Screen-management programs are used for tasks such as moving the cursor, printing a menu, dividing a terminal screen into windows or drawing a display on a screen for data entry and retrieval.
The curses package is split into three parts: screen updating, screen updating with user input, and cursor motion optimization. Screen-updating routines are used when parts of the screen need to be changed but the overall image remains the same. The cursor motion part of the package can be used separately for tasks such as defining how the cursor moves in response to tabs and newline characters
The curses routines do not write directly to the terminal screen (the physical screen): instead, they write to a window, a two-dimensional array of characters which represents all or part of the terminal screen. A window can be as big as the terminal screen or any smaller size down to a single character.
The <cursesX.h> header file supplies two default windows, stdscr (standard screen) and curscr (current screen) for all programs using curses routines. The stdscr window is the size of the current terminal screen. The curscr window is not normally accessed directly by the screen-management program; changes are made to the appropriate window and then the refresh routine is called. The screen program keeps track of what is on the physical screen and what is on stdscr. When refresh is called, it compares the two screen images and then sends a stream of characters to the terminal to make the physical screen look like stdscr.
The header file <cursesX.h> defines stdscr to be of the type WINDOW*. This is a pointer to a C structure which includes the starting position of the window on the screen and the window size.
Some curses routines are designed to work with a pad. A pad is a type of window whose size is not restricted by the size of the screen. Use a pad when you only need part of a window on the screen at any one time, for example when running a spreadsheet application.
Other windows can be created with newwin and used instead of stdscr for maintaining several different screen images, for example, one window can control input/output and another can display error messages. The routine subwin creates subwindows within windows. When windows overlap, the contents of the current screen show the most recently refreshed window.
Among the most basic routines are move and addch. These routines are used to move the cursor around and to add characters to the default window, stdscr.
All curses data is manipulated using the routines provided by the curses library. You should not use routines or system calls from other libraries in a curses program as they may cause undesirable results when you run the program.
Using Curses
The curses library has three types of routines; Main routines, TERMINFO routines and TERMCAP compatibility routines
The terminfo routines are a group of routines within the curses library which provide a database containing descriptions of many terminals that can be used with curses programs. The termcap compatibility routines are provided as a conversion aid for programs using termcap.
Most screen handling can be achieved using the Main routines. The following hints should help you make the most of the screen-handling routines.
The <cursesX.h> header file must always be included whenever curses functions are used in a program. Note that the header file includes <sgtty.h> to enable the terminal to use the features provided by ULTRIX. All the manual definitions assume that <cursesX.h> has been included in the code.
The header file defines global variables and data structures, and defines several of the routines as macros. The integer variables LINES and COLS are defined so that when a curses program is run on a particular terminal, initscr assigns the vertical and horizontal dimensions of the terminal screen to these variables.
A curses program must start by calling the routine initscr to allocate memory space for the windows. It should only be called once in a program, as it can overflow core memory if it is called repeatedly. The routine endwin is used to exit from the screen-handling routines.
Most interactive screen-oriented programs need character-at-a-time input without echoing. To achieve this, you should call:
nonl();
cbreak();
noecho();
immediately after calling initscr. All curses routines that move the cursor, move it relative to the home position in the upper left corner of the screen. The (LINES, COLS) coordinate at this position is (1,1). Note that the vertical coordinate y is given first and the horizontal coordinate x is given second. The −1 in the example program takes the home position into account to place the cursor on the centre line of the terminal screen. The example program displays MIDSCREEN in the centre of the screen. Use the refresh routine after changing a screen to make the terminal screen look like stdscr.
Example Program
#include <cursesX.h>
main ()
{
initscr(); /*initialize terminal settings, data
** structures and variables*/
move(LINES/2 −1, COLS/2 −4);
addstr("MID");
refresh(); /* send output to update terminal
** screen */
addstr("SCREEN");
refresh(); /* send more output to terminal
** screen */
endwin(); /*restore all terminal settings */
}
Main Routines
Routines listed here can be called when using the curses library. Routines that are preceded by a w affect a specified window, those preceded by a p affect a specified pad. All other routines affect the default window stdscr. Windows are specified by a numeric argument, for example: winch (win) where win is the specified window.
| addch(ch) | Add a character to stdscr (like putchar wraps to next line at end of line) |
| addstr(str) | Call addch with each character in str |
| attroff(attrs) | Turn off named attributes |
| attron(attrs) | Turn on named attributes |
| attrset(attrs) | Set current attributes to attrs |
| baudrate() | Display current terminal speed |
| beep() | Sound beep on terminal |
| box(win, vert, hor) | Draw a box around edges of win, |
| vert and hor are characters to use for vertical | |
| and horizontal edges of box | |
| clear() | Clear stdscr |
| clearok(win, bf) | Clear screen before next redraw of win |
| clrtobot() | Clear to bottom of stdscr |
| clrtoeol() | Clear to end of line on stdscr |
| cbreak() | Set cbreak mode |
| delay_output(ms) | Insert ms millisecond pause in output |
| delch() | Delete a character |
| deleteln() | Delete a line |
| delwin(win) | Delete win |
| doupdate() | Update screen from all wnoutrefresh |
| echo() | Set echo mode |
| endwin() | End window modes |
| erase() | Erase stdscr |
| erasechar() | Return user’s erase character |
| fixterm() | Restore tty to in “curses” state |
| flash() | Flash screen or beep |
| flushinp() | Throw away any typeahead |
| getch() | Get a character from tty |
| getstr(str) | Get a string through stdscr |
| gettmode() | Establish current tty modes |
| getyx(win, y, x) | Get (y, x) coordinates |
| has_ic() | True if terminal can do insert character |
| has_il() | True if terminal can do insert line |
| idlok(win, bf) | Use terminal’s insert/delete line if bf != 0 |
| inch() | Get character at current (y, x) coordinates |
| initscr() | Initialize screens |
| insch(c) | Insert a character |
| insertln() | Insert a line |
| intrflush(win, bf) | Interrupt flush output if bf is TRUE |
| keypad(win, bf) | Enable keypad input |
| killchar() | Return current user’s kill character |
| leaveok(win, flag) | Leave cursor anywhere after refresh if |
| flag!=0 for win. Otherwise cursor must be left | |
| at current position | |
| longname() | Return verbose name of terminal |
| meta(win, flag) | Allow meta characters on input if flag != 0 |
| move(y, x) | Move to (y, x) on stdscr |
NOTE: The following routines prefixed with mv require y and x coordinates to move to, before performing the same functions as the standard routines. As an example, mvaddch performs the same function as addch,but y and x coordinates must be supplied first. The routines prefixed with mvw also require a window or pad argument.
| mvaddch(y, x, ch) | |
| mvaddstr(y, x, str) | |
| mvcur(oldrow, oldcol, newrow, | low level cursor motion |
| newcol) | |
| mvdelch(y, x) | |
| mvgetch(y, x) | |
| mvgetstr(y, x) | |
| mvinch(y, x) | |
| mvinsch(y, x, c) | |
| mvprintw(y, x, fmt, args) | |
| mvscanw(y, x, fmt, args) | |
| mvwaddch(win, y, x, ch) | |
| mvwaddstr(win, y, x, str) | |
| mvwdelch(win, y, x) | |
| mvwgetch(win, y, x) | |
| mvwgetstr(win, y, x) | |
| mvwin(win, by, bx) | |
| mvwinch(win, y, x) | |
| mvwinsch(win, y, x, c) | |
| mvwprintw(win, y, x, fmt, args) | |
| mvwscanw(win, y, x, fmt, args) | |
| newpad(nlines, ncols) | Create a new pad with given dimensions |
| newterm(type, fd) | Set up new terminal of given type to output on fd |
| newwin(lines, cols, | Create a new window |
| begin_y, begin_x) | |
| nl() | Set newline mapping |
| nocbreak() | Unset cbreak mode |
| nodelay(win, bf) | Enable nodelay input mode through getch |
| noecho() | Unset echo mode |
| nonl() | Unset newline mapping |
| noraw() | Unset raw mode |
| overlay(win1, win2) | Overlay win1 on win2 |
| overwrite(win1, win2) | Overwrite win1 on top of win2 |
| pnoutrefresh(pad, pminrow, | Like prefresh but with no output |
| pmincol, sminrow, smincol, | until doupdate called |
| smaxrow, smaxcol) | |
| prefresh(pad, pminrow, | Refresh from pad starting with given upper |
| pmincol, sminrow, smincol, | left corner of pad with output to |
| smaxrow, smaxcol) | given portion of screen |
| printw(fmt, arg1, arg2, ...) | printf on stdscr |
| raw() | Set raw mode |
| refresh() | Make current screen look like stdscr |
| 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(fmt, arg1, arg2, ...) | scanf through stdscr |
| scroll(win) | Scroll win one line |
| scrollok(win, flag) | Allow terminal to scroll if flag != 0 |
| set_term(new) | Switch between different terminals |
| setscrreg(t, b) | Set user scrolling region to lines t through b |
| setupterm(term, filenum, errret) | Low level terminal setup |
| standend() | Clear standout mode attribute |
| standout() | Set standout mode attribute |
| subwin(win, lines, cols, | Create a subwindow |
| begin_y, begin_x) | |
| touchwin(win) | “change” all of win |
| traceoff() | Turn off debugging trace output |
| traceon() | Turn on debugging trace output |
| typeahead(fd) | Use file descriptor fd to check typeahead |
| unctrl(ch) | Produce printable version of ch |
| waddch(win, ch) | Add character to win |
| waddstr(win, str) | Add string to win |
| wattroff(win, attrs) | Turn off attrs in win |
| wattron(win, attrs) | Turn on attrs in win |
| wattrset(win, attrs) | Set attrs in win to attrs |
| wclear(win) | Clear win |
| wclrtobot(win) | Clear to bottom of win |
| wclrtoeol(win) | Clear to end of line on win |
| wdelch(win, c) | Delete char from win |
| wdeleteln(win) | Delete line from win |
| werase(win) | Erase win |
| wgetch(win) | Get a character through win |
| wgetstr(win, str) | Get a string through win |
| winch(win) | Get character at current (y, x) in win |
| winsch(win, c) | Insert char into win |
| winsertln(win) | Insert line into win |
| wmove(win, y, x) | Set current (y, x) coordinates on win |
| wnoutrefresh(win) | Refresh but no screen output |
| wprintw(win, fmt, | printf on win |
| arg1, arg2, ...) | |
| wrefresh(win) | Make screen look like win |
| wscanw(win, fmt, | scanf through win |
| arg1, arg2, ...) | |
| wsetscrreg(win, t, b) | Set scrolling region of win |
| wstandend(win) | Clear standout attribute in win |
| wstandout(win) | Set standout attribute in win |
Caution
The plotting library plot() and the curses() library 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 to the curses() code, and/or #undef move() and erase() in the plot() code.
TERMINFO Level Routines
If the environment variable TERMINFO is defined, any program using curses will check for a local terminal definition before checking in the standard libraries. For example, if the standard place is /usr/lib/terminfo,and set to vt100, the compiled file will normally be found in /usr/lib/terminfo/v/vt100. The v is copied from the first letter of vt100 to avoid creating huge directories. However, if TERMINFO is set to /usr/mark/myterms, curses will first check /usr/mark/myterms/v/vt100, and if that fails, will then check /usr/lib/terminfo/v/vt100. This is useful for developing experimental definitions or when there is no write permission for /usr/lib/terminfo.
These routines should be called by programs that need to deal directly with the terminfo database, but as this is a low level interface, it is not recommended.
Initially, the routine setupterm should be called. This will define the set of terminal-dependent variables defined in terminfo(.). The include files <cursesX.h> and <term.h> should be included to get the definitions for these strings, numbers, and flags. Parameterized strings should be passed through tparm to instantiate them. All terminfo strings (including the output of tparm) should be printed with tputs or putp. Before exiting, resetterm should be called to restore the tty modes.
Programs which want shell escapes or <CTRLZ> suspending can call resetterm before the shell is called and fixterm after returning from the shell.
| fixterm() | Restore tty modes for terminfo use |
| (called by setupterm) | |
| resetterm() | Reset tty modes to state before program entry |
| setupterm(term, fd, rc) | Read in database. Terminal type is the |
| character string term, all output is to ULTRIX | |
| System file descriptor fd. A status value is | |
| returned in the integer pointed to by rc: 1 | |
| is normal. The simplest call would be | |
| setupterm(0, 1, 0) which uses all defaults | |
| tparm(str, p1, p2, ..., p9) | Instantiate string str with parms pi |
| tputs(str, affcnt, putc) | Apply padding info to string str |
| affcnt is the number of lines affected, | |
| or 1 if not applicable. Putc is a | |
| putchar-like function to which the characters | |
| are passed, one at a time | |
| putp(str) | A function that calls tputs |
| (str, 1, putchar) | |
| vidputs(attrs, putc) | Output the string to put terminal in video |
| attribute mode attrs, which is any | |
| combination of the attributes listed below | |
| Chars are passed to putchar-like | |
| function putc | |
| vidattr(attrs) | Like vidputs but outputs through |
| putchar |
Termcap Compatibility Routines
The following routines were included as a conversion aid for programs that use termcap. Their parameters are the same as for termcap. They are emulated using the terminfo database.
DO NOT use these routines in new programs.
| tgetent(bp, name) | Look up termcap entry for name |
| tgetflag(id) | Get boolean entry for id |
| tgetnum(id) | Get numeric entry for id |
| tgetstr(id, area) | Get string entry for id |
| tgoto(cap, col, row) | Apply parms to given cap |
| tputs(cap, affcnt, fn) | Apply padding to cap calling fn as putchar |
As an aid to compatibility, the object module termcap.o has been provided in /usr/lib/termcap.o. This module should be linked into an application before resolving against the curses library. If your application contains references such as UP then recompile using
cc [options] files /usr/lib/termcap.o −lcursesX [libs]
Errors
No errors are defined for the curses functions.
Return Values
For most curses routines, the OK value is returned if a routine is properly completed and the ERR value is returned if some error occurs.
See Also
tic(1), ioctl(2), getenv(3), printf(3s), putchar(3s), scanf(3s), plot(3x), termcap(5), terminfo(5)
Guide to X/Open curses Screen Handling