summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorache <ache@FreeBSD.org>1995-04-20 21:36:15 +0000
committerache <ache@FreeBSD.org>1995-04-20 21:36:15 +0000
commit38cb38bdc12de8056b42dd987c04f8114036f119 (patch)
tree66f24a593392034fc42488cc688b05f94e79b385
parentf4b86adcb0fffe02c9b00b60f1817b00577c0c0b (diff)
downloadFreeBSD-src-38cb38bdc12de8056b42dd987c04f8114036f119.zip
FreeBSD-src-38cb38bdc12de8056b42dd987c04f8114036f119.tar.gz
Add a bit more docs
-rw-r--r--lib/libncurses/Makefile3
-rw-r--r--lib/libncurses/curs_termin.3190
-rw-r--r--lib/libncurses/doc/color.doc71
-rw-r--r--lib/libncurses/doc/manual.doc1361
-rw-r--r--lib/ncurses/ncurses/Makefile3
5 files changed, 1626 insertions, 2 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 */
+
diff --git a/lib/ncurses/ncurses/Makefile b/lib/ncurses/ncurses/Makefile
index 452666c..ab24ed5 100644
--- a/lib/ncurses/ncurses/Makefile
+++ b/lib/ncurses/ncurses/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 \
OpenPOWER on IntegriCloud