diff options
Diffstat (limited to 'lib/libncurses')
-rw-r--r-- | lib/libncurses/Makefile | 3 | ||||
-rw-r--r-- | lib/libncurses/curs_termin.3 | 190 | ||||
-rw-r--r-- | lib/libncurses/doc/color.doc | 71 | ||||
-rw-r--r-- | lib/libncurses/doc/manual.doc | 1361 |
4 files changed, 1624 insertions, 1 deletions
diff --git a/lib/libncurses/Makefile b/lib/libncurses/Makefile index 452666c..ab24ed5 100644 --- a/lib/libncurses/Makefile +++ b/lib/libncurses/Makefile @@ -1,5 +1,5 @@ # Makefile for ncurses -# $Id: Makefile,v 1.9 1994/12/04 02:43:41 ache Exp $ +# $Id: Makefile,v 1.10 1995/02/13 17:23:18 ache Exp $ LIB= ncurses SRCS= lib_kernel.c lib_pad.c lib_bkgd.c \ @@ -71,6 +71,7 @@ MAN3 = curs_addch.3 \ curs_scroll.3 \ curs_slk.3 \ curs_termatt.3 \ + curs_termin.3 \ curs_touch.3 \ curs_util.3 \ curs_window.3 \ diff --git a/lib/libncurses/curs_termin.3 b/lib/libncurses/curs_termin.3 new file mode 100644 index 0000000..862b943 --- /dev/null +++ b/lib/libncurses/curs_termin.3 @@ -0,0 +1,190 @@ +.TH curs_terminfo 3X "" +.ds n 5 +.SH NAME +\fBcurs_terminfo\fR: \fBsetupterm\fR, \fBsetterm\fR, +\fBset_curterm\fR, \fBdel_curterm\fR, \fBrestartterm\fR, \fBtparm\fR, +\fBtputs\fR, \fBputp\fR, \fBvidputs\fR, \fBvidattr\fR, \fBmvcur\fR, +\fBtigetflag\fR, \fBtigetnum\fR, \fBtigetstr\fR - \fBncurses\fR +interfaces to terminfo database +.SH SYNOPSIS +\fB#include <ncurses.h>\fR +.br +\fB#include <term.h>\fR + +\fBint setupterm(char *term, int fildes, int *errret);\fR +.br +\fBint setterm(char *term);\fR +.br +\fBint set_curterm(TERMINAL *nterm);\fR +.br +\fBint del_curterm(TERMINAL *oterm);\fR +.br +\fBint restartterm(char *term, int fildes, int *errret);\fR +.br +\fBchar *tparm(char *str, long int p1, long int p2, long int p3, + long int p4, long int p5, long int p6, long int p7,\fR + long int p8, long int p9);\fR +\fBint tputs(char *str, int affcnt, int (*putc)(char));\fR +.br +\fBint putp(char *str);\fR +.br +\fBint vidputs(chtype attrs, int (*putc)(char));\fR +.br +\fBint vidattr(chtype attrs);\fR +.br +\fBint mvcur(int oldrow, int oldcol, int newrow, int newcol);\fR +.br +\fBint tigetflag(char *capname);\fR +.br +\fBint tigetnum(char *capname);\fR +.br +\fBint tigetstr(char *capname);\fR +.br +.SH DESCRIPTION +These low-level routines must be called by programs that have to deal +directly with the \fBterminfo\fR database to handle certain terminal +capabilities, such as programming function keys. For all other +functionality, \fBncurses\fR routines are more suitable and their use is +recommended. + +Initially, \fBsetupterm\fR should be called. Note that +\fBsetupterm\fR is automatically called by \fBinitscr\fR and +\fBnewterm\fR. This defines the set of terminal-dependent variables +[listed in \fBterminfo\fR(\*n)]. The \fBterminfo\fR variables +\fBlines\fR and \fBcolumns\fR are initialized by \fBsetupterm\fR as +follows: If \fBuse_env(FALSE)\fR has been called, values for +\fBlines\fR and \fBcolumns\fR specified in \fBterminfo\fR are used. +Otherwise, if the environment variables \fBLINES\fR and \fBCOLUMNS\fR +exist, their values are used. If these environment variables do not +exist and the program is running in a window, the current window size +is used. Otherwise, if the environment variables do not exist, the +values for \fBlines\fR and \fBcolumns\fR specified in the +\fBterminfo\fR database are used. + +The header files \fBncurses.h\fR and \fBnterm.h\fR should be included (in this +order) to get the definitions for these strings, numbers, and flags (these +correspond to the SVr4 headers \fBcurses.h\fR and \fBterm.h\fR). Parameterized +strings should be passed through \fBtparm\fR to instantiate them. All +\fBterminfo\fR strings [including the output of \fBtparm\fR] should be printed +with \fBtputs\fR or \fBputp\fR. Call the \fBreset_shell_mode\fR to restore the +tty modes before exiting [see \fBcurs_kernel\fR(3X)]. Programs which use +cursor addressing should output \fBenter_ca_mode\fR upon startup and should +output \fBexit_ca_mode\fR before exiting. Programs desiring shell escapes +should call + +\fBreset_shell_mode\fR and output \fBexit_ca_mode\fR before the shell +is called and should output \fBenter_ca_mode\fR and call +\fBreset_prog_mode\fR after returning from the shell. + +The \fBsetupterm\fR routine reads in the \fBterminfo\fR database, +initializing the \fBterminfo\fR structures, but does not set up the +output virtualization structures used by \fBncurses\fR. The terminal +type is the character string \fIterm\fR; if \fIterm\fR is null, the +environment variable \fBTERM\fR is used. All output is to file +descriptor \fBfildes\fR which is initialized for output. If +\fIerrret\fR is not null, then \fBsetupterm\fR returns \fBOK\fR or +\fBERR\fR and stores a status value in the integer pointed to by +\fIerrret\fR. A status of \fB1\fR in \fIerrret\fR is normal, \fB0\fR +means that the terminal could not be found, and \fB-1\fR means that +the \fBterminfo\fR database could not be found. If \fIerrret\fR is +null, \fBsetupterm\fR prints an error message upon finding an error +and exits. Thus, the simplest call is: + + \fBsetupterm((char *)0, 1, (int *)0);\fR, + +which uses all the defaults and sends the output to \fBstdout\fR. + +The \fBsetterm\fR routine is being replaced by \fBsetupterm\fR. The call: + + \fBsetupterm(\fR\fIterm\fR\fB, 1, (int *)0)\fR + +provides the same functionality as \fBsetterm(\fR\fIterm\fR\fB)\fR. +The \fBsetterm\fR routine is included here for BSD compatibility, and +is not recommended for new programs. + +The \fBset_curterm\fR routine sets the variable \fBcur_term\fR to +\fInterm\fR, and makes all of the \fBterminfo\fR boolean, numeric, and +string variables use the values from \fInterm\fR. + +The \fBdel_curterm\fR routine frees the space pointed to by +\fIoterm\fR and makes it available for further use. If \fIoterm\fR is +the same as \fBcur_term\fR, references to any of the \fBterminfo\fR +boolean, numeric, and string variables thereafter may refer to invalid +memory locations until another \fBsetupterm\fR has been called. + +The \fBrestartterm\fR routine is similar to \fBsetupterm\fR and +\fBinitscr\fR, except that it is called after restoring memory to a +previous state. It assumes that the windows and the input and output +options are the same as when memory was saved, but the terminal type +and baud rate may be different. + +The \fBtparm\fR routine instantiates the string \fIstr\fR with +parameters \fIpi\fR. A pointer is returned to the result of \fIstr\fR +with the parameters applied. + +The \fBtputs\fR routine applies padding information to the string +\fIstr\fR and outputs it. The \fIstr\fR must be a terminfo string +variable or the return value from \fBtparm\fR, \fBtgetstr\fR, or +\fBtgoto\fR. \fIaffcnt\fR is the number of lines affected, or 1 if +not applicable. \fIputc\fR is a \fBputchar\fR-like routine to which +the characters are passed, one at a time. + +The \fBputp\fR routine calls \fBtputs(\fR\fIstr\fR\fB, 1, putchar)\fR. +Note that the output of \fBputp\fR always goes to \fBstdout\fR, not to +the \fIfildes\fR specified in \fBsetupterm\fR. + +The \fBvidputs\fR routine displays the string on the terminal in the +video attribute mode \fIattrs\fR, which is any combination of the +attributes listed in \fBncurses\fR(3X). The characters are passed to +the \fBputchar\fR-like routine \fIputc\fR. + +The \fBvidattr\fR routine is like the \fBvidputs\fR routine, except +that it outputs through \fBputchar\fR. + +The \fBmvcur\fR routine provides low-level cursor motion. It takes +effect immediately (rather than at the next refresh). + +The \fBtigetflag\fR, \fBtigetnum\fR and \fBtigetstr\fR routines return +the value of the capability corresponding to the \fBterminfo\fR +\fIcapname\fR passed to them, such as \fBxenl\fR. + +With the \fBtigetflag\fR routine, the value \fB-1\fR is returned if +\fIcapname\fR is not a boolean capability. + +With the \fBtigetnum\fR routine, the value \fB-2\fR is returned if +\fIcapname\fR is not a numeric capability. + +With the \fBtigetstr\fR routine, the value \fB(char *)-1\fR is +returned if \fIcapname\fR is not a string capability. + +The \fIcapname\fR for each capability is given in the table column entitled +\fIcapname\fR code in the capabilities section of \fBterminfo\fR(\*n). + +\fBchar *boolnames\fR, \fB*boolcodes\fR, \fB*boolfnames\fR + +\fBchar *numnames\fR, \fB*numcodes\fR, \fB*numfnames\fR + +\fBchar *strnames\fR, \fB*strcodes\fR, \fB*strfnames\fR + +These null-terminated arrays contain the \fIcapnames\fR, the +\fBtermcap\fR codes, and the full C names, for each of the +\fBterminfo\fR variables. +.SH RETURN VALUE +All routines return the integer \fBERR\fR upon failure and an integer value +other than \fBERR\fR upon successful completion, unless otherwise noted in the +preceding routine descriptions. + +Routines that return pointers always return \fBNULL\fR on error. +.SH NOTES +The \fBsetupterm\fR routine should be used in place of \fBsetterm\fR. + +Note that \fBvidattr\fR and \fBvidputs\fR may be macros. +.SH SEE ALSO +\fBncurses\fR(3X), \fBcurs_initscr\fR(3X), \fBcurs_kernel\fR(3X), \fBcurs_termcap\fR(3X), +\fBputc\fR(3S), \fBterminfo\fR(\*n) +.\"# +.\"# The following sets edit modes for GNU EMACS +.\"# Local Variables: +.\"# mode:nroff +.\"# fill-column:79 +.\"# End: diff --git a/lib/libncurses/doc/color.doc b/lib/libncurses/doc/color.doc new file mode 100644 index 0000000..55f3346 --- /dev/null +++ b/lib/libncurses/doc/color.doc @@ -0,0 +1,71 @@ + + 5.10. Color Manipulation + + Ncurses provides support for the use of color on terminals + that are capable of display it. Note the BSD and older SYSV + curses don't support color. Color support in the PC version + is not compatible with SYSR4. + + has_colors() + this function returns TRUE if the terminal supports color, + FALSE otherwise. Other color handling funtions will return + ERR if has_colors() is FALSE. You should always check before + using color and use other video attributes to replace color. + + can_change_color() + This function returns TRUE if the terminal is capable of + redefining colors using the init_color function, FALSE if it + can't. Don't use init_color and color_content if it returns + FALSE. + + start_color() + This function must be called before any other color handling + function is called. It initializes the 8 basic colors (see + appendix I) and sets the global variables COLORS and COLOR_ + PAIRS to the maximum number of colors and color-pairs a + terminal can handle. + + init_pair(pair, fg, bg) + This function changes the definition of a color-pair, pair. + Each pair has a foregroung color fg, and a background color + bg. Both values must be between 0 and COLORS-1. pair must be + between 1 and COLOR_PAIRS-1. + [If a pair is changed from a previous definition, the screen + is refreshed and all occurances of the color-pair are + changed to reflect the change.] + + pair_content(pair, f, b) + This function stores the foreground and background colors of + the color-pair pair into the variables pointed to by f, b. + pair should be between 1 and COLOR_PAIRS-1. + + init_color(color, r, g, b) + This function changes the value of a given color. A color is + defined by its red, green, and blue components, r, g, and b. + These values must be between 0 and 1000. color should be + between 0 and COLORS-1. + + color_content(color, r, g, b) + This function puts the red, green, and blue components of + color into the variable pointed to by r, g, b respectively. + color should be between 0 and COLORS-1. + + COLOR_PAIR(n) set color-pair to that stored in n + PAIR_NUMBER(a) get color-pair stored in attribute a + + + Appendix II: COLORS + ------------------- + + Colors are defined in <ncurses.h> are used with init_pair(). + + COLOR_BLACK 0 + COLOR_RED 1 + COLOR_GREEN 2 + COLOR_YELLOW 3 + COLOR_BLUE 4 + COLOR_MAGENTA 5 + COLOR_CYAN 6 + COLOR_WHITE 7 + + diff --git a/lib/libncurses/doc/manual.doc b/lib/libncurses/doc/manual.doc new file mode 100644 index 0000000..5ae7d39 --- /dev/null +++ b/lib/libncurses/doc/manual.doc @@ -0,0 +1,1361 @@ + + + + + + + + + + The Curses Reference Manual + + Pavel Curtis 1982 + Zeyd M. Ben-Halim 1993 + zmbenhal@netcom.com + + + + + + + Caveat Emptor: + I'm slowly but surely updating the documentation of + ncurses to reflect the current status of the code. The text + below may refer to yet to be implemented functions or + missing functionality. Description of functions may be + missing or out of date. ncurses is aimed at being compatible + with AT&T curses as defined in SysVR4. + + There is no ?roff sources for this document. I may one day + go nuts and create one, but don't hold your breath :-) + + 1. Introduction + + Terminfo is a database describing many capabilities of over + 150 different terminals. Curses is a subroutine package + which presents a high level screen model to the programmer, + while dealing with issues such as terminal differences and + optimization of output to change one screenfull of text into + another. + Terminfo is based on Berkeley's termcap database, but con- + tains a number of improvements and extensions. Parameterized + strings are introduced, making it possible to describe such + capabilities as video attributes, and to handle far more + unusual terminals than possible with termcap. + Curses is also based on Berkeley's curses package, with many + improvements. The package makes use of the insert and + delete line and character features of terminals so equipped, + and determines how to optimally use these features with no + help from the programmer. It allows arbitrary combinations + of video attributes to be displayed, even on terminals that + leave ``magic cookies'' on the screen to mark changes in + attributes.+ + + 2. An Overview of the Package + + 2.1. Terminology + + In this document, the following terminology is kept + to with reasonable consistency: + + window An internal representation containing an image of + what a section of the terminal screen may look + like at some point in time. This subsection can + either encompass the entire terminal screen, or + any smaller portion down to a single character + within that screen. + terminal Sometimes called terminal screen. The package's + idea of what the terminal's screen currently looks + like, i.e., what the user sees now. This is a + special screen. + screen This is a subset of windows which are as large as + the terminal screen, i.e., they start at the upper + left hand corner and encompass the lower right + hand corner. One of these, stdscr, is automati- + cally provided for the programmer. + + 2.2. Compiling Programs using the Package + + In order to use the library, it is necessary to have + certain types and variables defined. Therefore, the pro- + grammer must have a line: + #include <ncurses.h> + at the top of the program source. The screen package + uses the Standard I/O library, so <ncurses.h> includes + <stdio.h>. Ncurses also includes <termios.h>, <termio.h>, or + <sgtty.h> depending on your system. It is redundant (but + harmless) for the programmer to do it, too. In linking with + ncurses you need to have `-lncurses' in your LDFLAGS or on + the command line. There is no need for any other libraries. + + 2.3. Updating the Screen + + In order to update the screen optimally, it is + necessary for the routines to know what the screen currently + looks like and what the programmer wants it to look like + next. For this purpose, a data type (structure) named WINDOW + is defined which describes a window image to the routines, + including its starting position on the screen (the (y, x) + coordinates of the upper left hand corner) and its size. + One of these (called curscr, for current screen) is a screen + image of what the terminal currently looks like. Another + screen (called stdscr, for standard screen) is provided by + default to make changes on. + A window is a purely internal representation. It is + used to build and store a potential image of a portion of + the terminal. It doesn't bear any necessary relation to + what is really on the terminal screen. It is more like an + array of characters on which to make changes. + When one has a window which describes what some part of + the terminal screen should look like, the routine refresh() + (or wrefresh() if the window is not stdscr) is called. + Refresh() in the area covered by the window, look like that + window. Note, therefore, that changing something on a win- + dow does not change the terminal. Actual updates to the + terminal screen are made only by calling refresh() or wre- + fresh(). This allows the programmer to maintain several + different ideas of what a portion of the terminal screen + should look like. Also, changes can be made to windows in + any order, without regard to motion efficiency. Then, at + will, the programmer can effectively say ``make it look like + this,'' and let the package worry about the best way to do + this. + + 2.4. Naming Conventions + + As hinted above, the routines can use several windows, + but two are automatically given: curscr, which knows what + the terminal looks like, and stdscr, which is what the pro- + grammer wants the terminal to look like next. The user + should never really access curscr directly. Changes should + be made to the appropriate screen, and then the routine + refresh() (or wrefresh()) should be called. + Many functions are set up to deal with stdscr as a + default screen. For example, to add a character to stdscr, + one calls addch() with the desired character. If a differ- + ent window is to be used, the routine waddch() (for + `w'indow-specific addch()) is provided. This convention of + prepending function names with a ``w'' when they are to be + applied to specific windows is consistent. The only rou- + tines which do not do this are those to which a window must + always be specified. + In order to move the current (y, x) coordinates from + one point to another, the routines move() and wmove() are + provided. However, it is often desirable to first move and + then perform some I/O operation. In order to avoid clumsy- + ness, most I/O routines can be preceded by the prefix 'mv' + and the desired (y, x) coordinates then can be added to the + arguments to the function. For example, the calls + move(y, x); + addch(ch); + can be replaced by + mvaddch(y, x, ch); + and + wmove(win, y, x); + waddch(win, ch); + can be replaced by + mvwaddch(win, y, x, ch); + Note that the window description pointer (win) comes before + the added (y, x) coordinates. If such pointers are need, + they are always the first parameters passed. + + 3. Variables + + Many variables which are used to describe the terminal + environment are available to the programmer. They are: + + type name description + ------------------------------------------------------------------ + WINDOW *curscr current version of the screen (terminal screen). + WINDOW *stdscr standard screen. Most updates are done here. + int LINES number of lines on the terminal + int COLS number of columns on the terminal + + There are also several `#define' constants and types which + are of general usefulness: + + bool boolean type, actually a `char' (e.g., bool doneit;) + TRUE boolean `true' flag (1). + FALSE boolean `false' flag (0). + ERR -1 error flag returned by routines on a fail. + OK 0 error flag returned by routines when things + go right. + + 4. Usage + + This is a description of how to actually use the screen + package. In it, we assume all updating, reading, etc. is + applied to stdscr. All instructions will work on any win- + dow, with changing the function name and parameters as men- + tioned above. + + 4.1. Starting up + + In order to use the screen package, the routines must + know about terminal characteristics, and the space for + curscr and stdscr must be allocated. These functions are + performed by initscr(). Since it must allocate space for the + windows, it can overflow memory when attempting to do so. On + this rather rare occasion, initscr() returns ERR. + initscr() must always be called before any of the routines + which affect windows are used. If it is not, the program + will core dump as soon as either curscr or stdscr are + referenced. However, it is usually best to wait to call it + until after you are sure you will need it, like after + checking for startup errors. Terminal status changing + routines like nl() and cbreak() should be called after + initscr(). + Now that the screen windows have been allocated, you + can set them up for the run. If you want to, say, allow the + window to scroll, use scrollok(). If you want the cursor to + be left after the last change, use leaveok(). If this isn't + done, refresh() will move the cursor to the window's current + (y, x) coordinates after updating it. New windows of your + own can be created, too, by using the functions newwin(), + derwin(), and subwin(). delwin() will allow you to get rid + of old windows. + + 4.2. Output + + Now that we have set things up, we will want to actu- + ally update the terminal. The basic functions used to + change what will go on a window are addch() and move(). + addch() adds a character at the current (y, x) coordinates, + returning ERR if it would cause the window to illegally + scroll, i.e., printing a character in the lower right-hand + corner of a terminal which automatically scrolls if + scrolling is not allowed. move() changes the current (y, x) + coordinates to whatever you want them to be. It returns ERR + if you try to move off the window. As mentioned above, you + can combine the two into mvaddch() to do both things at + once. + The other output functions, such as addstr() and + printw(), all call addch() to add characters to the window. + After you have put on the window what you want there, + when you want the portion of the terminal covered by the + window to be made to look like it, you must call refresh(). + In order to optimize finding changes, refresh() assumes that + any part of the window not changed since the last refresh() + of that window has not been changed on the terminal, i.e., + that you have not refreshed a portion of the terminal with + an overlapping window. If this is not the case, the routine + touchwin() is provided to make it look like the entire win- + dow has been changed, thus making refresh() check the whole + subsection of the terminal for changes. + If you call wrefresh() with curscr(), it will make the + screen look like curscr thinks it looks like. This is use- + ful for implementing a command which would redraw the screen + in case it get messed up. + + 4.3. Input + + Input is essentially a mirror image of output. The + complementary function to addch() is getch() which, if echo + is set, will call addch() to echo the character. Since the + screen package needs to know what is on the terminal at all + times, if characters are to be echoed, the tty must be in + raw or cbreak mode. Since initially the terminal has echo- + ing enable and is in nocreak mode, one or the other has to + changed before calling getch(). The result of not doing this + is unpredictable output. + + 4.4. Miscellaneous + + A plethora of other functions exist for maintaining and + changing information about the windows. For the most part, + the descriptions in section 5 should suffice. + + 4.5. Finishing Up + + In order to do certain optimizations, and, on some ter- + minals, to work at all, some things must be done before the + screen routines start up. In order to clean up after the + routines, the routine endwin() is provided. It restores tty + modes to what they were when initscr() was first called, + moves the cursor down to the lower-left corner, etc. Thus, + anytime after the call to initscr, endwin() should be called + before exiting. + + 5. Descriptions of the Functions + + This section describes all the functions available to the + programmer in the curses package. For an alphabetical list, + see the manual page ncurses(3). + + 5.1. Initialization + + These functions are called when initializing a program. + + initscr() + The first function called should always be initscr. This + will determine the terminal type and initialize curses data + structures. initscr also arranges that the first call to + refresh will clear the screen. If an error occurs a message + is writen to standard error and the program exits. Otherwise + it returns a pointer to stdscr. Some function may be called + before initscr (slk_init, filter, ripofflines, use_env, and + if you are using multiple terminals newterm.) + + endwin() + A program should always call endwin before exiting or + shelling out of the program. This function will restore tty + modes, move the cursor to the lower left corner of the + screen, reset the terminal into the proper nonvisual mode. + Calling refresh() or doupdate() after a temporary escape + from the program will restore the screen to its original + status. + + newterm(type, ofp, ifp) + A program which outputs to more than one terminal should use + newterm instead of initscr. 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. The + arguments are the type of the terminal (a string) and FILE + pointers for the output and input of the terminal. If type + is NULL then the environment variable $TERM is used. endwin + must called for each terminal opened using this function. + + set_term(new) + This function is used to switch to a different terminal. + The screen reference for the new terminal is passed as the + parameter. The previous terminal is returned by the func- + tion. All other calls affect only the current terminal. + + delscreen(sp) + + longname() + This function returns a pointer to a static area containing + a verbose description of the current terminal. It is defined + only after a call to initscr or newterm. + + termattrs() + + termname() + + 5.2. Option Setting + + These functions set options within curses. In each case, + win is the window affected, and bf is a boolean flag with + value TRUE or FALSE indicating whether to enable or disable + the option. All options are initially FALSE. It is not + necessary to turn these options off before calling endwin. + + clearok(win,bf) + If set, the next call to wrefresh with this window will + clear the screen and redraw the entire screen. If win is + curscr, the next call to wrefresh with any window will cause + the screen to be cleared. This is useful when the contents + of the screen are uncertain, or in some cases for a more + pleasing visual effect. + + idlok(win,bf) + If enabled, curses will consider using the hardware + insert/delete line feature of terminals so equipped. If + disabled, curses will not use this feature. Enable this + option only if your application needs insert/delete line, + for example, for a screen editor. It is disabled by default + because insert/delete line is visually annoying when used in + applications where it isn't really needed. + + idcok(win,bf) + This option allows curses will use inset/delete character + capabilities if any are defined. This option is on be + default. + + immedok(win,bf) + If this option is enabled any change in the window's image + causes a call to wrefresh. Enabling this option can degrade + performance; it is disabled by default. + + keypad(win,bf) + This option enables the keypad of the users terminal. If + enabled, the user can press a function key (such as an arrow + key) and getch will return a single value representing the + function key. If disabled, curses will not treat function + keys specially. If the keypad in the terminal can be turned + on (made to transmit) and off (made to work locally), turn- + ing on this option will turn on the terminal keypad. All the + possible function keys are defined in ncurses.h as KEY_*. + + leaveok(win,bf) + Normally, the hardware cursor is left at the location of the + window cursor being refreshed. This option allows the cur- + sor to be left wherever the update happens to leave it. It + is useful for applications where the cursor is not used, + since it saves cursor motions. If possible, the cursor is + made invisible when this option is enabled. + + meta(win,bf) + If enabled, characters returned by getch are transmitted + with all 8 bits, instead of stripping the highest bit. It + is useful for extending the non-text command set in applica- + tions where the terminal has a meta shift key, such as + EMACS. NOTE: This function is currently unsupported. + + notimeout(win,bf) + This option controls whether a timer is set when wgetch is + trying to interpret an input sequence. See keypad. + + scrollok(win,bf) + This option controls what happens when the cursor of a win- + dow is moved off the edge of the window, either from a new- + line on the bottom line, or typing the last character of the + last line. If disabled, the cursor is left on the bottom + line. If enabled, wrefresh is called on the window, and then + the physical terminal and window are scrolled up one line. + + setscrreg(t,b) + wsetscrreg(win,t,b) + These functions allow the user to set a software scrolling + region in a window win or stdscr. t and b are the line num- + bers of the top and bottom margin of the scrolling region. + (Line 0 is the top line of the screen.) If this option and + scrollok are enabled, an attempt to move off the bottom mar- + gin line will cause all lines in the scrolling region to + scroll up one line. Note that this has nothing to do with + use of a physical scrolling region capability in the termi- + nal, like that in the VT100. Only the text of the window is + scrolled. + The scrolling region really acts as a sort of barrier, lim- + iting the area of a window over which changes take place. + For this reason, an attempt to create a scrolling region in + an area of the screen which does not contain the current (y, + x) coordinates for that window is an error. Similarly, + attempts to move the (y, x) coordinates out of the region + will also fail with an ERR return. + When a scrolling region is in place, all changes are limited + to the region. For example, erase() will only erase the + area inside the region; insertln() will only shift lines + down to the bottom of the region, etc. It is anticipated + that this method of controlling the area of change will + prove quite handy in a number of applications. + To disable the scrolling region, once defined, simply rede- + fine it to be the whole window. For example, to disable the + scrolling region on stdscr, the following call would be + used: + setscrreg(0, LINES - 1) + For other windows, the height of the window should be used + instead of (LINES - 1). + + 5.3. Terminal Mode Setting + + These functions are used to set modes in the tty driver. The + initial mode usually depends on the setting when the program + was called: the initial modes documented here represenet the + normal situation. + + cbreak() + nocbreak() + crmode() + nocrmode() + These functions put the terminal into and out of CBREAK + mode. In this mode, characters typed by the user are immedi- + ately available to the program. When out of this mode, the + device driver will buffer characters typed until newline is + typed. Interrupt and flow control characters are unaffected + by this mode. Initially the terminal is not in CBREAK mode. + Most interactive programs using curses will set this mode. + The functions crmode() and nocrmode() are the result of an + accident in the first version of curses and are retained + solely for upward compatibility. crmode() is the same as + cbreak() and nocrmode() is the same as nocbreak(). See 4.3 + for a important note on using these functions. + + raw() + noraw() + These functions put the terminal into and out of RAW mode. + RAW mode is just like CBREAK mode except that no special + character processing is done (e.g. the interrupt character + will be passed through to the program, uninterpreted, as + will the kill character, etc.) and all 8 bits of the input + character are retained; in CBREAK mode, the eighth bit is + stripped off before it is given to the program. Because of + the lack of interpretation of special characters, it is not + recommended that programs use this mode. + + echo() + noecho() + These functions control whether characters typed by the user + are echoed as typed. Initially, characters typed are echoed + by the teletype driver. Authors of most interactive pro- + grams prefer to do their own echoing in a controlled area of + the screen, or not to echo at all, so they disable echoing. + + halfdelay(t) + This options is similar to cbreak mode except that if after + blocking for t tenth of a seconds no input is received ERR + is returned. t must between 1 and 255. Use nocbreak to leave + this mode. + + nodelay(win,bf) + This option causes getch to be a non-blocking call. If no + input is ready, getch will return ERR. If disabled, getch + will hang until a key is pressed. + + timeout(t) + wtimeout(win,t) + These functions offer control over the blocking action of a + read. If t is negative, reading will block until there is + input. If t is zero, no blocking will occur, read returns + ERR if no input is available. If t is posistive, the read + will block for t milliseconds and return ERR if there is + still no input. + These routines offer better and finer control than nodelay() + and halfdelay() and their use is recommended. + + nl() + nonl() + These functions control whether newline is translated into + carriage return and linefeed on output, and whether return + is translated into newline on input. Initially, the trans- + lations do occur. By disabling these translations, curses + is able to make better use of the linefeed capability, + resulting in faster cursor motion. + + savetty() + resetty() + These functions save and restore the state of the tty modes. + savetty saves the current state in a buffer, resetty + restores the state to what it was at the last call to save- + tty. + + 5.4. Window Manipulation + + newwin(num_lines, num_cols, begy, begx) + Create a new window with the given number of lines and + columns. The upper left corner of the window is at line + begy column begx. If either num_lines or num_cols is zero, + they will be defaulted to LINES-begy and COLS-begx. A new + full-screen window is created by calling newwin(0,0,0,0). + + subwin(orig, num_lines, num_cols, begy, begx) + Create a new window with the given number of lines and + columns. The window is at position (begy, begx) on the + screen. (It is relative to the screen, not orig.) The win- + dow is made in the middle of the window orig, so that + changes made to one window will affect both windows. When + using this function, often it will be necessary to call + touchwin before calling wrefresh. + + derwin(orig, num_lines, num_cols, begy, begx) + Is similar to subwin only the new window is created relative + to the original window, not the screen. + + delwin(win) + Deletes the named window, freeing up all memory associated + with it. In the case of sub-windows, they should be deleted + before the main window. + + dupwin(win) + + mvderwin(win,y,x) + + syncok(win,bf) + wsyncup(win) + wcursyncup(win) + wsyncdown(win) + + mvwin(win, by, bx) + Move the window so that the upper left corner will be at + position (by, bx). If the move would cause the window to be + off the screen, it is an error and the window is not moved. + + touchline(win,start,count) + touchwin(win) + Throw away all optimization information about which parts of + the window have been touched, by pretending the entire win- + dow has been drawn on. This is sometimes necessary when + using overlapping windows, since a change to one window will + affect the other window, but the optimization records of the + other window will not reflect the change. + + wtouchln(win,y,n,changed) + Throw away optimization information, or mark as unchanged, + n lines starting at y, depending on the value of changed. + + untouchwin(win) + Mark the whole window as unchcnged since the lat wrefresh. + + is_linetouched(win,line) + is_wintouched(win) + These routines are used to check if the given line/window + has been modified since the last wrefresh. They will return + TRUE is that is the case, FALSE otherwise. is_linetouched + will return ERR if there is no such line. + + overlay(win1, win2) + overwrite(win1, win2) + These functions overlay win1 on top of win2, that is, all + text in win1 is copied into win2, after lining up the two + windows' origins. The difference between the functions is + that overlay is nondestructive (blanks are not copied) while + overwrite is destructive. + + copywin(win,win,sminrow,smincol,dminrow,dmincol,dmaxrow, + dmaxcol,overlay) + Low level function used to implement overlay/overwrite. + + 5.5. Causing Output to the Terminal + + refresh() + wrefresh(win) + These functions must be called to actually get any output on + the terminal, as other routines merely manipulate data + structures. wrefresh copies the named window to the physi- + cal terminal screen, taking into account what is already + there in order to do optimizations. refresh is the same, + using stdscr as a default screen. Unless leaveok has been + enabled, the physical cursor of the terminal is left at the + location of the window's cursor. + + doupdate() + wnoutrefresh(win) + These two functions allow multiple updates with more effi- + ciency than wrefresh. To use them, it is important to + understand how curses works. In addition to all the window + structures, curses keeps two data structures representing + the terminal screen: a physical screen, describing what is + actually on the screen, and a virtual screen, describing + what the programmer wants to have on the screen. wrefresh + works by first copying the named window to the virtual + screen (wnoutrefresh), and then calling the routine to + update the screen (doupdate). If the programmer wishes to + output several windows at once, a series of calls to wre- + fresh will result in alternating calls to wnoutrefresh and + doupdate, causing several bursts of output to the screen. + By calling wnoutrefresh for each window, it is then possible + to call doupdate once, resulting in only one burst of out- + put, with probably fewer total characters transmitted. + + redrawwin(win) + wredrawln(win,start,count) + + 5.6. Writing on Window Structures + + These routines are used to ``draw'' text on windows. In all + cases, a missing win is taken to be stdscr. y and x are the + row and column, respectively. The upper left corner is + always (0, 0) not (1, 1). The mv functions imply a call to + move before the call to the other function. + + 5.6.1. Moving the Cursor + + move(y, x) + wmove(win, y, x) + The cursor associated with the window is moved to the given + location. This does not move the physical cursor of the + terminal until refresh is called. + + 5.6.2. Writing One Character + + addch(ch) + waddch(win, ch) + mvaddch(y, x, ch) + mvwaddch(win, y, x, ch) + The character ch is put in the window at the current cursor + position of the window. If ch is a tab, newline, or + backspace, the cursor will be moved appropriately in the + window. If ch is a different control character, it will be + drawn in the ^X notation. The position of the window cursor + is advanced. At the right margin, an automatic newline is + performed. At the bottom of the scrolling region, if scrol- + lok is enabled, the scrolling region will be scrolled up one + line. + + 5.6.3. Writing a String + + addstr(str) + addnstr(str,n) + waddstr(win,str) + waddnstr(win,str,n) + mvaddstr(y,x,str) + mvaddnstr(y,x,str,n) + mvwaddstr(win,y,x,str) + mvwaddnstr(win,y,x,str,n) + These functions write all the characters of the null termi- + nated character string str on the given window. They are + identical to a series of calls to addch. Routines with 'n' + write n characters of str. If n is -1 then the entire string + is written. + + addchstr(chstr) + addchnstr(chstr,n) + waddchstr(win,chstr) + waddchnstr(win,chstr,n) + mvaddchstr(y,x,chstr) + mvaddchnstr(y,x,chstr,n) + mvwaddchstr(win,y,x,chstr) + mvwaddchnstr(win,y,x,chstr,n) + These functions copy chstr onto the window image starting at + the current cursor position. Routines with 'n' write at most + n characters of chstr (as many as will fit on the line). If + n is -1 then the entire string is written. The cursor is not + advanced and no checking for control characters is done. + These routines are faster than the addstr() group. chstr is + a pointer to an array of chtype. + + 5.6.4. Clearing Areas of the Screen + + erase() + werase(win) + These functions copy blanks to every position in the window. + + clear() + wclear(win) + These functions are like erase and werase but they also call + clearok, arranging that the screen will be cleared on the + next refresh. The result can visually annoying. + + clrtobot() + wclrtobot(win) + All lines below the cursor in this window are erased. Also, + the current line to the right of the cursor is erased. + + clrtoeol() + wclrtoeol(win) + The current line to the right of the cursor is erased. + + 5.6.5. Inserting and Deleting Text + + delch() + wdelch(win) + mvdelch(y,x) + mvwdelch(win,y,x) + The character under the cursor in the window is deleted. + All characters to the right on the same line are moved to + the left one position. This does not imply use of the hard- + ware delete character feature. + + deleteln() + wdeleteln(win) + The line under the cursor in the window is deleted. All + lines below the current line are moved up one line. The + bottom line of the window is cleared. This does not imply + use of the hardware delete line feature. + + insch(c) + winsch(win, c) + mvinsch(y,x,c) + mvwinsch(win,y,x,c) + The character c is inserted before the character under the + cursor. All characters to the right are moved one space to + the right, possibly losing the rightmost character on the + line. This does not imply use of the hardware insert char- + acter feature. + + insertln() + winsertln(win) + A blank line is inserted above the current line. The bottom + line is lost. This does not imply use of the hardware + insert line feature. + + 5.6.6. Formatted Output + + printw(fmt, ...) + wprintw(win, fmt, ...) + mvprintw(y, x, fmt, ...) + mvwprintw(win, y, x, fmt, ...) + vwprintw(win, fmt, va_list) + These functions correspond to printf. The characters which + would be output by printf are instead output using waddch on + the given window. vwprintw() acts like vprintf(). + + 5.6.7. Line drawing + + Borders are drawn inside a window and not around it. + + border(ls, rs, ts, bs, tl, tr, bl, br) + wborder(win, ls, rs, ts, bs, tl, tr, bl, br) + box(win, vert, hor) + A border is drawn around the edges of the window. ls, rs, + ts, bs, tl, tr, bl, and br are the character and attribute + to draw the left side, right side, top side, bottom side, + top left, top right, bottom left, and bottom right respec- + tively. + If any of these are 0, the follwing defaults are used: + ACS_VLINE. ACS_VLINE, ACS_HLINE, ACS_HLINE, ACS_ULCORNER, + ACS_URCORNER, ACS_LLCORNER, ACS_LRCORNER. box is shorthand + for wborder(win, vert, vert, hor, hor, 0, 0, 0, 0). + + vline(ch,n) + wvline(win,ch,n) + These functions draw a vertical line starting at the current + cursor position using ch for n characters or as many as will + fit on the window. The cursor position is not advanced. + + hline(ch,n) + whline(win,ch,n) + These functions draw a horizontal line starting at the + current cursor position using ch for n characters or as many + as will fit on the window. The cursor position is not + advanced. + + 5.6.8 Scrolling + + Scrolling only works if enabled via scrollok(). The cursor + position is unchanged by these functions. As an optimization + the physical screen is scrolled if the window in question is + covering the entire screen. + + scroll(win) + The window is scrolled up one line. This involves moving + the lines in the window data structure. + + scrl(n) + wscrl(win,n) + These functions scroll thw window up/down n lines depending + on the sign on n (+ for up, - for down). + + 5.7. Querying the Contents of a Window + + getyx(win,y,x) + The cursor position of the window is placed in the two + integer variables y and x. Since this is a macro, no & is + necessary. + + inch() + winch(win) + mvinch(y,x) + mvwinch(win,y,x) + The character at the current position in the named window is + returned. + + 5.8. Input from the Terminal + + getch() + wgetch(win) + mvgetch(y,x) + mvwgetch(win,y,x) + A character is read from the terminal associated with the + window. In nodelay mode, if there is no input waiting, the + value -1 is returned. In delay mode, the program will hang + until a character is typed. + + If keypad mode is enabled, and a function key is pressed, + the code for that function key will be returned instead of + the raw characters. Possible function keys are defined with + integers beginning with 0401, whose names begin with KEY_, + defined in <ncurses.h>. If a character is received that + could be the beginning of a function key (such as escape), + curses will set a one second timer. If the remainder of the + sequence does not come in within one second, the character + will be passed through, otherwise the function key value + will be returned. For this reason, on many terminals, there + will be a one second delay after a user presses the escape + key. (Use by a programmer of the escape key for a single + character function is discouraged.) The one second delay can + be turned off using the notimeout() function. + + getstr(str) + wgetstr(win,str) + mvgetstr(y,x,str) + mvwgetstr(win,y,x,str) + A series of calls to getch is made, until a newline is + received. The resulting value is placed in the area pointed + at by the character pointer str. The users erase and kill + characters are interpreted, and the string is echoed. + + scanw(fmt, ...) + wscanw(win, fmt, ...) + mvscanw(y, x, fmt, ...) + mvwscanw(win, y, x, fmt, ...) + vwscanw(win,fmt,va_list) + These functions corresponds to scanf. wgetstr is called on + the window, and the resulting line is used as input for the + scan. + + 5.9. Video Attributes + + attroff(at) + wattroff(win, attrs) + attron(at) + wattron(win, attrs) + attrset(at) + wattrset(win, attrs) + standout() + standend() + wstandout(win) + wstandend(win) + These functions set the current attributes of the named win- + dow. These attributes can be any combination of A_STANDOUT, + A_REVERSE, A_BOLD, A_DIM, A_BLINK, A_BLANK, A_UNDERLINE, + A_PROTECT, A_INVIS, and A_ALTCHARSET. These constants are + defined in <ncurses.h> and can be combined with the C | (or) + operator. The current attributes of a window are applied to + all characters that are written into the window. Attributes + are a property of the character, and move with the char- + acter through any scrolling and insert/delete line/character + operations. To the extent possible on the particular + terminal, they will be displayed as the graphic rendition + of characters put on the screen. + attrset(at) sets the current attributes of the given window + to at. attroff(at) turns off the named attributes without + affecting any other attributes. attron(at) turns on the + named attributes without affecting any others. standout is + the same as attrset(A_STANDOUT), standend is the same as + attrset(0), that is, it turns off all attributes. + + 5.10. Color Manipulation + + Ncurses provides support for the use of color on terminals + that are capable of display it. Note the BSD and older SYSV + curses don't support color. Color support in the PC version + is not compatible with SYSR4. + + has_colors() + this function returns TRUE if the terminal supports color, + FALSE otherwise. Other color handling funtions will return + ERR if has_colors() is FALSE. You should always check before + using color and use other video attributes to replace color. + + can_change_color() + This function returns TRUE if the terminal is capable of + redefining colors using the init_color function, FALSE if it + can't. Don't use init_color and color_content if it returns + FALSE. + + start_color() + This function must be called before any other color handling + function is called. It initializes the 8 basic colors (see + appendix I) and sets the global variables COLORS and COLOR_ + PAIRS to the maximum number of colors and color-pairs a + terminal can handle. + + init_pair(pair, fg, bg) + This function changes the definition of a color-pair, pair. + Each pair has a foregroung color fg, and a background color + bg. Both values must be between 0 and COLORS-1. pair must be + between 1 and COLOR_PAIRS-1. + [If a pair is changed from a previous definition, the screen + is refreshed and all occurances of the color-pair are + changed to reflect the change.] + + pair_content(pair, f, b) + This function stores the foreground and background colors of + the color-pair pair into the variables pointed to by f, b. + pair should be between 1 and COLOR_PAIRS-1. + + init_color(color, r, g, b) + This function changes the value of a given color. A color is + defined by its red, green, and blue components, r, g, and b. + These values must be between 0 and 1000. color should be + between 0 and COLORS-1. + + color_content(color, r, g, b) + This function puts the red, green, and blue components of + color into the variable pointed to by r, g, b respectively. + color should be between 0 and COLORS-1. + + 5.11. Pads + + 5.12. Soft Labels + + 5.13. Bells and Flashing Lights + + beep() + flash() + These functions are used to signal the programmer. beep + will sound the audible alarm on the terminal, if possible, + and if not, will flash the screen (visible bell), if that is + possible. flash will flash the screen, and if that is not + possible, will sound the audible signal. If neither signal + is possible, nothing will happen. Nearly all terminals have + an audible signal (bell or beep) but only some can flash the + screen. + + 5.14. Portability Functions + + These functions do not have anything to do with terminal + dependent character output, but tend to be needed by pro- + grams that use curses. Unfortunately, their implemention + varies from one version of UNIX* to another. They have been + included here to enhance the portability of programs using + curses. + + baudrate() + baudrate returns the output speed of the terminal. The num- + ber returned is the integer baud rate, for example, 9600, + rather than a table index such as B9600. + + erasechar() + The erase character chosen by the user is returned. This is + the character typed by the user to erase the character just + typed. + + killchar() + The line kill character chosen by the user is returned. + This is the character typed by the user to forget the entire + line being typed. + + flushinp() + flushinp throws away any typeahead that has been typed by + the user and has not yet been read by the program. + + 5.15. Debugging + + These functions are useful when debugging a program with + curses. + + unctrl(ch) + This macro expands to a character string which is a print- + able representation of the character ch. The program must + include the file <unctrl.h>. Control characters are dis- + played in the ^x notation. Printing characters are displayed + as is. + + traceoff() + traceon() + It is possible to compile a debugging version of curses with + tracing turned on, and with the -g option for gdb. This + library may be available on your system as -ldcurses. When + using this version, the file ``trace'' will be created each + time the program is run, containing verbose information + showing each step done by curses. This output is useful for + finding bugs in curses, and may be useful for finding bugs + in user programs. Since the output is so verbose, with any + bug that cannot be easily and quickly reproduced, it may be + necessary to turn the debugging output off in some parts of + the program. These functions can be used to turn tracing + off and back on. When initscr is first called, tracing is + automatically turned on. + You should use -DTRACE when compiling programs that use + tracing. + + _tracef() + This function can be used to output your own debugging info- + rmation. It is only available only if you compile with the + -DTRACE flag and linking with -ldcurses. It can be used the + same way as printf, only it outputs a newline after the end + of arguments. + + 6. Lower Level Functions + + These functions are provided for programs not needing the + screen optimization capabilities of curses. Programs are + discouraged from working at this level, since they must han- + dle various glitches in certain terminals. However, a pro- + gram can be smaller if it only brings in the low level rou- + tines. + + gettmode() + setterm(type) + These two initialization routines are provided for upward + compatibility with the old curses. gettmode does nothing. + setterm results in a call to setupterm with appropriate + arguments. + + def_prog_mode() + def_shell_mode() + These functions define "program" mode and "shell" mode. The + first describes the status of a terminal while in curses, + the second the status outside curses. + + reset_prog_mode() + reset_shell_mode() + These functions restore a terminal to "program" mode after + shelling out, or to "shell" mode before shelling out. + + fixterm() + resetterm() + These functions are obselete and have been replaced by + reset_prog_mode() and reset_prog_mode() respectively. + + saveterm() + This fucntion is obselete and is replaced by + def_prog_mode(). + + mvcur(oldrow, oldcol, newrow, newcol) + This routine optimally moves the cursor from (oldrow, old- + col) to (newrow, newcol). The user program is expected to + keep track of the current cursor position. Note that unless + a full screen image is kept, curses will have to make pes- + simistic assumptions, sometimes resulting in less than opti- + mal cursor motion. For example, moving the cursor a few + spaces to the right can be done by transmitting the charac- + ters being moved over, but if curses does not have access to + the screen image, it doesn't know what these characters are. + If either of oldcol or oldrow are negative, mvcur() will + refrain from using any relative motions. This is handy for + occasions when a program is unsure as to the current cursor + location. + + 7. Terminfo Level + + These routines are called by low level programs that need + access to specific capabilities of terminfo. A program + working at this level should include both <ncurses.h> and + <term.h>. After a call to setupterm, the capabilities will + be available with macro names defined in <term.h>. See ter- + minfo(5) for a detailed description of the capabilies. If + the program only needs to handle one terminal, the defini- + tion -DSINGLE can be passed to the C compiler, resulting in + static references to capabilities instead of dynamic refer- + ences. This can result in smaller code, but prevents use of + more than one terminal at a time. Very few programs use + more than one terminal, so almost all programs can use this + flag. + + setupterm(term, filenum, errret) + This routine is called to initialize a terminal. term is + the character string representing the name of the terminal + being used. filenum is the UNIX file descriptor of the ter- + minal being used for output. errret is a pointer to an + integer, in which a success or failure indication is + returned. The values returned can be 1 (all is well), 0 (no + such terminal), or -1 (some problem locating the terminfo + database). + The value of term can be given as 0, which will cause the + value of TERM in the environment to be used. The errret + pointer can also be given as 0, meaning no error code is + wanted. If errret is defaulted, and something goes wrong, + setupterm will print an appropriate error message and exit, + rather than returning. Thus, a simple program can call + setupterm(0, 1, 0) and not worry about initialization + errors. + setupterm will check the tty driver mode bits, and change + any that might prevent the correct operation of other low + level routines. Currently, the mode that expands tabs into + spaces is disabled, because the tab character is sometimes + used for different functions by different terminals. (Some + terminals use it to move right one space. Others use it to + address the cursor to row or column 9.) If the system is + expanding tabs, setupterm will remove the definition of the + tab and backtab functions, assuming that since the user is + not using hardware tabs, they may not be properly set in the + terminal. + After the call to setupterm, the global variable cur_term is + set to point to the current structure of terminal capabili- + ties. By calling setupterm for each terminal, and saving + and restoring cur_term, it is possible for a program to use + two or more terminals at once. Setupterm also stores the + names section of the terminal description in the global + character array ttytype[]. Subsequent calls to setupterm + will overwrite this array, so you'll have to save it your- + self if need be. + The mode that turns newlines into CRLF on output is not dis- + abled. Programs that use cud1 or ind should avoid these + capabilities if their value is linefeed unless they disable + this mode. setupterm calls fixterm after any changes it + makes. + + vidattr(newmode) + vidputs(newmode, outc) + newmode is any combination of attributes, defined in + <ncurses.h>. The proper string to put the terminal in the + given video mode is output. The routine vidattr() sends the + output characters to putchar; vidputs sends them to the + given routine outc, one character at a time. That routine + should therefore expect one char parameter. The previous + mode is remembered by this routine. + + tparm(instring, p1, p2, p3, p4, p5, p6, p7, p8, p9) + tparm is used to instantiate a parameterized string. The + character string returned is suitable for tputs. Up to 9 + parameters can be passed, in addition to the parameterized + string. + + tputs(cp, affcnt, outc) + A string capability, possibly containing padding informa- + tion, is processed. Enough padding characters to delay for + the specified time replace the padding specification, and + the resulting string is passed, one character at a time, to + the routine outc, which should expect one character parame- + ter. (This routine often just calls putchar.) cp is the + capability string. affcnt is the number of units affected + by the capability, which varies with the particular capabil- + ity. (For example, the affcnt for insert_line is the number + of lines below the inserted line on the screen, that is, the + number of lines that will have to be moved by the terminal.) + affcnt is used by the padding information of some terminals + as a multiplication factor. If the capability does not have + a factor, the value 1 should be passed. + + putp(str) + This is a convenient function to output a capability with no + affcnt. The string is output to putchar with an affcnt of + 1. It can be used in simple applications that do not need + to process the output of tputs. + + + 8. Termcap Emulation + + Appendix I: Attributes + ---------------------- + + Attributes are used with wattron(), wattroff(), wattrset(), + or or'ed with the character passed to waddch(). They are + defined in <ncurses.h> + + A_ATTRIBUTES mask chtype for attributes + A_NORMAL reset all attributes + A_STANDOUT best highlighting mode + A_UNDERLINE underline + A_REVERSE reverse video, background and foreground reversed + A_BLINK blinking + A_DIM dim or half bright + A_BOLD bold or extra bright + A_ALTCHARSET use alternate character set + A_INVIS invisible, background same as foreground + A_PROTECT I haven't a clue + A_CHARTEXT mask chtype for actual character + A_COLOR mask for color + COLOR_PAIR(n) set color-pair to that stored in n + PAIR_NUMBER(a) get color-pair stored in attribute a + + + Appendix II: COLORS + ------------------- + + Colors are defined in <ncurses.h> are used with init_pair(). + + COLOR_BLACK 0 + COLOR_RED 1 + COLOR_GREEN 2 + COLOR_YELLOW 3 + COLOR_BLUE 4 + COLOR_MAGENTA 5 + COLOR_CYAN 6 + COLOR_WHITE 7 + + Appendix III: Alternative character sets + ---------------------------------------- + + ACS variables are used to add line-drawing capability to + ncurses on terminals that support it. When defined for a + given terminal (using acs) the A_ALTCHARSET attribute is + set for that variable, otherwise the default value is + used. + + ACS_ULCORNER + + ACS_LLCORNER + + ACS_URCORNER + + ACS_LRCORNER + + ACS_RTEE + + ACS_LTEE + + ACS_BTEE + + ACS_TTEE + + ACS_HLINE - + ACS_VLINE | + ACS_PLUS + + ACS_S1 ~ /* scan line 1 */ + ACS_S9 _ /* scan line 9 */ + ACS_DIAMOND + /* diamond */ + ACS_CKBOARD : /* checker board (stipple) */ + ACS_DEGREE ' /* degree symbol */ + ACS_PLMINUS # /* plus/minus */ + ACS_BULLET 0 /* bullet */ + ACS_LARROW < /* arrow pointing left */ + ACS_RARROW > /* arrow pointing right */ + ACS_DARROW v /* arrow pointing down */ + ACS_UARROW ^ /* arrow pointing up */ + ACS_BOARD # /* board of squares */ + ACS_LANTERN # /* lantern symbol */ + ACS_BLOCK # /* solid square block */ + + + Appendix IV: Function keys, their codes, and their definition + ------------------------------------------------------------- + + Function keys can return their respective codes if keypad() + is enabled and they are defined in the terminal's terminfo + description (assuming the terminal transmits unique sequences + for the key. They are defined in <ncurses.h> + + KEY_BREAK 0401 /* break key (unreliable) */ + KEY_DOWN 0402 /* The four arrow keys ... */ + KEY_UP 0403 + KEY_LEFT 0404 + KEY_RIGHT 0405 /* ... */ + KEY_HOME 0406 /* Home key (upward+left arrow) */ + KEY_BACKSPACE 0407 /* backspace (unreliable) */ + KEY_F0 0410 /* Function keys. Space for 64 */ + KEY_F(n) (KEY_F0+(n)) /* keys is reserved. */ + KEY_DL 0510 /* Delete line */ + KEY_IL 0511 /* Insert line */ + KEY_DC 0512 /* Delete character */ + KEY_IC 0513 /* Insert char or enter insert mode */ + KEY_EIC 0514 /* Exit insert char mode */ + KEY_CLEAR 0515 /* Clear screen */ + KEY_EOS 0516 /* Clear to end of screen */ + KEY_EOL 0517 /* Clear to end of line */ + KEY_SF 0520 /* Scroll 1 line forward */ + KEY_SR 0521 /* Scroll 1 line backwards (reverse) */ + KEY_NPAGE 0522 /* Next page */ + KEY_PPAGE 0523 /* Previous page */ + KEY_STAB 0524 /* Set tab */ + KEY_CTAB 0525 /* Clear tab */ + KEY_CATAB 0526 /* Clear all tabs */ + KEY_ENTER 0527 /* Enter or send (unreliable) */ + KEY_SRESET 0530 /* soft (partial) reset (unreliable) */ + KEY_RESET 0531 /* reset or hard reset (unreliable) */ + KEY_PRINT 0532 /* print or copy */ + KEY_LL 0533 /* home down or bottom (lower left) */ + + /* The keypad is arranged like this: */ + /* a1 up a3 */ + /* left b2 right */ + /* c1 down c3 */ + + KEY_A1 0534 /* Upper left of keypad */ + KEY_A3 0535 /* Upper right of keypad */ + KEY_B2 0536 /* Center of keypad */ + KEY_C1 0537 /* Lower left of keypad */ + KEY_C3 0540 /* Lower right of keypad */ + KEY_BTAB 0541 /* Back tab key */ + KEY_BEG 0542 /* beg(inning) key */ + KEY_CANCEL 0543 /* cancel key */ + KEY_CLOSE 0544 /* close key */ + KEY_COMMAND 0545 /* cmd (command) key */ + KEY_COPY 0546 /* copy key */ + KEY_CREATE 0547 /* create key */ + KEY_END 0550 /* end key */ + KEY_EXIT 0551 /* exit key */ + KEY_FIND 0552 /* find key */ + KEY_HELP 0553 /* help key */ + KEY_MARK 0554 /* mark key */ + KEY_MESSAGE 0555 /* message key */ + KEY_MOVE 0556 /* move key */ + KEY_NEXT 0557 /* next object key */ + KEY_OPEN 0560 /* open key */ + KEY_OPTIONS 0561 /* options key */ + KEY_PREVIOUS 0562 /* previous object key */ + KEY_REDO 0563 /* redo key */ + KEY_REFERENCE 0564 /* ref(erence) key */ + KEY_REFRESH 0565 /* refresh key */ + KEY_REPLACE 0566 /* replace key */ + KEY_RESTART 0567 /* restart key */ + KEY_RESUME 0570 /* resume key */ + KEY_SAVE 0571 /* save key */ + KEY_SBEG 0572 /* shifted beginning key */ + KEY_SCANCEL 0573 /* shifted cancel key */ + KEY_SCOMMAND 0574 /* shifted command key */ + KEY_SCOPY 0575 /* shifted copy key */ + KEY_SCREATE 0576 /* shifted create key */ + KEY_SDC 0577 /* shifted delete char key */ + KEY_SDL 0600 /* shifted delete line key */ + KEY_SELECT 0601 /* select key */ + KEY_SEND 0602 /* shifted end key */ + KEY_SEOL 0603 /* shifted clear line key */ + KEY_SEXIT 0604 /* shifted exit key */ + KEY_SFIND 0605 /* shifted find key */ + KEY_SHELP 0606 /* shifted help key */ + KEY_SHOME 0607 /* shifted home key */ + KEY_SIC 0610 /* shifted input key */ + KEY_SLEFT 0611 /* shifted left arrow key */ + KEY_SMESSAGE 0612 /* shifted message key */ + KEY_SMOVE 0613 /* shifted move key */ + KEY_SNEXT 0614 /* shifted next key */ + KEY_SOPTIONS 0615 /* shifted options key */ + KEY_SPREVIOUS 0616 /* shifted prev key */ + KEY_SPRINT 0617 /* shifted print key */ + KEY_SREDO 0620 /* shifted redo key */ + KEY_SREPLACE 0621 /* shifted replace key */ + KEY_SRIGHT 0622 /* shifted right arrow */ + KEY_SRSUME 0623 /* shifted resume key */ + KEY_SSAVE 0624 /* shifted save key */ + KEY_SSUSPEND 0625 /* shifted suspend key */ + KEY_SUNDO 0626 /* shifted undo key */ + KEY_SUSPEND 0627 /* suspend key */ + KEY_UNDO 0630 /* undo key */ + KEY_MAX 0777 /* Maximum curses key */ + |