ncurses-intro.html

ncurses-5.4 需要的就来下把 一定会有用的哦

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>
    addstr("Shelling out...");
    def_prog_mode();           /* save current tty modes */
    endwin();                  /* restore original tty modes */
    system("sh");              /* run shell */
    addstr("returned.\n");     /* prepare return message */
    refresh();                 /* restore save modes, repaint screen */
</PRE>

<H3><A NAME="xterm">Using NCURSES under XTERM</A></H3>

A resize operation in X sends SIGWINCH to the application running under xterm.
The <CODE>ncurses</CODE> library provides an experimental signal
handler, but in general does not catch this signal, because it cannot
know how you want the screen re-painted.  You will usually have to write the
SIGWINCH handler yourself.  Ncurses can give you some help. <P>

The easiest way to code your SIGWINCH handler is to have it do an
<CODE>endwin</CODE>, followed by an <CODE>refresh</CODE> and a screen repaint you code
yourself.  The <CODE>refresh</CODE> will pick up the new screen size from the
xterm's environment. <P>

That is the standard way, of course (it even works with some vendor's curses
implementations).
Its drawback is that it clears the screen to reinitialize the display, and does
not resize subwindows which must be shrunk.
<CODE>Ncurses</CODE> provides an extension which works better, the
<CODE>resizeterm</CODE> function.  That function ensures that all windows
are limited to the new screen dimensions, and pads <CODE>stdscr</CODE>
with blanks if the screen is larger. <P>

Finally, ncurses can be configured to provide its own SIGWINCH handler,
based on <CODE>resizeterm</CODE>.

<H3><A NAME="screens">Handling Multiple Terminal Screens</A></H3>

The <CODE>initscr()</CODE> function actually calls a function named
<CODE>newterm()</CODE> to do most of its work.  If you are writing a program that
opens multiple terminals, use <CODE>newterm()</CODE> directly. <P>

For each call, you will have to specify a terminal type and a pair of file
pointers; each call will return a screen reference, and <CODE>stdscr</CODE> will be
set to the last one allocated.  You will switch between screens with the
<CODE>set_term</CODE> call.  Note that you will also have to call
<CODE>def_shell_mode</CODE> and <CODE>def_prog_mode</CODE> on each tty yourself.

<H3><A NAME="testing">Testing for Terminal Capabilities</A></H3>

Sometimes you may want to write programs that test for the presence of various
capabilities before deciding whether to go into <CODE>ncurses</CODE> mode.  An easy
way to do this is to call <CODE>setupterm()</CODE>, then use the functions
<CODE>tigetflag()</CODE>, <CODE>tigetnum()</CODE>, and <CODE>tigetstr()</CODE> to do your
testing. <P>

A particularly useful case of this often comes up when you want to
test whether a given terminal type should be treated as `smart'
(cursor-addressable) or `stupid'.  The right way to test this is to see
if the return value of <CODE>tigetstr("cup")</CODE> is non-NULL.  Alternatively,
you can include the <CODE>term.h</CODE> file and test the value of the
macro <CODE>cursor_address</CODE>.

<H3><A NAME="tuning">Tuning for Speed</A></H3>

Use the <CODE>addchstr()</CODE> family of functions for fast
screen-painting of text when you know the text doesn't contain any
control characters.  Try to make attribute changes infrequent on your
screens.  Don't use the <CODE>immedok()</CODE> option!

<H3><A NAME="special">Special Features of NCURSES</A></H3>

The <CODE>wresize()</CODE> function allows you to resize a window in place.
The associated <CODE>resizeterm()</CODE> function simplifies the construction
of <a HREF="#xterm">SIGWINCH</a> handlers, for resizing all windows.  <P>

The <CODE>define_key()</CODE> function allows you
to define at runtime function-key control sequences which are not in the
terminal description.
The <CODE>keyok()</CODE> function allows you to temporarily
enable or disable interpretation of any function-key control sequence. <P>

The <CODE>use_default_colors()</CODE> function allows you to construct
applications which can use the terminal's default foreground and
background colors as an additional "default" color.
Several terminal emulators support this feature, which is based on ISO 6429. <P>

Ncurses supports up 16 colors, unlike SVr4 curses which defines only 8.
While most terminals which provide color allow only 8 colors, about
a quarter (including XFree86 xterm) support 16 colors.

<H2><A NAME="compat">Compatibility with Older Versions</A></H2>

Despite our best efforts, there are some differences between <CODE>ncurses</CODE>
and the (undocumented!) behavior of older curses implementations.  These arise
from ambiguities or omissions in the documentation of the API.

<H3><A NAME="refbug">Refresh of Overlapping Windows</A></H3>

If you define two windows A and B that overlap, and then alternately scribble
on and refresh them, the changes made to the overlapping region under historic
<CODE>curses</CODE> versions were often not documented precisely. <P>

To understand why this is a problem, remember that screen updates are
calculated between two representations of the <EM>entire</EM> display. The
documentation says that when you refresh a window, it is first copied to to the
virtual screen, and then changes are calculated to update the physical screen
(and applied to the terminal).  But "copied to" is not very specific, and
subtle differences in how copying works can produce different behaviors in the
case where two overlapping windows are each being refreshed at unpredictable
intervals. <P>

What happens to the overlapping region depends on what <CODE>wnoutrefresh()</CODE>
does with its argument -- what portions of the argument window it copies to the
virtual screen.  Some implementations do "change copy", copying down only
locations in the window that have changed (or been marked changed with
<CODE>wtouchln()</CODE> and friends).  Some implementations do  "entire copy",
copying <EM>all</EM> window locations to the virtual screen whether or not
they have changed. <P>

The <CODE>ncurses</CODE> library itself has not always been consistent on this
score.  Due to a bug, versions 1.8.7 to 1.9.8a did entire copy.  Versions
1.8.6 and older, and versions 1.9.9 and newer, do change copy. <P>

For most commercial curses implementations, it is not documented and not known
for sure (at least not to the <CODE>ncurses</CODE> maintainers) whether they do
change copy or entire copy.  We know that System V release 3 curses has logic
in it that looks like an attempt to do change copy, but the surrounding logic
and data representations are sufficiently complex, and our knowledge
sufficiently indirect, that it's hard to know whether this is reliable.

It is not clear what the SVr4 documentation and XSI standard intend.  The XSI
Curses standard barely mentions wnoutrefresh(); the SVr4 documents seem to be
describing entire-copy, but it is possible with some effort and straining to
read them the other way. <P>

It might therefore be unwise to rely on either behavior in programs that might
have to be linked with other curses implementations.  Instead, you can do an
explicit <CODE>touchwin()</CODE> before the <CODE>wnoutrefresh()</CODE> call to
guarantee an entire-contents copy anywhere. <P>

The really clean way to handle this is to use the panels library.  If,
when you want a screen update, you do <CODE>update_panels()</CODE>, it will
do all the necessary <CODE>wnoutrfresh()</CODE> calls for whatever panel
stacking order you have defined.  Then you can do one <CODE>doupdate()</CODE>
and there will be a <EM>single</EM> burst of physical I/O that will do
all your updates.

<H3><A NAME="backbug">Background Erase</A></H3>

If you have been using a very old versions of <CODE>ncurses</CODE> (1.8.7 or
older) you may be surprised by the behavior of the erase functions.  In older
versions, erased areas of a window were filled with a blank modified by the
window's current attribute (as set by <STRONG>wattrset()</STRONG>, <STRONG>wattron()</STRONG>,
<STRONG>wattroff()</STRONG> and friends). <P>

In newer versions, this is not so.  Instead, the attribute of erased blanks
is normal unless and until it is modified by the functions <CODE>bkgdset()</CODE>
or <CODE>wbkgdset()</CODE>. <P>

This change in behavior conforms <CODE>ncurses</CODE> to System V Release 4 and
the XSI Curses standard.

<H2><A NAME="xsifuncs">XSI Curses Conformance</A></H2>

The <CODE>ncurses</CODE> library is intended to be base-level conformant with the
XSI Curses standard from X/Open.  Many extended-level features (in fact, almost
all features not directly concerned with wide characters and
internationalization) are also supported. <P>

One effect of XSI conformance is the change in behavior described under
<A HREF="#backbug">"Background Erase -- Compatibility with Old Versions"</A>. <P>

Also, <CODE>ncurses</CODE> meets the XSI requirement that every macro
entry point have a corresponding function which may be linked (and
will be prototype-checked) if the macro definition is disabled with
<CODE>#undef</CODE>.

<H1><A NAME="panels">The Panels Library</A></H1>

The <CODE>ncurses</CODE> library by itself provides good support for screen
displays in which the windows are tiled (non-overlapping).  In the more
general case that windows may overlap, you have to use a series of
<CODE>wnoutrefresh()</CODE> calls followed by a <CODE>doupdate()</CODE>, and be
careful about the order you do the window refreshes in.  It has to be
bottom-upwards, otherwise parts of windows that should be obscured will
show through. <P>

When your interface design is such that windows may dive deeper into the
visibility stack or pop to the top at runtime, the resulting book-keeping
can be tedious and difficult to get right.  Hence the panels library. <P>

The <CODE>panel</CODE> library first appeared in AT&amp;T System V.  The
version documented here is the <CODE>panel</CODE> code distributed
with <CODE>ncurses</CODE>.

<H2><A NAME="pcompile">Compiling With the Panels Library</A></H2>

Your panels-using modules must import the panels library declarations with

<PRE>
	  #include &lt;panel.h&gt;
</PRE>

and must be linked explicitly with the panels library using an
<CODE>-lpanel</CODE> argument.  Note that they must also link the
<CODE>ncurses</CODE> library with <CODE>-lncurses</CODE>.  Many linkers
are two-pass and will accept either order, but it is still good practice
to put <CODE>-lpanel</CODE> first and <CODE>-lncurses</CODE> second.

<H2><A NAME="poverview">Overview of Panels</A></H2>

A panel object is a window that is implicitly treated as part of a
<DFN>deck</DFN> including all other panel objects.  The deck has an implicit
bottom-to-top visibility order.  The panels library includes an update
function (analogous to <CODE>refresh()</CODE>) that displays all panels in the
deck in the proper order to resolve overlaps.  The standard window,
<CODE>stdscr</CODE>, is considered below all panels. <P>

Details on the panels functions are available in the man pages.  We'll just
hit the highlights here. <P>

You create a panel from a window by calling <CODE>new_panel()</CODE> on a
window pointer.  It then becomes the top of the deck.  The panel's window
is available as the value of <CODE>panel_window()</CODE> called with the
panel pointer as argument.<P>

You can delete a panel (removing it from the deck) with <CODE>del_panel</CODE>.
This will not deallocate the associated window; you have to do that yourself.

You can replace a panel's window with a different window by calling
<CODE>replace_window</CODE>.  The new window may be of different size;
the panel code will re-compute all overlaps.  This operation doesn't
change the panel's position in the deck. <P>

To move a panel's window, use <CODE>move_panel()</CODE>.  The
<CODE>mvwin()</CODE> function on the panel's window isn't sufficient because it
doesn't update the panels library's representation of where the windows are.
This operation leaves the panel's depth, contents, and size unchanged. <P>