-</PRE>
-
-<H3><A NAME="starting">Starting up</A></H3>
-
-In order to use the screen package, the routines must know about terminal
-characteristics, and the space for <CODE>curscr</CODE> and <CODE>stdscr</CODE> must be
-allocated. These function <CODE>initscr()</CODE> does both these things. Since it
-must allocate space for the windows, it can overflow memory when attempting to
-do so. On the rare occasions this happens, <CODE>initscr()</CODE> will terminate
-the program with an error message. <CODE>initscr()</CODE> 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 <CODE>curscr</CODE> or <CODE>stdscr</CODE> 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 <CODE>nl()</CODE> and <CODE>cbreak()</CODE> should be called
-after <CODE>initscr()</CODE>. <P>
-
-Once the screen windows have been allocated, you can set them up for
-your program. If you want to, say, allow a screen to scroll, use
-<CODE>scrollok()</CODE>. If you want the cursor to be left in place after
-the last change, use <CODE>leaveok()</CODE>. If this isn't done,
-<CODE>refresh()</CODE> will move the cursor to the window's current (y, x)
-coordinates after updating it. <P>
-
-You can create new windows of your own using the functions <CODE>newwin()</CODE>,
-<CODE>derwin()</CODE>, and <CODE>subwin()</CODE>. The routine <CODE>delwin()</CODE> will
-allow you to get rid of old windows. All the options described above can be
-applied to any window.
-
-<H3><A NAME="output">Output</A></H3>
-
-Now that we have set things up, we will want to actually update the terminal.
-The basic functions used to change what will go on a window are
-<CODE>addch()</CODE> and <CODE>move()</CODE>. <CODE>addch()</CODE> adds a character at the
-current (y, x) coordinates. <CODE>move()</CODE> changes the current (y, x)
-coordinates to whatever you want them to be. It returns <CODE>ERR</CODE> if you
-try to move off the window. As mentioned above, you can combine the two into
-<CODE>mvaddch()</CODE> to do both things at once. <P>
-
-The other output functions, such as <CODE>addstr()</CODE> and <CODE>printw()</CODE>,
-all call <CODE>addch()</CODE> to add characters to the window. <P>
-
-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
-<CODE>refresh()</CODE>. In order to optimize finding changes, <CODE>refresh()</CODE>
-assumes that any part of the window not changed since the last
-<CODE>refresh()</CODE> 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 <CODE>touchwin()</CODE> is provided
-to make it look like the entire window has been changed, thus making
-<CODE>refresh()</CODE> check the whole subsection of the terminal for changes. <P>
-
-If you call <CODE>wrefresh()</CODE> with <CODE>curscr</CODE> as its argument, it will
-make the screen look like <CODE>curscr</CODE> thinks it looks like. This is useful
-for implementing a command which would redraw the screen in case it get messed
-up.
-
-<H3><A NAME="input">Input</A></H3>
-
-The complementary function to <CODE>addch()</CODE> is <CODE>getch()</CODE> which, if
-echo is set, will call <CODE>addch()</CODE> 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 echoing enabled and is in ordinary ``cooked'' mode,
-one or the other has to changed before calling <CODE>getch()</CODE>; otherwise,
-the program's output will be unpredictable. <P>
-
-When you need to accept line-oriented input in a window, the functions
-<CODE>wgetstr()</CODE> and friends are available. There is even a <CODE>wscanw()</CODE>
-function that can do <CODE>scanf()</CODE>(3)-style multi-field parsing on window
-input. These pseudo-line-oriented functions turn on echoing while they
-execute. <P>
-
-The example code above uses the call <CODE>keypad(stdscr, TRUE)</CODE> to enable
-support for function-key mapping. With this feature, the <CODE>getch()</CODE> code
-watches the input stream for character sequences that correspond to arrow and
-function keys. These sequences are returned as pseudo-character values. The
-<CODE>#define</CODE> values returned are listed in the <CODE>curses.h</CODE> The
-mapping from sequences to <CODE>#define</CODE> values is determined by
-<CODE>key_</CODE> capabilities in the terminal's terminfo entry.
-
-<H3><A NAME="formschars">Using Forms Characters</A></H3>
-
-The <CODE>addch()</CODE> function (and some others, including <CODE>box()</CODE> and
-<CODE>border()</CODE>) can accept some pseudo-character arguments which are specially
-defined by <CODE>ncurses</CODE>. These are <CODE>#define</CODE> values set up in
-the <CODE>curses.h</CODE> header; see there for a complete list (look for
-the prefix <CODE>ACS_</CODE>). <P>
-
-The most useful of the ACS defines are the forms-drawing characters. You can
-use these to draw boxes and simple graphs on the screen. If the terminal
-does not have such characters, <CODE>curses.h</CODE> will map them to a
-recognizable (though ugly) set of ASCII defaults.
-
-<H3><A NAME="attributes">Character Attributes and Color</A></H3>
-
-The <CODE>ncurses</CODE> package supports screen highlights including standout,
-reverse-video, underline, and blink. It also supports color, which is treated
-as another kind of highlight. <P>
-
-Highlights are encoded, internally, as high bits of the pseudo-character type
-(<CODE>chtype</CODE>) that <CODE>curses.h</CODE> uses to represent the contents of a
-screen cell. See the <CODE>curses.h</CODE> header file for a complete list of
-highlight mask values (look for the prefix <CODE>A_</CODE>).<P>
-
-There are two ways to make highlights. One is to logical-or the value of the
-highlights you want into the character argument of an <CODE>addch()</CODE> call,
-or any other output call that takes a <CODE>chtype</CODE> argument. <P>
-
-The other is to set the current-highlight value. This is logical-or'ed with
-any highlight you specify the first way. You do this with the functions
-<CODE>attron()</CODE>, <CODE>attroff()</CODE>, and <CODE>attrset()</CODE>; see the manual
-pages for details.
-
-Color is a special kind of highlight. The package actually thinks in terms
-of color pairs, combinations of foreground and background colors. The sample
-code above sets up eight color pairs, all of the guaranteed-available colors
-on black. Note that each color pair is, in effect, given the name of its
-foreground color. Any other range of eight non-conflicting values could
-have been used as the first arguments of the <CODE>init_pair()</CODE> values. <P>
-
-Once you've done an <CODE>init_pair()</CODE> that creates color-pair N, you can
-use <CODE>COLOR_PAIR(N)</CODE> as a highlight that invokes that particular
-color combination. Note that <CODE>COLOR_PAIR(N)</CODE>, for constant N,
-is itself a compile-time constant and can be used in initializers.
-
-<H3><A NAME="mouse">Mouse Interfacing</A></H3>
-
-The <CODE>ncurses</CODE> library also provides a mouse interface.
-<!-- The 'note' tag is not portable enough -->
-<blockquote>
-<strong>NOTE:</strong> this facility is specific to <CODE>ncurses</CODE>, it is not part of either
-the XSI Curses standard, nor of System V Release 4, nor BSD curses.
-System V Release 4 curses contains code with similar interface definitions,
-however it is not documented. Other than by disassembling the library, we
-have no way to determine exactly how that mouse code works.
-Thus, we recommend that you wrap mouse-related code in an #ifdef using the
-feature macro NCURSES_MOUSE_VERSION so it will not be compiled and linked
-on non-ncurses systems.
-</blockquote>
-
-Presently, mouse event reporting works in the following environments:
-<ul>
-<li>xterm and similar programs such as rxvt.
-<li>Linux console, when configured with <CODE>gpm</CODE>(1), Alessandro
-Rubini's mouse server.
-<li>FreeBSD sysmouse (console)
-<li>OS/2 EMX
-</ul>
-<P>
-The mouse interface is very simple. To activate it, you use the function
-<CODE>mousemask()</CODE>, passing it as first argument a bit-mask that specifies
-what kinds of events you want your program to be able to see. It will
-return the bit-mask of events that actually become visible, which may differ
-from the argument if the mouse device is not capable of reporting some of
-the event types you specify. <P>
-
-Once the mouse is active, your application's command loop should watch
-for a return value of <CODE>KEY_MOUSE</CODE> from <CODE>wgetch()</CODE>. When
-you see this, a mouse event report has been queued. To pick it off
-the queue, use the function <CODE>getmouse()</CODE> (you must do this before
-the next <CODE>wgetch()</CODE>, otherwise another mouse event might come
-in and make the first one inaccessible). <P>
-
-Each call to <CODE>getmouse()</CODE> fills a structure (the address of which you'll
-pass it) with mouse event data. The event data includes zero-origin,
-screen-relative character-cell coordinates of the mouse pointer. It also
-includes an event mask. Bits in this mask will be set, corresponding
-to the event type being reported. <P>
-
-The mouse structure contains two additional fields which may be
-significant in the future as ncurses interfaces to new kinds of
-pointing device. In addition to x and y coordinates, there is a slot
-for a z coordinate; this might be useful with touch-screens that can
-return a pressure or duration parameter. There is also a device ID
-field, which could be used to distinguish between multiple pointing
-devices. <P>
-
-The class of visible events may be changed at any time via <CODE>mousemask()</CODE>.
-Events that can be reported include presses, releases, single-, double- and
-triple-clicks (you can set the maximum button-down time for clicks). If
-you don't make clicks visible, they will be reported as press-release
-pairs. In some environments, the event mask may include bits reporting
-the state of shift, alt, and ctrl keys on the keyboard during the event. <P>
-
-A function to check whether a mouse event fell within a given window is
-also supplied. You can use this to see whether a given window should
-consider a mouse event relevant to it. <P>
-
-Because mouse event reporting will not be available in all
-environments, it would be unwise to build <CODE>ncurses</CODE>
-applications that <EM>require</EM> the use of a mouse. Rather, you should
-use the mouse as a shortcut for point-and-shoot commands your application
-would normally accept from the keyboard. Two of the test games in the
-<CODE>ncurses</CODE> distribution (<CODE>bs</CODE> and <CODE>knight</CODE>) contain
-code that illustrates how this can be done. <P>
-
-See the manual page <CODE>curs_mouse(3X)</CODE> for full details of the
-mouse-interface functions.
-
-<H3><A NAME="finishing">Finishing Up</A></H3>
-
-In order to clean up after the <CODE>ncurses</CODE> routines, the routine
-<CODE>endwin()</CODE> is provided. It restores tty modes to what they were when
-<CODE>initscr()</CODE> was first called, and moves the cursor down to the
-lower-left corner. Thus, anytime after the call to initscr, <CODE>endwin()</CODE>
-should be called before exiting.
-
-<H2><A NAME="functions">Function Descriptions</A></H2>
-
-We describe the detailed behavior of some important curses functions here, as a
-supplement to the manual page descriptions.
-
-<H3><A NAME="init">Initialization and Wrapup</A></H3>
-
-<DL>
-<DT> <CODE>initscr()</CODE>
-<DD> The first function called should almost always be <CODE>initscr()</CODE>.
-This will determine the terminal type and
-initialize curses data structures. <CODE>initscr()</CODE> also arranges that
-the first call to <CODE>refresh()</CODE> will clear the screen. If an error
-occurs a message is written to standard error and the program
-exits. Otherwise it returns a pointer to stdscr. A few functions may be
-called before initscr (<CODE>slk_init()</CODE>, <CODE>filter()</CODE>,
-<CODE>ripoffline()</CODE>, <CODE>use_env()</CODE>, and, if you are using multiple
-terminals, <CODE>newterm()</CODE>.)
-<DT> <CODE>endwin()</CODE>
-<DD> Your program should always call <CODE>endwin()</CODE> 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 non-visual mode. Calling <CODE>refresh()</CODE>
-or <CODE>doupdate()</CODE> after a temporary escape from the program will
-restore the ncurses screen from before the escape.
-<DT> <CODE>newterm(type, ofp, ifp)</CODE>
-<DD> A program which outputs to more than one terminal should use
-<CODE>newterm()</CODE> instead of <CODE>initscr()</CODE>. <CODE>newterm()</CODE> should
-be called once for each terminal. It returns a variable of type
-<CODE>SCREEN *</CODE> which should be saved as a reference to that
-terminal.
-(NOTE: a SCREEN variable is not a <em>screen</em> in the sense we
-are describing in this introduction, but a collection of
-parameters used to assist in optimizing the display.)
-The arguments are the type of the terminal (a string) and
-<CODE>FILE</CODE> pointers for the output and input of the terminal. If
-type is NULL then the environment variable <CODE>$TERM</CODE> is used.
-<CODE>endwin()</CODE> should called once at wrapup time for each terminal
-opened using this function.
-<DT> <CODE>set_term(new)</CODE>
-<DD> This function is used to switch to a different terminal previously
-opened by <CODE>newterm()</CODE>. The screen reference for the new terminal
-is passed as the parameter. The previous terminal is returned by the
-function. All other calls affect only the current terminal.
-<DT> <CODE>delscreen(sp)</CODE>
-<DD> The inverse of <CODE>newterm()</CODE>; deallocates the data structures
-associated with a given <CODE>SCREEN</CODE> reference.
-</DL>
-
-<H3><A NAME="flush">Causing Output to the Terminal</A></H3>
-
-<DL>
-<DT> <CODE>refresh()</CODE> and <CODE>wrefresh(win)</CODE>
-<DD> These functions must be called to actually get any output on
-the terminal, as other routines merely manipulate data
-structures. <CODE>wrefresh()</CODE> copies the named window to the physical
-terminal screen, taking into account what is already
-there in order to do optimizations. <CODE>refresh()</CODE> does a
-refresh of <CODE>stdscr</CODE>. Unless <CODE>leaveok()</CODE> has been
-enabled, the physical cursor of the terminal is left at the
-location of the window's cursor.
-<DT> <CODE>doupdate()</CODE> and <CODE>wnoutrefresh(win)</CODE>
-<DD> These two functions allow multiple updates with more efficiency
-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
-(<CODE>wnoutrefresh()</CODE>), and then calling the routine to update the
-screen (<CODE>doupdate()</CODE>). If the programmer wishes to output
-several windows at once, a series of calls to <CODE>wrefresh</CODE> will result
-in alternating calls to <CODE>wnoutrefresh()</CODE> and <CODE>doupdate()</CODE>,
-causing several bursts of output to the screen. By calling
-<CODE>wnoutrefresh()</CODE> for each window, it is then possible to call
-<CODE>doupdate()</CODE> once, resulting in only one burst of output, with
-fewer total characters transmitted (this also avoids a visually annoying
-flicker at each update).
-</DL>
-
-<H3><A NAME="lowlevel">Low-Level Capability Access</A></H3>
-
-<DL>
-<DT> <CODE>setupterm(term, filenum, errret)</CODE>
-<DD> This routine is called to initialize a terminal's description, without setting
-up the curses screen structures or changing the tty-driver mode bits.
-<CODE>term</CODE> is the character string representing the name of the terminal
-being used. <CODE>filenum</CODE> is the UNIX file descriptor of the terminal to
-be used for output. <CODE>errret</CODE> 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). <P>
-
-The value of <CODE>term</CODE> can be given as NULL, which will cause the value of
-<CODE>TERM</CODE> in the environment to be used. The <CODE>errret</CODE> pointer can
-also be given as NULL, meaning no error code is wanted. If <CODE>errret</CODE> is
-defaulted, and something goes wrong, <CODE>setupterm()</CODE> 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. <P>
-
-After the call to <CODE>setupterm()</CODE>, the global variable <CODE>cur_term</CODE> is
-set to point to the current structure of terminal capabilities. By calling
-<CODE>setupterm()</CODE> for each terminal, and saving and restoring
-<CODE>cur_term</CODE>, it is possible for a program to use two or more terminals at
-once. <CODE>Setupterm()</CODE> also stores the names section of the terminal
-description in the global character array <CODE>ttytype[]</CODE>. Subsequent calls
-to <CODE>setupterm()</CODE> will overwrite this array, so you'll have to save it
-yourself if need be.
-</DL>
-
-<H3><A NAME="debugging">Debugging</A></H3>
-
-<!-- The 'note' tag is not portable enough -->
-<blockquote>
-<strong>NOTE:</strong> These functions are not part of the standard curses API!
-</blockquote>
-
-<DL>
-<DT> <CODE>trace()</CODE>
-<DD>
-This function can be used to explicitly set a trace level. If the
-trace level is nonzero, execution of your program will generate a file
-called `trace' in the current working directory containing a report on
-the library's actions. Higher trace levels enable more detailed (and
-verbose) reporting -- see comments attached to <CODE>TRACE_</CODE> defines
-in the <CODE>curses.h</CODE> file for details. (It is also possible to set
-a trace level by assigning a trace level value to the environment variable
-<CODE>NCURSES_TRACE</CODE>).
-<DT> <CODE>_tracef()</CODE>
-<DD>
-This function can be used to output your own debugging information. It is only
-available only if you link with -lncurses_g. It can be used the same way as
-<CODE>printf()</CODE>, only it outputs a newline after the end of arguments.
-The output goes to a file called <CODE>trace</CODE> in the current directory.
-</DL>
-
-Trace logs can be difficult to interpret due to the sheer volume of
-data dumped in them. There is a script called <STRONG>tracemunch</STRONG>
-included with the <CODE>ncurses</CODE> distribution that can alleviate
-this problem somewhat; it compacts long sequences of similar operations into
-more succinct single-line pseudo-operations. These pseudo-ops can be
-distinguished by the fact that they are named in capital letters.
-
-<H2><A NAME="hints">Hints, Tips, and Tricks</A></H2>
-
-The <CODE>ncurses</CODE> manual pages are a complete reference for this library.
-In the remainder of this document, we discuss various useful methods that
-may not be obvious from the manual page descriptions.
-
-<H3><A NAME="caution">Some Notes of Caution</A></H3>
-
-If you find yourself thinking you need to use <CODE>noraw()</CODE> or
-<CODE>nocbreak()</CODE>, think again and move carefully. It's probably
-better design to use <CODE>getstr()</CODE> or one of its relatives to
-simulate cooked mode. The <CODE>noraw()</CODE> and <CODE>nocbreak()</CODE>
-functions try to restore cooked mode, but they may end up clobbering
-some control bits set before you started your application. Also, they
-have always been poorly documented, and are likely to hurt your
-application's usability with other curses libraries. <P>
-
-Bear in mind that <CODE>refresh()</CODE> is a synonym for <CODE>wrefresh(stdscr)</CODE>.
-Don't try to mix use of <CODE>stdscr</CODE> with use of windows declared
-by <CODE>newwin()</CODE>; a <CODE>refresh()</CODE> call will blow them off the
-screen. The right way to handle this is to use <CODE>subwin()</CODE>, or
-not touch <CODE>stdscr</CODE> at all and tile your screen with declared
-windows which you then <CODE>wnoutrefresh()</CODE> somewhere in your program
-event loop, with a single <CODE>doupdate()</CODE> call to trigger actual
-repainting. <P>
-
-You are much less likely to run into problems if you design your screen
-layouts to use tiled rather than overlapping windows. Historically,
-curses support for overlapping windows has been weak, fragile, and poorly
-documented. The <CODE>ncurses</CODE> library is not yet an exception to this
-rule. <P>
-
-There is a panels library included in the <CODE>ncurses</CODE>
-distribution that does a pretty good job of strengthening the
-overlapping-windows facilities. <P>
-
-Try to avoid using the global variables LINES and COLS. Use
-<CODE>getmaxyx()</CODE> on the <CODE>stdscr</CODE> context instead. Reason:
-your code may be ported to run in an environment with window resizes,
-in which case several screens could be open with different sizes.
-
-<H3><A NAME="leaving">Temporarily Leaving NCURSES Mode</A></H3>
-
-Sometimes you will want to write a program that spends most of its time in
-screen mode, but occasionally returns to ordinary `cooked' mode. A common
-reason for this is to support shell-out. This behavior is simple to arrange
-in <CODE>ncurses</CODE>. <P>
-
-To leave <CODE>ncurses</CODE> mode, call <CODE>endwin()</CODE> as you would if you
-were intending to terminate the program. This will take the screen back to
-cooked mode; you can do your shell-out. When you want to return to
-<CODE>ncurses</CODE> mode, simply call <CODE>refresh()</CODE> or <CODE>doupdate()</CODE>.
-This will repaint the screen. <P>
-
-There is a boolean function, <CODE>isendwin()</CODE>, which code can use to
-test whether <CODE>ncurses</CODE> screen mode is active. It returns <CODE>TRUE</CODE>
-in the interval between an <CODE>endwin()</CODE> call and the following
-<CODE>refresh()</CODE>, <CODE>FALSE</CODE> otherwise. <P>
-
-Here is some sample code for shellout:
-
-<PRE>
+</pre>
+
+ <h3><a name="starting" id="starting">Starting up</a></h3>
+
+ <p>In order to use the screen package, the routines must know
+ about terminal characteristics, and the space for
+ <code>curscr</code> and <code>stdscr</code> must be allocated.
+ These function <code>initscr()</code> does both these things.
+ Since it must allocate space for the windows, it can overflow
+ memory when attempting to do so. On the rare occasions this
+ happens, <code>initscr()</code> will terminate the program with
+ an error message. <code>initscr()</code> 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
+ <code>curscr</code> or <code>stdscr</code> 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 <code>nl()</code>
+ and <code>cbreak()</code> should be called after
+ <code>initscr()</code>.</p>
+
+ <p>Once the screen windows have been allocated, you can set them
+ up for your program. If you want to, say, allow a screen to
+ scroll, use <code>scrollok()</code>. If you want the cursor to be
+ left in place after the last change, use <code>leaveok()</code>.
+ If this is not done, <code>refresh()</code> will move the cursor
+ to the window's current (y, x) coordinates after updating it.</p>
+
+ <p>You can create new windows of your own using the functions
+ <code>newwin()</code>, <code>derwin()</code>, and
+ <code>subwin()</code>. The routine <code>delwin()</code> will
+ allow you to get rid of old windows. All the options described
+ above can be applied to any window.</p>
+
+ <h3><a name="output" id="output">Output</a></h3>
+
+ <p>Now that we have set things up, we will want to actually
+ update the terminal. The basic functions used to change what will
+ go on a window are <code>addch()</code> and <code>move()</code>.
+ <code>addch()</code> adds a character at the current (y, x)
+ coordinates. <code>move()</code> changes the current (y, x)
+ coordinates to whatever you want them to be. It returns
+ <code>ERR</code> if you try to move off the window. As mentioned
+ above, you can combine the two into <code>mvaddch()</code> to do
+ both things at once.</p>
+
+ <p>The other output functions, such as <code>addstr()</code> and
+ <code>printw()</code>, all call <code>addch()</code> to add
+ characters to the window.</p>
+
+ <p>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 <code>refresh()</code>. In order
+ to optimize finding changes, <code>refresh()</code> assumes that
+ any part of the window not changed since the last
+ <code>refresh()</code> 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 <code>touchwin()</code> is provided to make it look like
+ the entire window has been changed, thus making
+ <code>refresh()</code> check the whole subsection of the terminal
+ for changes.</p>
+
+ <p>If you call <code>wrefresh()</code> with <code>curscr</code>
+ as its argument, it will make the screen look like
+ <code>curscr</code> thinks it looks like. This is useful for
+ implementing a command which would redraw the screen in case it
+ get messed up.</p>
+
+ <h3><a name="input" id="input">Input</a></h3>
+
+ <p>The complementary function to <code>addch()</code> is
+ <code>getch()</code> which, if echo is set, will call
+ <code>addch()</code> 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 echoing enabled and is in
+ ordinary “cooked” mode, one or the other has to
+ changed before calling <code>getch()</code>; otherwise, the
+ program's output will be unpredictable.</p>
+
+ <p>When you need to accept line-oriented input in a window, the
+ functions <code>wgetstr()</code> and friends are available. There
+ is even a <code>wscanw()</code> function that can do
+ <code>scanf()</code>(3)-style multi-field parsing on window
+ input. These pseudo-line-oriented functions turn on echoing while
+ they execute.</p>
+
+ <p>The example code above uses the call <code>keypad(stdscr,
+ TRUE)</code> to enable support for function-key mapping. With
+ this feature, the <code>getch()</code> code watches the input
+ stream for character sequences that correspond to arrow and
+ function keys. These sequences are returned as pseudo-character
+ values. The <code>#define</code> values returned are listed in
+ the <code>curses.h</code> The mapping from sequences to
+ <code>#define</code> values is determined by <code>key_</code>
+ capabilities in the terminal's terminfo entry.</p>
+
+ <h3><a name="formschars" id="formschars">Using Forms
+ Characters</a></h3>
+
+ <p>The <code>addch()</code> function (and some others, including
+ <code>box()</code> and <code>border()</code>) can accept some
+ pseudo-character arguments which are specially defined by
+ <code>ncurses</code>. These are <code>#define</code> values set
+ up in the <code>curses.h</code> header; see there for a complete
+ list (look for the prefix <code>ACS_</code>).</p>
+
+ <p>The most useful of the ACS defines are the forms-drawing
+ characters. You can use these to draw boxes and simple graphs on
+ the screen. If the terminal does not have such characters,
+ <code>curses.h</code> will map them to a recognizable (though
+ ugly) set of ASCII defaults.</p>
+
+ <h3><a name="attributes" id="attributes">Character Attributes and
+ Color</a></h3>
+
+ <p>The <code>ncurses</code> package supports screen highlights
+ including standout, reverse-video, underline, and blink. It also
+ supports color, which is treated as another kind of
+ highlight.</p>
+
+ <p>Highlights are encoded, internally, as high bits of the
+ pseudo-character type (<code>chtype</code>) that
+ <code>curses.h</code> uses to represent the contents of a screen
+ cell. See the <code>curses.h</code> header file for a complete
+ list of highlight mask values (look for the prefix
+ <code>A_</code>).</p>
+
+ <p>There are two ways to make highlights. One is to logical-or
+ the value of the highlights you want into the character argument
+ of an <code>addch()</code> call, or any other output call that
+ takes a <code>chtype</code> argument.</p>
+
+ <p>The other is to set the current-highlight value. This is
+ <em>logical-OR</em>ed with any highlight you specify the first
+ way. You do this with the functions <code>attron()</code>,
+ <code>attroff()</code>, and <code>attrset()</code>; see the
+ manual pages for details. Color is a special kind of highlight.
+ The package actually thinks in terms of color pairs, combinations
+ of foreground and background colors. The sample code above sets
+ up eight color pairs, all of the guaranteed-available colors on
+ black. Note that each color pair is, in effect, given the name of
+ its foreground color. Any other range of eight non-conflicting
+ values could have been used as the first arguments of the
+ <code>init_pair()</code> values.</p>
+
+ <p>Once you have done an <code>init_pair()</code> that creates
+ color-pair N, you can use <code>COLOR_PAIR(N)</code> as a
+ highlight that invokes that particular color combination. Note
+ that <code>COLOR_PAIR(N)</code>, for constant N, is itself a
+ compile-time constant and can be used in initializers.</p>
+
+ <h3><a name="mouse" id="mouse">Mouse Interfacing</a></h3>
+
+ <p>The <code>ncurses</code> library also provides a mouse
+ interface.</p>
+
+ <blockquote>
+ <strong>NOTE:</strong> this facility is specific to
+ <code>ncurses</code>, it is not part of either the XSI Curses
+ standard, nor of System V Release 4, nor BSD curses. System V
+ Release 4 curses contains code with similar interface
+ definitions, however it is not documented. Other than by
+ disassembling the library, we have no way to determine exactly
+ how that mouse code works. Thus, we recommend that you wrap
+ mouse-related code in an #ifdef using the feature macro
+ NCURSES_MOUSE_VERSION so it will not be compiled and linked on
+ non-ncurses systems.
+ </blockquote>
+
+ <p>Presently, mouse event reporting works in the following
+ environments:</p>
+
+ <ul>
+ <li>xterm and similar programs such as rxvt.</li>
+
+ <li>Linux console, when configured with <code>gpm</code>(1),
+ Alessandro Rubini's mouse server.</li>
+
+ <li>FreeBSD sysmouse (console)</li>
+
+ <li>OS/2 EMX</li>
+ </ul>
+
+ <p>The mouse interface is very simple. To activate it, you use
+ the function <code>mousemask()</code>, passing it as first
+ argument a bit-mask that specifies what kinds of events you want
+ your program to be able to see. It will return the bit-mask of
+ events that actually become visible, which may differ from the
+ argument if the mouse device is not capable of reporting some of
+ the event types you specify.</p>
+
+ <p>Once the mouse is active, your application's command loop
+ should watch for a return value of <code>KEY_MOUSE</code> from
+ <code>wgetch()</code>. When you see this, a mouse event report
+ has been queued. To pick it off the queue, use the function
+ <code>getmouse()</code> (you must do this before the next
+ <code>wgetch()</code>, otherwise another mouse event might come
+ in and make the first one inaccessible).</p>
+
+ <p>Each call to <code>getmouse()</code> fills a structure (the
+ address of which you will pass it) with mouse event data. The
+ event data includes zero-origin, screen-relative character-cell
+ coordinates of the mouse pointer. It also includes an event mask.
+ Bits in this mask will be set, corresponding to the event type
+ being reported.</p>
+
+ <p>The mouse structure contains two additional fields which may
+ be significant in the future as ncurses interfaces to new kinds
+ of pointing device. In addition to x and y coordinates, there is
+ a slot for a z coordinate; this might be useful with
+ touch-screens that can return a pressure or duration parameter.
+ There is also a device ID field, which could be used to
+ distinguish between multiple pointing devices.</p>
+
+ <p>The class of visible events may be changed at any time via
+ <code>mousemask()</code>. Events that can be reported include
+ presses, releases, single-, double- and triple-clicks (you can
+ set the maximum button-down time for clicks). If you do not make
+ clicks visible, they will be reported as press-release pairs. In
+ some environments, the event mask may include bits reporting the
+ state of shift, alt, and ctrl keys on the keyboard during the
+ event.</p>
+
+ <p>A function to check whether a mouse event fell within a given
+ window is also supplied. You can use this to see whether a given
+ window should consider a mouse event relevant to it.</p>
+
+ <p>Because mouse event reporting will not be available in all
+ environments, it would be unwise to build <code>ncurses</code>
+ applications that <em>require</em> the use of a mouse. Rather,
+ you should use the mouse as a shortcut for point-and-shoot
+ commands your application would normally accept from the
+ keyboard. Two of the test games in the <code>ncurses</code>
+ distribution (<code>bs</code> and <code>knight</code>) contain
+ code that illustrates how this can be done.</p>
+
+ <p>See the manual page <code>curs_mouse(3X)</code> for full
+ details of the mouse-interface functions.</p>
+
+ <h3><a name="finishing" id="finishing">Finishing Up</a></h3>
+
+ <p>In order to clean up after the <code>ncurses</code> routines,
+ the routine <code>endwin()</code> is provided. It restores tty
+ modes to what they were when <code>initscr()</code> was first
+ called, and moves the cursor down to the lower-left corner. Thus,
+ anytime after the call to initscr, <code>endwin()</code> should
+ be called before exiting.</p>
+
+ <h2><a name="functions" id="functions">Function
+ Descriptions</a></h2>
+
+ <p>We describe the detailed behavior of some important curses
+ functions here, as a supplement to the manual page
+ descriptions.</p>
+
+ <h3><a name="init" id="init">Initialization and Wrapup</a></h3>
+
+ <dl>
+ <dt><code>initscr()</code></dt>
+
+ <dd>The first function called should almost always be
+ <code>initscr()</code>. This will determine the terminal type
+ and initialize curses data structures. <code>initscr()</code>
+ also arranges that the first call to <code>refresh()</code>
+ will clear the screen. If an error occurs a message is written
+ to standard error and the program exits. Otherwise it returns a
+ pointer to stdscr. A few functions may be called before initscr
+ (<code>slk_init()</code>, <code>filter()</code>,
+ <code>ripoffline()</code>, <code>use_env()</code>, and, if you
+ are using multiple terminals, <code>newterm()</code>.)</dd>
+
+ <dt><code>endwin()</code></dt>
+
+ <dd>Your program should always call <code>endwin()</code>
+ 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
+ non-visual mode. Calling <code>refresh()</code> or
+ <code>doupdate()</code> after a temporary escape from the
+ program will restore the ncurses screen from before the
+ escape.</dd>
+
+ <dt><code>newterm(type, ofp, ifp)</code></dt>
+
+ <dd>A program which outputs to more than one terminal should
+ use <code>newterm()</code> instead of <code>initscr()</code>.
+ <code>newterm()</code> should be called once for each terminal.
+ It returns a variable of type <code>SCREEN *</code> which
+ should be saved as a reference to that terminal. (NOTE: a
+ SCREEN variable is not a <em>screen</em> in the sense we are
+ describing in this introduction, but a collection of parameters
+ used to assist in optimizing the display.) The arguments are
+ the type of the terminal (a string) and <code>FILE</code>
+ pointers for the output and input of the terminal. If type is
+ NULL then the environment variable <code>$TERM</code> is used.
+ <code>endwin()</code> should called once at wrapup time for
+ each terminal opened using this function.</dd>
+
+ <dt><code>set_term(new)</code></dt>
+
+ <dd>This function is used to switch to a different terminal
+ previously opened by <code>newterm()</code>. The screen
+ reference for the new terminal is passed as the parameter. The
+ previous terminal is returned by the function. All other calls
+ affect only the current terminal.</dd>
+
+ <dt><code>delscreen(sp)</code></dt>
+
+ <dd>The inverse of <code>newterm()</code>; deallocates the data
+ structures associated with a given <code>SCREEN</code>
+ reference.</dd>
+ </dl>
+
+ <h3><a name="flush" id="flush">Causing Output to the
+ Terminal</a></h3>
+
+ <dl>
+ <dt><code>refresh()</code> and <code>wrefresh(win)</code></dt>
+
+ <dd>These functions must be called to actually get any output
+ on the terminal, as other routines merely manipulate data
+ structures. <code>wrefresh()</code> copies the named window to
+ the physical terminal screen, taking into account what is
+ already there in order to do optimizations.
+ <code>refresh()</code> does a refresh of <code>stdscr</code>.
+ Unless <code>leaveok()</code> has been enabled, the physical
+ cursor of the terminal is left at the location of the window's
+ cursor.</dd>
+
+ <dt><code>doupdate()</code> and
+ <code>wnoutrefresh(win)</code></dt>
+
+ <dd>These two functions allow multiple updates with more
+ efficiency 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
+ (<code>wnoutrefresh()</code>), and then calling the routine to
+ update the screen (<code>doupdate()</code>). If the programmer
+ wishes to output several windows at once, a series of calls to
+ <code>wrefresh</code> will result in alternating calls to
+ <code>wnoutrefresh()</code> and <code>doupdate()</code>,
+ causing several bursts of output to the screen. By calling
+ <code>wnoutrefresh()</code> for each window, it is then
+ possible to call <code>doupdate()</code> once, resulting in
+ only one burst of output, with fewer total characters
+ transmitted (this also avoids a visually annoying flicker at
+ each update).</dd>
+ </dl>
+
+ <h3><a name="lowlevel" id="lowlevel">Low-Level Capability
+ Access</a></h3>
+
+ <dl>
+ <dt><code>setupterm(term, filenum, errret)</code></dt>
+
+ <dd>
+ This routine is called to initialize a terminal's
+ description, without setting up the curses screen structures
+ or changing the tty-driver mode bits. <code>term</code> is
+ the character string representing the name of the terminal
+ being used. <code>filenum</code> is the UNIX file descriptor
+ of the terminal to be used for output. <code>errret</code> 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).
+
+ <p>The value of <code>term</code> can be given as NULL, which
+ will cause the value of <code>TERM</code> in the environment
+ to be used. The <code>errret</code> pointer can also be given
+ as NULL, meaning no error code is wanted. If
+ <code>errret</code> is defaulted, and something goes wrong,
+ <code>setupterm()</code> 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.</p>
+
+ <p>After the call to <code>setupterm()</code>, the global
+ variable <code>cur_term</code> is set to point to the current
+ structure of terminal capabilities. By calling
+ <code>setupterm()</code> for each terminal, and saving and
+ restoring <code>cur_term</code>, it is possible for a program
+ to use two or more terminals at once.
+ <code>Setupterm()</code> also stores the names section of the
+ terminal description in the global character array
+ <code>ttytype[]</code>. Subsequent calls to
+ <code>setupterm()</code> will overwrite this array, so you
+ will have to save it yourself if need be.</p>
+ </dd>
+ </dl>
+
+ <h3><a name="debugging" id="debugging">Debugging</a></h3>
+
+ <blockquote>
+ <strong>NOTE:</strong> These functions are not part of the
+ standard curses API!
+ </blockquote>
+
+ <dl>
+ <dt><code>trace()</code></dt>
+
+ <dd>This function can be used to explicitly set a trace level.
+ If the trace level is nonzero, execution of your program will
+ generate a file called “trace” in the current
+ working directory containing a report on the library's actions.
+ Higher trace levels enable more detailed (and verbose)
+ reporting -- see comments attached to <code>TRACE_</code>
+ defines in the <code>curses.h</code> file for details. (It is
+ also possible to set a trace level by assigning a trace level
+ value to the environment variable
+ <code>NCURSES_TRACE</code>).</dd>
+
+ <dt><code>_tracef()</code></dt>
+
+ <dd>This function can be used to output your own debugging
+ information. It is only available only if you link with
+ -lncurses_g. It can be used the same way as
+ <code>printf()</code>, only it outputs a newline after the end
+ of arguments. The output goes to a file called
+ <code>trace</code> in the current directory.</dd>
+ </dl>
+
+ <p>Trace logs can be difficult to interpret due to the sheer
+ volume of data dumped in them. There is a script called
+ <strong>tracemunch</strong> included with the
+ <code>ncurses</code> distribution that can alleviate this problem
+ somewhat; it compacts long sequences of similar operations into
+ more succinct single-line pseudo-operations. These pseudo-ops can
+ be distinguished by the fact that they are named in capital
+ letters.</p>
+
+ <h2><a name="hints" id="hints">Hints, Tips, and Tricks</a></h2>
+
+ <p>The <code>ncurses</code> manual pages are a complete reference
+ for this library. In the remainder of this document, we discuss
+ various useful methods that may not be obvious from the manual
+ page descriptions.</p>
+
+ <h3><a name="caution" id="caution">Some Notes of Caution</a></h3>
+
+ <p>If you find yourself thinking you need to use
+ <code>noraw()</code> or <code>nocbreak()</code>, think again and
+ move carefully. It is probably better design to use
+ <code>getstr()</code> or one of its relatives to simulate cooked
+ mode. The <code>noraw()</code> and <code>nocbreak()</code>
+ functions try to restore cooked mode, but they may end up
+ clobbering some control bits set before you started your
+ application. Also, they have always been poorly documented, and
+ are likely to hurt your application's usability with other curses
+ libraries.</p>
+
+ <p>Bear in mind that <code>refresh()</code> is a synonym for
+ <code>wrefresh(stdscr)</code>. Do not try to mix use of
+ <code>stdscr</code> with use of windows declared by
+ <code>newwin()</code>; a <code>refresh()</code> call will blow
+ them off the screen. The right way to handle this is to use
+ <code>subwin()</code>, or not touch <code>stdscr</code> at all
+ and tile your screen with declared windows which you then
+ <code>wnoutrefresh()</code> somewhere in your program event loop,
+ with a single <code>doupdate()</code> call to trigger actual
+ repainting.</p>
+
+ <p>You are much less likely to run into problems if you design
+ your screen layouts to use tiled rather than overlapping windows.
+ Historically, curses support for overlapping windows has been
+ weak, fragile, and poorly documented. The <code>ncurses</code>
+ library is not yet an exception to this rule.</p>
+
+ <p>There is a panels library included in the <code>ncurses</code>
+ distribution that does a pretty good job of strengthening the
+ overlapping-windows facilities.</p>
+
+ <p>Try to avoid using the global variables LINES and COLS. Use
+ <code>getmaxyx()</code> on the <code>stdscr</code> context
+ instead. Reason: your code may be ported to run in an environment
+ with window resizes, in which case several screens could be open
+ with different sizes.</p>
+
+ <h3><a name="leaving" id="leaving">Temporarily Leaving NCURSES
+ Mode</a></h3>
+
+ <p>Sometimes you will want to write a program that spends most of
+ its time in screen mode, but occasionally returns to ordinary
+ “cooked” mode. A common reason for this is to support
+ shell-out. This behavior is simple to arrange in
+ <code>ncurses</code>.</p>
+
+ <p>To leave <code>ncurses</code> mode, call <code>endwin()</code>
+ as you would if you were intending to terminate the program. This
+ will take the screen back to cooked mode; you can do your
+ shell-out. When you want to return to <code>ncurses</code> mode,
+ simply call <code>refresh()</code> or <code>doupdate()</code>.
+ This will repaint the screen.</p>
+
+ <p>There is a boolean function, <code>isendwin()</code>, which
+ code can use to test whether <code>ncurses</code> screen mode is
+ active. It returns <code>TRUE</code> in the interval between an
+ <code>endwin()</code> call and the following
+ <code>refresh()</code>, <code>FALSE</code> otherwise.</p>
+
+ <p>Here is some sample code for shellout:</p>
+ <pre>