ncurses-intro.html

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

<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>ripofflines()</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