\author{Sven van der Meer}
\date{v0.3, 15 Oct 1994}


\section{\label {vdm} Character Cell Graphics}

\begin{itemize}
\item  {\bf print, printf, fprintf} \\ 
With these functions from {\it libc\/} you have a high level access to the
terminal, mainly for text output.
\item  {\bf termcap} \\ 
The TERMinal CAPabilitie database is a set of terminal description
entries in the ASCII file /etc/termcap.
Here you can find information about how to display special characters,
how to perform operations (delete, insert characters  or lines ...) and how
to initialize a terminal. The database is used i.e. by the editor vi. There
are view library functions to read and use the terminal capabilities (see
termcap(3x)). With these database programs can work with a variety of 
terminals with the same code. Using the termcap database and library
library functions means to have only a low level access to the terminal.
Things as changing attributes
or colors, use parameterized output and optimization must be done by the
programmer himself.
\item  {\bf terminfo database} \\ 
The TERMinal INFOrmation database is based on the termcap database and 
also describes terminal capabilities, but on a higher level then termcap.
Using terminfo the program can easily change screen attributes, 
use special keys such as function keys and more. The database can be found
in {\it /usr/lib/terminfo/[A-z,0-9]*\/}. Every file describes one terminal.
\item  {\bf curses} \\ 
Terminfo is a good base to use for terminal handling in a program, but
it's tricky to use. The CURSES library gives you a high level access to
the terminal and is based on the terminfo database. With curses you can
open and manipulate windows on the screen, you have a complete set of in- and 
output functions, can change video attributes and all this with the same code
on more than 150 terminals. The curses library can be found in 
{\it /usr/lib/libcurses.a\/}.
\item  {\bf ncurses} \\ 
Ncurses in the next improvement. In version 1.8.6 it should be compatible
with AT\&T curses as defined in SYSVR4 and has to offer some extensions,
such as color manipulation, special optimization for output, use terminal
specific optimization  and some more. It is
tested on a lot of systems such as SunOS, HP and Linux. I recommend to
use ncurses instead of one of the three others (termcap, terminfo or curses).

In the following sections I will describe how to use ncurses and termcap
functions to access a terminal. With Linux we have the GNU-version from
termcap and ncurses. When I use features which are not in the normal
termcap or in the BSD-curses (or some older SYSTEM V curses versions) I
will mark them.
\end{itemize}








\newpage
\subsection{The Termcap Library}






\subsubsection{Introduction}

The termcap library is an api to the termcap database which could be
found in {\it  \/}etc/termcap/. With the library programs are able to perform
the following actions:

\begin{itemize}
\item  get a description about the current terminal ({\it  tgetent(...)\/}).
\item  search in this description for information
({\it  tgetnum(...), tgetflag(...), tgetstr(...)\/}).
\item  encoding numeric parameters in the terminal specific form
{\it  tparam(...), tgoto(...)\/}).
\item  computing and performing padding ({\it  tputs(...)\/}).
\end{itemize}


Programs using termcap library must include {\it  termcap.h\/} and should
be linked with:

\begin{tscreen}
\begin{verbatim}
    gcc [flags] files -ltermcap
\end{verbatim}
\end{tscreen}


Termcap functions are terminal independent routines but give the programmer
only a low level access to the terminal. Use curses or ncurses as a higher
level package.








\subsubsection{Find a Terminal Description}

\begin{itemize}
\item {\tt  int tgetent(void *buffer, const char *termtype)} \\ 
On the Linux operating system the current terminal name could be
found in the environment variable {\it  TERM\/}. So {\it  termtype\/} is
the result of a call to {\it  getenv(3)\/}.

For {\it  buffer\/} no memory has to allocated when using the GNU version
of termcap (This is what we can assume under Linux!). Else you have
to allocate 2048 Byte or {\it  buffer\/} (former it needed only 1024 Byte,
but the size has doubled).

{\it  Tgetent(...)\/} returns {\it  1\/} on success, {\it  0\/} when the database
is found but has no entry for TERM and some other value for other errors.

The following example should show how to use {\it  tgetent(...)\/}:

\begin{tscreen}
\begin{verbatim}
    #define buffer 0
    char *termtype=getenv("TERM");
    int ok;

    ok=tgetent(buffer,termtype);
    if(ok==1)
      /* all right, we have the entry */
    else if(ok==0)
     /* uups, something wrong with TERM
      * check termtype first then termcap database
      */
    else
     /* huuu, fatal error */
\end{verbatim}
\end{tscreen}


Termcap use by default {\it /etc/termcap/\/} as database. When you define
the environment variable TERMCAP for instance with {\it \$HOME/mytermcap\/} all functions will {\it  mytermcap\/} instead of {\it /etc/termcap\/}.
With no leading slash in TERMCAP, the defined value is
used as a name for a terminal.
\end{itemize}







\subsubsection{Look at a Terminal Description}

Every information is called a capability. Every capability is a two
letter code. And every two letter code is followed by the value for
the capability.Possible values are:

\begin{itemize}
\item  {\bf  Numeric} for instance {\it  co\/} - number of columns
\item  {\bf  Boolean} or {\bf  Flag} for instance {\it  hc\/} - hardcopy terminal
\item  {\bf  String} for instance {\it  st\/} - set tab stop
\end{itemize}


Every capability is related to always the same value ({\it  co\/} is always
numeric, {\it  hc\/} is always a flag and {\it  st\/} is always a string).

There are three different types of values, so there are also three functions
to interrogate them. {\it  Char *name\/} is the two letter code for the capability.



\begin{itemize}
\item {\tt  int tgetnum(char *name)} \\ 
Get a capability value that is numeric, such as the {\it  co\/}. {\it  Tgetent(...)\/} returns
the numeric value if the capability is available, otherwise {\it  1\/}.
(Note: the returned value is not negative.)
\item {\tt  int tgetflag(char *name)} \\ 
Get a capability value that is boolean (or flag). Returns {\it  0\/} or {\it  1\/}
depending on the boolean value. (if the flag is present {\it  1\/} else {\it  0\/}.)
\item {\tt  char *tgetstr(char *name, char **area)} \\ 
Get a capability value that is a string. Returns a pointer to the string
or {\it  NULL\/} if not present. If {\it  char **area\/} is {\it  NULL\/} termcap
will allocate memory by itself (only in the GNU-version, which is used
under Linux). Termcap will never refer to this pointer again.
This method is preferred, because you don't know how much space is needed
for the pointer, so let termcap do this for you. Don't forget to free your
character pointer before leaving the program.
\end{itemize}









\subsubsection{Terminal Capability Names}



\begin{list}{}{}
\item {\tt ae} {\bf String} to turn off alternate character set mode.
\item {\tt al} {\bf String} to insert a blank line before the cursor.
\item {\tt AL} {\bf String} to insert n blank lines before the cursor.
\item {\tt am} {\bf Flag:} output to last column wraps cursor to next line.
\item {\tt as} {\bf String} to turn on alternate character set mode.like.
\item {\tt bl} {\bf String} to sound the bell.
\item {\tt bt} {\bf String} to move the cursor left to the previous hardware
tab stop column.
\item {\tt bw} {\bf Flag:} {\it le\/} at left margin wraps to end of previous line.
So {\it le\/} can be used to move to the last column in the 
preceding line from column zero.
\item {\tt CC} {\bf String:} change terminal's command character.
The terminal has a settable command character (default ESC).
\item {\tt cd} {\bf String} to clear the line the cursor is on, and following 
lines.
\item {\tt ce} {\bf String} to clear from the cursor to the end of the line.
\item {\tt ch} {\bf String} to position the cursor at column c in the same line.
\item {\tt cl} {\bf String} to clear the entire screen and put cursor at upper 
left corner.
\item {\tt cm} {\bf String:} to move the cursor to line l, column c.
{\it L\/} and {\it c\/} are zero and relative to the screen.
\item {\tt CM} {\bf String} to move the cursor at line l, column c, relative 
to display memory.
\item {\tt co} {\bf Number:} width of the screen.
\item {\tt cr} {\bf String} to move cursor to the beginning of the line.
\item {\tt cs} {\bf String} to set the scroll region.
\item {\tt cS} {\bf Alternate} form of string to set the scroll region.
\item {\tt ct} {\bf String} to clear all tab stops.
\item {\tt cv} {\bf String} to position the cursor at line l in the same column.
\item {\tt da} {\bf Flag:} data scrolled off top of screen may be scrolled back.
\item {\tt db} {\bf Flag:} data scrolled off bottom of screen may be scrolled 
back.
\item {\tt dc} {\bf String} to delete one character position at the cursor.
\item {\tt DC} {\bf String} to delete n characters starting at the cursor.
\item {\tt dl} {\bf String} to delete the line the cursor is on.
\item {\tt DL} {\bf String} to delete n lines starting with the cursor's line.
\item {\tt dm} {\bf String} to enter delete mode.
\item {\tt do} {\bf String} to move the cursor vertically down one line.
\item {\tt DO} {\bf String} to move cursor vertically down n lines.
\item {\tt ds} {\bf String} to disable the display of the status line.
\item {\tt ec} {\bf String} of commands to clear n characters at cursor.
\item {\tt ed} {\bf String} to exit delete mode.
\item {\tt ei} {\bf String} to leave insert mode.
\item {\tt eo} {\bf Flag:} output of a space can erase.
Outputting a space will erase the character, even if the terminal 
can overstrike. {\it See os\/}. When the terminal does not support
overstriking a space will erase whatever was on this position 
before.
\item {\tt es} {\bf Flag:} other display commands work while writing the status 
line.
\item {\tt ff} {\bf String} to advance to the next page, for a hardcopy terminal.
\item {\tt fs} {\bf String} to move the cursor back from the status line to its
previous position (outside the status line).
\item {\tt gn} {\bf Flag:} this terminal type is generic.
The terminal is not real. Use for instance as default when 
connecting to other systems and specify a terminal (i.e network).
Programs that use termcap can now use "You have not specified
your real terminal type" than another.
\item {\tt hc} {\bf Flag:} hardcopy terminal.
\item {\tt hd} {\bf String} to move the cursor down half a line.
\item {\tt ho} {\bf String:} to move cursor at upper left corner (home position).
Supported by all terminals.
\item {\tt hs} {\bf Flag:} the terminal has a status line.
\item {\tt hu} {\bf String} to move the cursor up half a line.
\item {\tt hz} {\bf Flag:} terminal cannot accept {\it  ~\/} as output.
The tilde character is used for display commands. Programs must 
check the text and replace each {\it ~\/} with some other character.
\item {\tt i1} {\bf String} to initialize the terminal for each login session.
\item {\tt i3} {\bf String} to initialize the terminal for each login session.
\item {\tt ic} {\bf String} to insert one character position at the cursor.
\item {\tt IC} {\bf String} to insert n character positions at the cursor.
\item {\tt if} {\bf String} naming a file of commands to initialize the terminal.
\item {\tt im} {\bf String} to enter insert mode.
\item {\tt in} {\bf Flag:} outputting a space is different from moving over 
empty positions.
\item {\tt ip} {\bf String} to output following an inserted character in 
insert mode.
\item {\tt is} {\bf String} to initialize the terminal for each login session.
\item {\tt it} {\bf Number:} initial spacing between hardware tab stop columns.
\item {\tt k0} {\bf String} of input sent by function key 0 or 10.
\item {\tt k1} {\tt : :k:9} {\bf  Strings} of input sent by function keys 
1 through 9.
\item {\tt K1} {\tt : :K:5} {\bf  Strings} sent by the five other keys in 
3-by-3 array with arrows.
\item {\tt ka} {\bf String} of input sent by the "clear all tabs" key.
\item {\tt kA} {\bf String} of input sent by the "insert line" key.
\item {\tt kb} {\bf String} of input sent by the "backspace" key.
\item {\tt kC} {\bf String} of input sent by the "clear screen" key.
\item {\tt kd} {\bf String} of input sent by typing the down-arrow key.
\item {\tt kD} {\bf String} of input sent by the "delete character" key.
\item {\tt ke} {\bf String} to make the function keys work locally.
\item {\tt kE} {\bf String} of input sent by the "clear to end of line" key.
\item {\tt kF} {\bf String} of input sent by the "scroll forward" key.
\item {\tt kh} {\bf String} of input sent by typing the "home-position" key.
\item {\tt kH} {\bf String} of input sent by the "home down" key.
\item {\tt kI} {\bf String} of input sent by the "insert character" or "enter 
insert mode" key.
\item {\tt kl} {\bf String} of input sent by typing the left-arrow key.
\item {\tt kL} {\bf String} of input sent by the "delete line" key.
\item {\tt km} {\bf Flag:} the terminal has a Meta key.
\item {\tt kM} {\bf String} of input sent by the "exit insert mode" key.
\item {\tt kn} {\bf Numeric} value, the number of numbered function keys.
\item {\tt kN} {\bf String} of input sent by the "next page" key.
\item {\tt kP} {\bf String} of input sent by the "previous page" key.
\item {\tt kr} {\bf String} of input sent by typing the right-arrow key.
\item {\tt kR} {\bf String} of input sent by the "scroll reverse" key.
\item {\tt ks} {\bf String} to make the function keys transmit.
\item {\tt kS} {\bf String} of input sent by the "clear to end of screen" key.
\item {\tt kt} {\bf String} of input sent by the "clear tab stop this column" key.
\item {\tt kT} {\bf String} of input sent by the "set tab stop in this column" 
key.
\item {\tt ku} {\bf String} of input sent by typing the up-arrow key.
\item {\tt l0} {\bf String} on keyboard labeling function key 0 or 10.
\item {\tt l1} {\tt : :l:9} {\bf  Strings} on keyboard labeling function 
keys 1 through 9.
\item {\tt le} {\bf String} to move the cursor left one column.
\item {\tt LE} {\bf String} to move cursor left n columns.
\item {\tt li} {\bf Number:} height of the screen.
\item {\tt ll} {\bf String} to move cursor at lower left corner.
(On some terminals moving the cursor to the home position and
then up will work. {\it  ll\/} will do this if possible).
\item {\tt lm} {\bf Number:} lines of display memory.
\item {\tt mb} {\bf String} to enter blinking mode.
\item {\tt md} {\bf String} to enter double-bright mode.
\item {\tt me} {\bf String} to turn off all appearance modes
\item {\tt mh} {\bf String} to enter half-bright mode.
\item {\tt mi} {\bf Flag:} cursor motion in insert mode is safe.
\item {\tt mk} {\bf String} to enter invisible mode.
\item {\tt mm} {\bf String} to enable the functioning of the Meta key.
\item {\tt mo} {\bf String} to disable the functioning of the Meta key.
\item {\tt mp} {\bf String} to enter protected mode.
\item {\tt mr} {\bf String} to enter reverse-video mode.
\item {\tt ms} {\bf Flag:} cursor motion in standout mode is safe.
\item {\tt nd} {\bf String} to move the cursor right one column.
\item {\tt ns} {\bf Flag:} the terminal does not normally scroll for
sequential output.
\item {\tt nw} {\bf String} to move to start of next line, possibly 
clearing rest of old line.
\item {\tt os} {\bf Flag:} terminal can overstrike.
When outputting a graphic character this will not erase 
what was present on the position before.
\item {\tt pb} {\bf Number:} the lowest baud rate at which padding is
actually needed.
\item {\tt pc} {\bf String} containing character for padding.
\item {\tt pf} {\bf String} to terminate redirection of output to the printer.
\item {\tt po} {\bf String} to redirect further output to the printer.
\item {\tt pO} {\bf String} to redirect n characters of output to the printer.
\item {\tt ps} {\bf String} to print the screen on the attached printer.
\item {\tt rc} {\bf String} to move to last saved cursor position.
\item {\tt RI} {\bf String} to move cursor right n columns.
\item {\tt rp} {\bf String:} to output character c repeated n times.
{\it C\/} is the ASCII code of the character and {\it n\/} the number 
of times to repeat it.
\item {\tt rs} {\bf String} to reset the terminal from any strange modes.
\item {\tt sa} {\bf String} to turn on an arbitrary combination of appearance
modes.
\item {\tt sc} {\bf String} to save the current cursor position.
\item {\tt se} {\bf String} to leave standout mode.
\item {\tt sf} {\bf String} to scroll the screen one line up.
\item {\tt SF} {\bf String} to scroll the screen n lines up.
\item {\tt sg} {\bf Number:} width of magic standout cookie. Absent if magic
cookies are not used.
\item {\tt so} {\bf String} to enter standout mode.
\item {\tt sr} {\bf String} to scroll the screen one line down.
\item {\tt SR} {\bf String} to scroll the screen n line down.
\item {\tt st} {\bf String} to set tab stop at current cursor column on all
lines. programs.
\item {\tt ta} {\bf String} to move the cursor right to the next hardware
tab stop column.
\item {\tt te} {\bf String} to return terminal to settings for sequential output.
\item {\tt ti} {\bf String} to initialize terminal for random cursor motion.
\item {\tt ts} {\bf String} to move the terminal cursor into the status line.
\item {\tt uc} {\bf String} to underline one character and move cursor right.
\item {\tt ue} {\bf String} to turn off underline mode
\item {\tt ug} {\bf Number:} width of underlining magic cookie. Absent if 
underlining doesn't use magic cookies.
\item {\tt ul} {\bf Flag:} underline by overstriking with an underscore.
\item {\tt up} {\bf String} to move the cursor vertically up one line.
\item {\tt UP} {\bf String} to move cursor vertically up n lines.
\item {\tt us} {\bf String} to turn on underline mode
\item {\tt vb} {\bf String} to make the screen flash.
\item {\tt ve} {\bf String} to return the cursor to normal.
\item {\tt vi} {\bf String} to make the cursor invisible.
\item {\tt vs} {\bf String} to enhance the cursor.
\item {\tt wi} {\bf String} to set the terminal output screen window.
\item {\tt ws} {\bf Number:} the width of the status line.
\item {\tt xb} {\bf Flag:} superbee terminal.
The terminal can not transmit ESC and CTRL-C. Programs that use 
this Flag have to check input for code sequences sent by {\it F1\/}
and {\it F2\/} and use them as ESC and CTRL-C.
\item {\tt xn} {\bf Flag:} cursor wraps in a strange way.
\item {\tt xs} {\bf Flag:} clearing a line is the only way to clear the 
appearance modes of positions in that line (or, only way to 
remove magic cookies on that line).
\item {\tt xt} {\bf Flag:} Teleray 1061; several strange characteristics.
\end{list}








\clearpage
\subsection{Ncurses - Introduction}

In this section I will use the terminology of the ncurses manual. This means
\begin{itemize}
\item  window  - is an internal representation containing an image
of a part of the screen. WINDOW is defined in
{\it ncurses.h\/}.
\item  screen  - is a window with the size of the entire screen (from the
upper left to the lower right). {\it Stdscr\/} and {\it curscr\/}
are screens (see below for more information).
\item  terminal - is a special screen with information about how the screen
currently looks like.
\item  variables - the following variables and constants defined in 
{\it ncurses.h\/}
\begin{itemize}
\item  WINDOW *curscr - current screen
\item  WINDOW *stdscr - standard screen
\item  int LINES - lines on the terminal
\item  int COLS - columns on the terminal
\item  bool TRUE - true flag, 1
\item  bool FALSE - false flag, 0
\item  int ERR - error flag, -1
\item  int OK - ok flag, 0
\end{itemize}
\end{itemize}


A program using the ncurses library must look like this:

\begin{tscreen}
\begin{verbatim}
    #include <ncurses.h>
    ...
    main()
    {
      ...
      initscr();
      ...
      endwin();
      ...
    }
\end{verbatim}
\end{tscreen}


Including {\it ncurses.h\/} will define variables and types for ncurses, such
as WINDOW and function prototypes. It automatically includes {\it stdio.h\/},
{\it stdarg.h\/} and {\it termios.h\/}.

{\it Initscr()\/} is used to initialize the ncurses data structures and to
read the proper terminfo file. Memory for
{\it stdscr\/} and {\it curscr\/} will be allocated. If an error occurs,
initscr will return ERR otherwise a pointer to {\it stdscr\/}. Additional the
screen will be erased and {\it LINES\/} and {\it COLS\/} will be initialized.

{\it Endwin()\/} will clean up all allocated resources from ncurses and restore
the tty modes to the status they had before calling {\it initscr()\/}.

{\it Initscr()\/} must be called before any other function from the ncurses
library and {\it endwin()\/} must be called before your program will exit. When
you want to do output to more than one terminal, you can use {\it newterm(...)\/}
instead of {\it initscr()\/}.

Our example need to check the return code from {\it initscr()\/}.

\begin{tscreen}
\begin{verbatim}
    if (!initsrc())
      exit (1);
\end{verbatim}
\end{tscreen}


The program will exit, when {\it initsrc()\/} can't allocate memory or has some
other problems.

Compile the program with:

\begin{tscreen}
\begin{verbatim}
    gcc [flags] files -lncurses
\end{verbatim}
\end{tscreen}


In flags you can include anything you like. Since the path for ncurses.h
has changed you have to include the following line:

\begin{tscreen}
\begin{verbatim}
    -I/usr/include/ncurses.h
\end{verbatim}
\end{tscreen}


Otherwise ncurses.h and unctrl.h will not be found. Possible other flags
for Linux are:

\begin{tscreen}
\begin{verbatim}
    -O6 -ansi -Wall -m486 -DLINUX
\end{verbatim}
\end{tscreen}


{\it O6\/} tells gcc to do some optimization, {\it -ansi\/} is for ansi conform
c-code, {\it -Wall\/} will print out all warnings, {\it -m486\/} will use optimized
code for an Intel 486 (the binary can be used on an Intel 386, too) and
{\it -DLINUX\/} tells defines the macro LINUX for \#ifdef in the code.

The ncurses library could be found in /usr/lib/. Actually there
are three versions:
\begin{itemize}
\item  {\bf libncurses.a} the normal ncurses library.
\item  {\bf libdcurses.a} ncurses for debugging.
\item  {\bf libpcurses.a} ncurses for profiling.
\item  {\bf libcurses.a}  No fourth version, but the original System V
curses.
\end{itemize}


The data structures for the screen are called {\it windows\/} as defined in
{\it ncurses.h\/}. A window is something like a character
array in the memory and a programmer can manipulate the array without
output to the terminal. The default window is {\it stdscr\/} with the size of
the terminal. You can create other windows with {\it newwin(...)\/}.

To update the physical terminal optimally, ncurses has another window
declared, {\it curscr\/}. {\it Curscr\/} is an image of the terminal how it
actually looks like and {\it  stdscr\/} is an image how the terminal should
look like.
The output will be done when you call {\it  refresh()\/}. Ncurses will then
update {\it  curscr\/} and the physical terminal with the information in
{\it  stdscr\/}.
Ncurses will use for the update process internal optimization so you can
change different windows and then update the screen at once in the most
optimal way.

With the ncurses functions you can manipulate the data structure 
{\it  window\/}. Functions beginning with {\it  w\/} allow to specify a {\it  window\/}
others will affect usually {\it  stdscr\/}. Functions beginning with {\it  mv\/}
will move the cursor to the position {\it  y,x\/} first.

A character has the type {\it  chtype\/} which is {\it  long unsigned int\/} to
store additional information about the character (attributes etc.). 

Ncurses use the {\it  terminfo\/} database. Normally the database is
located in {\it  \/}usr/lib/terminfo/ and ncurses will look there for
local terminal definitions. If you want to test for example some other
definitions for a terminal without changing the original terminfo, set the
environment variable {\it  TERMINFO\/}. Ncurses will check this variable
and use the definitions stored there instead of /usr/lib/terminfo/.





\clearpage
\subsection{Ncurses functions}




\subsubsection{Windows}

Windows can be created, deleted, moved, copied, touched, duplicated and more.
A new window can created with {\it  newwin\/}.

\begin{itemize}
\item {\tt WINDOW *newwin(nlines, ncols, begy, begx)} \\ 
{\it Newwin(...)\/} returns a WINDOW pointer. {\it Begy\/} and {\it begx\/} are
the coordinates of the upper left corner from the window. {\it Nlines\/}
is an integer with the number of lines and {\it ncols\/} is an integer with
the number of columns. The upper left corner of our window is in line 10
and column 10 and the window has 10 lines and 60 columns. If {\it nlines\/}
is zero, the window will have $LINES-begy$ rows. On the same way the 
window will have $COLS-begx$ columns when {\it ncols\/} is zero.

\begin{tscreen}
\begin{verbatim}
    WINDOW *mywin;
    mywin=newwin(10,60,10,10);
\end{verbatim}
\end{tscreen}

\item {\tt  int delwin(win)} \\ 
Delete the window {\it  win\/}. When there are sub windows delete them
before {\it  win\/}.
{\it  Delwin(win)\/} will free up all resources occupied by the window {\it  win\/}.
Delete all windows you have opened before calling {\it  endwin()\/}.
\item {\tt  int mvwin(win,by,bx)} \\ 
Will move a window to the coordinates {\it by,bx\/}. When
this means move it out of the screen nothing is done and ERR is returned.
\item {\tt  WINDOW *subwin(origwin, nlines, ncols, begy, begx)} \\ 
Returns a sub window in the middle of {\it  origwin\/}. When you change one of
the two windows ({\it  origwin\/} or the new one) this will reflect both
windows.

{\it  Begx\/} and {\it  begy\/} are relative to the screen, not to {\it  origwin\/}.
\item {\tt  WINDOW *derwin(origwin, nlines, ncols, begy, begx)} \\ 
The same as {\it  subwin(...)\/} except that {\it  begx\/} and {\it  begy\/} are
relative to the window {\it  origwin\/} than to the screen.
\item {\tt  WINDOW *dupwin(win)} \\ 
Should duplicate a window. In version 1.8.5 not implemented.
\item {\tt  int mvderwin(win,y,x)} \\ 
{\tt  int syncok(win,bf)} \\ 
{\tt  void wsyncup(win)} \\ 
{\tt  void wcursyncup(win)} \\ 
{\tt  void wsyncdown(win)} \\ 
Not implemented yet.
\item {\tt  int touchline(win,start,count)} \\ 
{\tt  int untouchwin(win)} \\ 
Tells ncurses that the whole window {\it  win\/} or the whole line
has been manipulated. For instance, when you have some overlapping
windows (as in the example {\it  type.c\/}) a change to one
window will not affect the image from the other.

{\it  Wtouchln(...)\/} will touch {\it  n\/} lines starting at {\it  y\/}.
If {\it  change\/} is TRUE the lines are touched, otherwise untouched.

{\it  Untouchwin(win)\/} will mark the window {\it  win\/} as unchanged
since the last call to {\it  refresh()\/}.
\item {\tt  int is\_linetouched(win,line)} \\ 
{\tt  int is\_wintouched(win)} \\ 
With these functions you can check, if the lines {\it  lines\/} or the
window {\it  win\/} has been touched since the last call to {\it  refresh()\/}.
\item {\tt  int overlay(win1, win2)} \\ 
{\tt  int overwrite(win1, win2)} \\ 
{\it  Overlay(...)\/} will copy all text from {\it  win1\/} to {\it  win2\/} without
copying blanks. {\it  Overwrite(...)\/} does the same, but copies blanks, too.
\item {\tt  int copywin(win,win,sminrow,smincol,dminrow,dmincol,dmaxrow,dmaxcol,overlay)} \\ 
\end{itemize}









\subsubsection{Window options}

\begin{itemize}
\item {\tt  int idlok(win,bf)} \\ 
{\tt  void idcok(win,bf)} \\ 
enable or disable terminals insert/delete
features for the window. ({\it  idlok\/} for
lines and {\it  idcok\/} for characters)
\item {\tt  void immedok(win,bf)} \\  
If set TRUE every change to the window
{\it  win\/} will cause a refresh to the physical
screen. This can decrease the performance of a
program, so the default value is FALSE.
\item {\tt  int keypad(win,bf)} \\ 
If TRUE it enables the keypad on the keyboard of
the users terminal when waiting for input.
Ncurses will then return a key code defined in
{\it  ncurses.h\/} as KEY\_* for the function and
arrow keys on the keypad. This is very useful
for a PC keyboard cause you can enable the
numerical block and the cursor keys.
\item {\tt  int leaveok(win,bf)} \\ 
On default ncurses leaf the physical cursor
on the place the last refresh left the window
cursor. Programs which don't use the cursor can
set {\it  leaveok\/} TRUE and save on this way the
time for cursor motions. Additional curses will try to make
the terminal cursor invisible.
\item {\tt  int meta(win,bf)} \\ 
If TRUE the key codes returned from {\it  getch()\/}
are 8-bit-clean (the highest bit will not be 
stripped).
\item {\tt  int notimeout(win,bf)} \\ 
If TRUE {\it  getch()\/} will use a special timer
(one second) to interpret an input sequence
beginning with keys as ESCAPE etc.
\item {\tt  int scrollok(win,bf)} \\ 
If TRUE the text in the window {\it  win\/} will
be scrolled up one line when the cursor is on
the lower right corner and a character is typed
(or newline). If FALSE the cursor is left on it
position.
\item {\tt  int setscrreg(t,b)} \\ 
{\tt  int wsetscrreg(win,t,b)} \\ 
Set a software scrolling region.
See scrolling below for information.
\end{itemize}











\subsubsection{Terminal Modes}

\begin{itemize}
\item {\tt  int cbreak()} \\ 
{\tt  int nocbreak()} \\ 
{\tt  int crmode()} \\ 
{\tt  int nocrmode()} \\ 
{\it  Cbreak()\/} and {\it  nocbreak()\/} will turn the
terminal CBREAK mode on or off. When CBREAK is on
input from read will be immediately available to the
program, when off the input will be buffered until
newline occurs. ({\it  crmode()\/} and
{\it  nocrmode()\/} are for upward compatibility).
\item {\tt  int raw()} \\ 
{\tt  int noraw()} \\ 
Turn RAW mode on or off. RAW is the same as CBREAK,
except that in RAW mode no special character
processing will be done.
\item {\tt  int echo()} \\ 
{\tt  int noecho()} \\ 
Set {\it  echo()\/} to echo input typed by the user
and {\it  noecho()\/} if not.
\item {\tt  int halfdelay(t)} \\ 
As {\it  cbreak()\/} with a delay of {\it  t\/} seconds.
\item {\tt  int nodelay(win,bf)} \\  
Terminal will be set to no blocking mode.
{\it  Getch()\/} will return ERR if no input
is ready. If set to FALSE {\it  getch\/} will
wait until a key is pressed.
\item {\tt  int timeout(t)} \\ 
{\tt  int wtimeout(win,t)} \\  
Ncurses manual recommends the use of these
functions instead of {\it  halfdelay(t)\/}
and {\it  nodelay(win,bf)\/}. {\it  Getch()\/}
returns depending on the value of {\it  t\/}.
If {\it  t\/} is positive, read is blocked for
{\it  t\/} milliseconds, on zero no blocking is
done and when {\it  t\/} is negative read is blocked
until input is there.
\item {\tt  int nl()} \\ 
{\tt  int nonl()} \\ 
Control the translation for newline. Turned on with
{\it  nl()\/} will translate a newline in carriage return
and line feed on output, {\it  nonl()\/} will turn translation
off. With disabled translation ncurses can to faster
cursor motions.
\item {\tt  int savetty()} \\ 
{\tt  int resetty()} \\  
Save and restore tty modes.
\end{itemize}











\subsubsection{Use Options and Modes}

Now we have seen the window options and terminal modes it is time to
describe they're use.

At first, on Linux you should enable the keypad. This will allow to use
the cursor keys and the numeric block on the PC keyboard.

\begin{tscreen}
\begin{verbatim}
    keypad(stdscr,TRUE);
\end{verbatim}
\end{tscreen}


Now there are two sections of input (or more?).
\begin{enumerate}
\item \item The program wants the user enter a key and then call a function depend
on this key. (for example something like "press 'q' for quit" and wait
for {\it  q\/})
\item The program wants a string or character typed by the user in a mask
on the screen. (for example a directory or a address in a database etc.)
\end{enumerate}


For the first we use the following options and modes and the while loop will
work correctly.

\begin{tscreen}
\begin{verbatim}
    char c;

    noecho();
    timeout(-1);
    nonl();
    while(c=getch()){
      switch(c){
        case 'q': your_quit_function();
                  break;
        default:  break;
      }
   }
\end{verbatim}
\end{tscreen}


The program will hang until a key is pressed and check this key. If it was 
{\it  q\/} we call our quit function else we wait for other input.

The switch statement can be expanded until we have an input function that
fits our wishes. Use the KEY\_* macros to check special keys, for instance

\begin{tscreen}
\begin{verbatim}
    KEY_UP
    KEY_DOWN
    KEY_RIGHT
    KEY_LEFT
\end{verbatim}
\end{tscreen}


for the cursor keys on the keyboard.
For a file viewer the loop can look like this:

\begin{tscreen}
\begin{verbatim}
    char c;
    enum{UP,DOWN,RIGHT,LEFT};

    noecho();
    timeout(-1);
    nonl();
    while(c=getch()){
      switch(c){
        case KEY_UP:
        case 'u':
        case 'U': scroll_s(UP);
                  break;
        case KEY_DOWN:
        case 'd':
        case 'D': scroll_s(DOWN);
                  break;
        case KEY_LEFT:
        case 'l':
        case 'L': scroll_s(LEFT);
                  break;
        case KEY_RIGHT
        case 'r':
        case 'R': scroll_s(RIGHT);
                  break;
        case 'q':
        case 'Q': okloop=FALSE;
                  break;
        default:  break;
      }
   }
\end{verbatim}
\end{tscreen}


For the second we only need to set {\it echo()\/} and the characters typed
by the user will be printed to the screen. To have the characters printed 
on the position you like use {\it move\/} or {\it wmove\/}.

Or we open a window with a mask in it (some other colors then in the window
will do this) and ask the user for input a string. This is what I do
in {\it inp.c\/} in the example directory. See {\it inp.c\/} for more explanations.








\subsubsection{Updating the Terminal}

As written in the overview ncurses windows are images in the memory. This
means any change on a window is not printed to the physical screen until
a refresh is done. This optimize the output to the screen, because you
can do a lot of manipulations and then, once, call refresh to print it
on screen. Otherwise every change would be printed to the terminal and 
decrease the performance of your programs.

\begin{itemize}
\item {\tt  int refresh()} \\ 
{\tt  int wrefresh(win)} \\ 
{\it  Refresh()\/} copies {\it  stdscr\/} to the terminal
and {\it  wrefresh(win)\/}
copies the window images to {\it  stdscr\/} and makes
then {\it  curscr\/} looks like {\it  stdscr\/}.
\item {\tt  int wnoutrefresh(win)} \\ 
{\tt  int doupdate()} \\ 
{\it  Wnoutrefresh(win)\/} copies the window {\it  win\/}
only to stdscr. This means that no output to the
terminal is done, but the virtual screen
{\it  stdscr\/} actually looks like the programmer
wanted. {\it  Doupdate()\/} will do the output to
the terminal. A program can change various windows,
call {\it  wnoutrefresh\/} for every window and then
call {\it  doupdate()\/} to update the physical screen
only once.
\end{itemize}


For instance we have the following program with two windows.
We do some changes to both windows (change some lines of text).
We can write {\it  changewin(win)\/} with {\it  wrefresh(win)\/}.

\begin{tscreen}
\begin{verbatim}
    main()                    changewin(WINDOW *win)
    {                         {
    WINDOW *win1,*win2;           ... /* here we change */
        ...                       ... /* the lines */
        changewin(win1);          wrefresh(win);
        changewin(win2);      return;
        ...                   }
    }
\end{verbatim}
\end{tscreen}


This will cause ncurses to update the terminal twice and slow down our
performance. With {\it  doupdate()\/} we change {\it  changewin(win)\/} and
our main function and will get a better performance.

\begin{tscreen}
\begin{verbatim}
    main()                    changewin(WINDOW *win)
    {                         {
    WINDOW *win1,*win2;           ... /* here we change */
        ...                       ... /* the lines */
        changewin(win1);          wnoutrefresh(win);
        changewin(win2);      return;
        doupdate();           }
        ...
    }
\end{verbatim}
\end{tscreen}









\subsubsection{Cursor}

\begin{itemize}
\item {\tt  int move(y,x)} \\ 
{\tt  int wmove(win,y,x)} \\ 
{\it  Move()\/} moves the cursor from {\it  stdscr\/},
{\it  wmove(win)\/} the cursor from window {\it  win\/}.
For in/output functions additional macros
defined which move the cursor before the
specified function is called.
\item {\tt  int curs\_set(bf)} \\ 
This will turn the cursor visibility on or off, if
the terminal has this capability.
\item {\tt  getyx(win,y,x)} \\ 
{\it Getyx(...)\/} will return the current cursor position in {\it win\/} in the
to integer arguments {\it y\/} and {\it x\/}. (Note: this is a macro).
\end{itemize}









\subsubsection{Output}

\begin{itemize}
\item {\tt  addch(ch)} \\ 
{\tt  waddch(win,ch)} \\ 
{\tt  mvaddch(y,x,ch)} \\ 
{\tt  mvwaddch(win,y,x,ch)} \\ 
The functions are used for character output to a window. They will
manipulate the window and you have to call refresh to get it on screen.
{\it  Addch(...)\/} and {\it  waddch(...)\/} put the character {\it  ch\/} in the window
{\it  stdscr\/} or {\it  win\/}. {\it  Mvaddch(...)\/} and {\it  mvwaddch(...)\/} do the same
except that they move the cursor to position x,y first.
\item {\tt  addstr(str)} \\ 
{\tt  addnstr(str,n)} \\ 
{\tt  waddstr(win,str)} \\ 
{\tt  waddnstr(win,str,n)} \\ 
{\tt  mvaddstr(y,x,str)} \\ 
{\tt  mvaddnstr(y,x,str,n)} \\ 
{\tt  mvwaddstr(win,y,x,str)} \\ 
{\tt  mvwaddnstr(win,y,x,str,n)} \\ 
These functions write a string to a window. (They are as a series of calls to
{\it  addch(...)\/}). {\it  Str\/} is a null terminated string ({\it  "blafoo\verb+\+0"\/}).
Functions with {\it  w\/} write the string {\it  str\/} to the window {\it  win\/}
the other to {\it  stdscr\/}. Functions with {\it  n\/} write n characters of
{\it  str\/}. If {\it  n\/} is -1, the entire string {\it  str\/} is written.
\item {\tt  addchstr(chstr)} \\ 
{\tt  addchnstr(chstr,n)} \\ 
{\tt  waddchstr(win,chstr)} \\ 
{\tt  waddchnstr(win,chstr,n)} \\ 
{\tt  mvaddchstr(y,x,chstr)} \\ 
{\tt  mvaddchnstr(y,x,chstr,n)} \\ 
{\tt  mvwaddchstr(win,y,x,chstr)} \\ 
{\tt  mvwaddchnstr(win,y,x,chstr,n)} \\ 
These functions copy {\it  chstr\/} to the window image ({\it  stdscr\/} or
{\it  win\/}). The starting position is the current cursor position.
Functions with {\it  n\/} write n characters of {\it  chstr\/}. If {\it  n\/} is -1,
the entire string {\it  chstr\/} is written. The cursor is not moved and no
control character check is done. The functions are faster as the {\it  addstr(...)\/}
routines. {\it  Chstr\/} is a pointer to an array of chtype.
\end{itemize}











\subsubsection{Formatted Output}

\begin{itemize}
\item {\tt  printw(fmt, ...)} \\ 
{\tt  wprintw(win, fmt, ...)} \\ 
{\tt  mvprintw(y, x, fmt, ...)} \\ 
{\tt  mvwprintw(win, y, x, fmt, ...)} \\ 
{\tt  vwprintw(win, fmt, va\_list)} \\ 
These functions correspondent to {\it  printf\/} from {\it  libc\/} and the character
is printed out by printf (vwprintw correspondents with vprintf).

In the {\it  libc\/} package {\it  printf\/} is used for formatted output. You can
define an output string and include variables of different type in it.
For instance you like to output an integer:

\begin{tscreen}
\begin{verbatim}
    int i=2;
    printf("This is version %i.",i);
\end{verbatim}
\end{tscreen}


{\it  Printf\/} will print this string to the screen and format the integer
{\it  i\/} to the number {\it  2\/}. Every type in the string begins with
{\it  \%\/} followed by a character (to print \% by itself use {\it  \%\%\/}).

\begin{center}
\begin{tabular}{|l|l|} \hline
{\bf Character} &  {\bf Formatted to} \\ \hline
d,i &  {\it int\/} signed, decimal \\ 
o &  {\it int\/} unsigned, octal, without leading 0 \\ 
x,X &  {\it int\/} unsigned, hexadecimal without leading 0x \\ 
u &  {\it int\/} unsigned, decimal \\ 
c &  {\it int\/} (unsigned) single character \\ 
s &  {\it char *\/} up to \verb+\+0 \\ 
f &  {\it double\/} as $[-]mmm.ddd$ \\ 
e,E &  {\it double\/} as $[-]m.dddddde \pm xx$ \\ 
g,G &  {\it double\/} using \%e or \%f as needed \\ 
p &  {\it void *\/} \\ 
n &  {\it int *\/} \\ 
\% &  {\it \%\/} \\ \hline
\end{tabular}
\end{center}

\end{itemize}









\subsubsection{Input}

\begin{itemize}
\item {\tt  int getch()} \\ 
{\tt  int wgetch(win)} \\ 
{\tt  int mvgetch(y,x)} \\ 
{\tt  int mvwgetch(win,y,x)} \\ 
As in our example above {\it  getch()\/} will read input from the terminal depending
if delay mode is set or not. If delay is on, {\it  getch()\/} will wait until a key
is pressed, else it will return the key in the input buffer or ERR if this 
buffer is empty. {\it  Mvgetch(...)\/} and {\it  mvwgetch(...)\/} will move the cursor to position
{\it  x,y\/} first. The {\it  w\/} functions read input from the terminal related to
the window {\it  win\/}, {\it  getch()\/} and {\it  mvgetch(...)\/} from the terminal related
to {\it  stdscr\/}.

With {\it  keypad\/} enabled {\it  getch\/} will return a code defined in {\it  ncurses.h\/}
as KEY\_* macros when a function key is pressed. When a key as ESCAPE is pressed
(which can be the beginning of a function key) ncurses will start a second
timer for one second. Comes the remainder for the key not in this second,
the key is returned else the function key value will be returned.
(use {\it  notimeout()\/} to disable the second timer).
\item {\tt  int getstr(str)} \\ 
{\tt  int wgetstr(win,str)} \\ 
{\tt  int mvgetstr(y,x,str)} \\ 
{\tt  int mvwgetstr(win,y,x,str)} \\ 
These functions will do a series call to {\it  getch()\/} until newline is received.
The characters are placed in {\it  str\/} (so don't forget to allocate
memory for your character pointer before calling {\it  getstr(...)\/}).
If echo is enabled the string is echoed (use {\it  noecho()\/} to disable echo) and
the users kill and delete characters will be interpreted.
\item {\tt  scanw(fmt, ...)} \\ 
{\tt  wscanw(win, fmt, ...)} \\ 
{\tt  mvscanw(y, x, fmt, ...)} \\ 
{\tt  mvwscanw(win, y, x, fmt, ...)} \\ 
{\tt  vwscanw(win,fmt,va\_list)} \\ 
The same as {\it  scanf\/} from {\it  libc\/}. {\it  Wgetstr(...)\/} is called and the results
will be used as input for the scan.
\end{itemize}









\subsubsection{Clear screen/window}

\begin{itemize}
\item {\tt  erase()} \\ 
{\tt  werase(win)} \\ 
{\it  Werase(...)\/} and {\it  erase()\/} will copy blanks to every position 
on the window {\it  win\/} or
{\it  stdscr\/}. For instance, when you set color attributes to a window
and call {\it  werase\/} the window would be colored. I had some problems
with COLOR\_PAIRS when I defined other attributes then black on white
so I wrote my own erase
function (this is a low level access to the WINDOW structure and not
recommended):

\begin{tscreen}
\begin{verbatim}
    int  y,x;
  
     for ( y = 0 ; y <= win -> _maxy ; y++ )
       for ( x = 0 ; x <= win -> _maxx ; x++ )
         (chtype *) win -> _line[y][x] = ' ' | win -> _attrs;
     win -> _curx = win -> _cury = 0;
     touchwin(win);
\end{verbatim}
\end{tscreen}


\item {\tt  clear()} \\ 
{\tt  wclear(win)} \\ 
The same as {\it  erase()\/}, but will also set {\it  clearok()\/} (the screen will be
cleared with the next refresh).
\item {\tt  clrtobot()} \\ 
{\tt  wclrtobot(win)} \\ 
Clearing the current cursor line (start is one character right from the cursor)
and the line below the cursor.
\item {\tt  clrtoeol()} \\ 
{\tt  wclrtoeol(win)} \\ 
Clear the current line right from the cursor up to they're end.
\end{itemize}









\subsubsection{Insert/Delete Text}

\begin{itemize}
\item {\tt  delch()} \\ 
{\tt  wdelch(win)} \\ 
{\tt  mvdelch(y,x)} \\ 
{\tt  mvwdelch(win,y,x)} \\ 
Delete the character under the cursor and the characters right from the  
cursor moved one position to the left. 
\item {\tt  deleteln()} \\ 
{\tt  wdeleteln(win)} \\ 
Delete the line under the cursor and move all other lines below one position up.
Additional the bottom line of the window will be erased.
\item {\tt  insch(c)} \\ 
{\tt  winsch(win, c)} \\ 
{\tt  mvinsch(y,x,c)} \\ 
{\tt  mvwinsch(win,y,x,c)} \\ 
Character {\it  ch\/} is inserted left from the cursor and all characters moved
one position to the right (the character on the right end of the line may 
be lost).
\item {\tt  insertln()} \\ 
{\tt  winsertln(win)} \\ 
Insert a blank line above the current one (bottom line will be lost).
\end{itemize}









\subsubsection{Lines}

\begin{itemize}
\item {\tt  border(ls, rs, ts, bs, tl, tr, bl, br)} \\ 
{\tt  wborder(win, ls, rs, ts, bs, tl, tr, bl, br)} \\ 
{\tt  box(win, vert, hor)} \\ 
Draw a border around the edges of a window ({\it  stdscr\/} or {\it  win\/}).
In the following table you see the characters and they're default values
when zero in a call to {\it  box\/}. In the picture you can see the position
from the characters in a box.

\begin{center}
\begin{tabular}{|l|l|l|} \hline
{\bf Character} &  {\bf Position} &  {\bf Default} \\ \hline
tl &  top left &  ACS\_ULCORNER \\ 
ts &  top side &  ACS\_HLINE \\ 
tr &  top right &  ACS\_URCORNER \\ 
ls &  left side &  ACS\_VLINE \\ 
rs &  right side &  ACS\_VLINE \\ 
bl &  bottom left &  ACS\_LLCORNER \\ 
bs &  bottom side &  ACS\_HLINE \\ 
br &  bottom right &  ACS\_LRCORNER \\ 
rt &  right tee &  ACS\_RTEE \\ 
lt &  left tee &  ACS\_LTEE \\ 
tt &  top tee &  ACS\_TTEE \\ 
bt &  bottom tee &  ACS\_BTEE \\ \hline
\end{tabular}
\end{center}

\begin{center}
\input {boxpic.tex}
\end{center}

\item {\tt  vline(ch,n)} \\ 
{\tt  wvline(win,ch,n)} \\ 
{\tt  hline(ch,n)} \\ 
{\tt  whline(win,ch,n)} \\ 
These functions draw a vertical or horizontal line starting at the current
cursor position. {\it  Ch\/} is the character to use and {\it  n\/} is the
number of characters to draw. The cursor position is not advanced.
\end{itemize}









\subsubsection{Video Attributes and Color}

Attributes are special terminal capabilities when printing characters
to the screen. They can be printed bold or underlined or blinking etc.
In ncurses you have the possibility to turn attributes on or off to get
a looking output. Possible attributes are listed in the following table.

\begin{center}
\begin{tabular}{|l|l|} \hline
{\bf Definition} &  {\bf Attribute} \\ \hline
A\_ATTRIBUTES &  mask for attributes (chtype) \\ 
A\_NORMAL &  normal, reset all other \\ 
A\_STANDOUT &  best highlighting mode \\ 
A\_UNDERLINE &  underline \\ 
A\_REVERSE &  reverse video \\ 
A\_BLINK &  blinking \\ 
A\_DIM &  dim or half bright \\ 
A\_BOLD &  bold or extra bright \\ 
A\_ALTCHARSET &  use alternate character set \\ 
A\_INVIS &  invisible \\ 
A\_PROTECT &  ??? \\ 
A\_CHARTEXT &  mask for actual character (chtype) \\ 
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 \\ \hline
\end{tabular}
\end{center}


To define and change colors on a terminal which has colors, you can use
one of these colors. Also to variables defined with {\it  start\_color()\/}.
COLORS is the number of maximum colors the terminal has and COLOR\_PAIR
is a number for the maximum color pairs you can define.

\begin{center}
\begin{tabular}{|l|l|} \hline
{\bf Definition} &  {\bf Color} \\ \hline
COLOR\_BLACK &  black \\ 
COLOR\_RED &  red \\ 
COLOR\_GREEN &  green \\ 
COLOR\_YELLOW &  yellow \\ 
COLOR\_BLUE &  blue \\ 
COLOR\_MAGENTA &  magenta \\ 
COLOR\_CYAN &  cyan \\ 
COLOR\_WHITE &  white \\ \hline
\end{tabular}
\end{center}


The attributes can combined with the OR operator '${\verbar}$' so that you can
produce bold blinking output with

\begin{tscreen}
\begin{verbatim}
    A_BOLD|A_BLINK
\end{verbatim}
\end{tscreen}


When you set a window to attribute {\it  at\/} all characters printed to this
window will get it as a property until you change the window attribute.
It will not get lost when you scroll or move the window or anything else.

When you write programs for ncurses and BSD curses be careful with colors,
cause BSD curses has no color support (also old SYS V versions of curses
do not have color support). So you have to use {\it  \#ifdef\/} operations
in your code or you use {\it  has\_colors()\/} in guarded expressions.
See example for more information.



\begin{itemize}
\item {\tt  attroff(at)} \\ 
{\tt  wattroff(win, attrs)} \\ 
{\tt  attron(at)} \\ 
{\tt  wattron(win, attrs)} \\ 
Turn on or off the specified attribute {\it  at\/} without reflecting the other
attributes in a window ({\it  stdscr\/} or {\it  win\/}).
\item {\tt  attrset(at)} \\ 
{\tt  wattrset(win, attrs)} \\ 
Set the attribute on {\it  stdscr\/} or {\it  win\/} to {\it  at\/}.
\item {\tt  standout()} \\ 
{\tt  standend()} \\ 
{\tt  wstandout(win)} \\ 
{\tt  wstandend(win)} \\ 
Turn on standout attribute for the window ({\it  stdscr\/} at {\it  win\/}).
\item {\tt  has\_colors()} \\ 
Returns TRUE if the terminal has colors else FALSE. Before you use colors
check the terminal with {\it  has\_colors()\/} (and before this initialize
colors with {\it  start\_color())\/}).
\item {\tt  can\_change\_color()} \\ 
TRUE if the terminal can redefine colors.
\item {\tt  start\_color()} \\ 
Color initializing. This function has to be called before using colors!
\item {\tt  init\_pair(pair, fg, bg)} \\ 
When you use colors as attributes for windows you have at first to define
a color pair with {\it  init\_pair\/}. {\it  Fg\/} is the foreground color and
{\it  bg\/} the background color from the pair {\it  pair\/}. {\it  Pair\/} is
a value from 1 to $COLOR\hspace{.167em}PAIRS-1$. Once defined you can use {\it  pair\/}
like an attribute. For instance when you want to have red characters on a
blue screen do:

\begin{tscreen}
\begin{verbatim}
    init_pair(1,COLOR_RED,COLOR_BLUE);
\end{verbatim}
\end{tscreen}


Now usr {\it wattr\/} to set {\it win\/} to our new color pair:

\begin{tscreen}
\begin{verbatim}
    wattr(win,COLOR_PAIR(1));
\end{verbatim}
\end{tscreen}


You can combine color pairs also with other attributes, such as:

\begin{tscreen}
\begin{verbatim}
    wattr(win ,A_BOLD|COLOR_PAIR(1));
    wattr(win1,A_STANDOUT|COLOR_PAIR(1));
\end{verbatim}
\end{tscreen}


The first will invoke the color pair and set the attribute BOLD on and the
second will turn on standout mode, so that you get high lighted red on blue a 
screen.
\item {\tt  pair\_content(pair, f, b)} \\ 
Will return the foreground and background color from the color pair {\it  pair\/}.
\item {\tt  init\_color(color, r, g, b)} \\ 
Change the color components {\it  r\/}, {\it  g\/} and {\it  b\/} for color {\it  color\/}.
{\it  R\/}, {\it  g\/} and {\it  b\/} can have values from 1 to $COLORS-1$.
\item {\tt  color\_content(color, r, g, b)} \\ 
Get the color components {\it  r\/}, {\it  g\/} and {\it  b\/} for color {\it  color\/}.
\end{itemize}


And how to combine attributes and colors? Some terminals, as the console
in Linux, have colors and some not (xterm, vt100 etc). The following
code should solve the problem:

\begin{tscreen}
\begin{verbatim}
WINDOW *win1,*win2,*win3; /* defined somewhere */

void CheckColor()
{
 start_color();
 if (has_colors()){
   /* fine we have colors, define color_pairs for foreground
    * and background colors
    */
   init_pair(1,COLOR_BLUE,COLOR_WHITE);
   init_pair(2,COLOR_WHITE,COLOR_RED);
   init_pair(3,COLOR_BLACK,COLOR_WHITE);
   /* now use the defined color_pairs for the windows */
   wattrset(win1,COLOR_PAIR(2));
   wattrset(win2,COLOR_PAIR(1));
   wattrset(win3,COLOR_PAIR(3));
 }
 else{
   /* ohh, no color (maybe a vt100 or xterm). ok we use black/white
    * attributes instead
    */
   wattrset(win1,A_REVERSE);
   wattrset(win2,A_BOLD);
   wattrset(win3,A_NORMAL);
 }
return;
}
\end{verbatim}
\end{tscreen}


The function {\it CheckColor\/} initialize at first the colors with
{\it start\_color()\/}. Then the function {\it has\_colors()\/}
will return TRUE if the current terminal has colors and FALSE if not.
We check this and call {\it init\_pair(...)\/} to combine foreground and
background colors and {\it wattrset(...)\/} to set these pairs for the
specified window. Or e use only {\it wattrset(...)\/} to set attributes if
we have a black and white terminal.








\subsubsection{Scrolling}

Enable scrolling with {\it scrollok(win,TRUE)\/}. Then the contents of a window
can be scrolled with the following functions. Note: It would be also
scrolled, if you print a new line in the last line of the window. So be
careful with {\it scrollok(...)\/} or you would get unreasonable results.

\begin{itemize}
\item {\tt scroll(win)} \\ 
This function will scroll up the window (and the lines in the data structure)
one line.
\item {\tt scrl(n)} \\ 
{\tt wscrl(win,n)} \\ 
These functions will scroll the window {\it stdscr\/} or {\it win\/} up or down 
depending on the value of the integer {\it n\/}.
If {\it n\/} is positive the window will be scrolled up {\it n\/} lines,
otherwise if {\it n\/} is negative the window will be scrolled down {\it n\/}
lines.
\end{itemize}

