ncurses-intro.doc

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

   inaccessible).

   Each call to getmouse() 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.

   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.

   The   class  of  visible  events  may  be  changed  at  any  time  via
   mousemask().  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.

   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.

   Because   mouse   event   reporting  will  not  be  available  in  all
   environments,  it  would  be unwise to build ncurses applications that
   require  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 ncurses
   distribution  (bs  and  knight) contain code that illustrates how this
   can be done.

   See   the   manual   page  curs_mouse(3X)  for  full  details  of  the
   mouse-interface functions.

  Finishing Up

   In  order to clean up after the ncurses routines, the routine endwin()
   is  provided.  It  restores tty modes to what they were when initscr()
   was  first called, and moves the cursor down to the lower-left corner.
   Thus,  anytime  after  the  call to initscr, endwin() should be called
   before exiting.

Function Descriptions

   We  describe  the detailed behavior of some important curses functions
   here, as a supplement to the manual page descriptions.

  Initialization and Wrapup

   initscr()
          The  first  function  called should almost always be initscr().
          This  will  determine  the  terminal type and initialize curses
          data structures. initscr() also arranges that the first call to
          refresh()  will  clear the screen. If an error occurs a message
          is  written  to standard error and the program exits. Otherwise
          it  returns  a pointer to stdscr. A few functions may be called
          before initscr (slk_init(), filter(), ripofflines(), use_env(),
          and, if you are using multiple terminals, newterm().)

   endwin()
          Your  program  should  always  call  endwin() before exiting or
          shelling  out  of  the  program. This function will restore tty
          modes,  move the cursor to the lower left corner of the screen,
          reset  the  terminal  into  the proper non-visual mode. Calling
          refresh()  or  doupdate()  after  a  temporary  escape from the
          program will restore the ncurses screen from before the escape.

   newterm(type, ofp, ifp)
          A  program  which  outputs to more than one terminal should use
          newterm() instead of initscr(). newterm() should be called once
          for each terminal. It returns a variable of type SCREEN * which
          should  be  saved  as  a  reference  to that terminal. (NOTE: a
          SCREEN  variable is not a screen 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 FILE pointers for the output and
          input  of  the  terminal.  If type is NULL then the environment
          variable  $TERM  is used. endwin() should called once at wrapup
          time for each terminal opened using this function.

   set_term(new)
          This  function  is  used  to  switch  to  a  different terminal
          previously  opened  by  newterm(). 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.

   delscreen(sp)
          The  inverse  of  newterm();  deallocates  the  data structures
          associated with a given SCREEN reference.

  Causing Output to the Terminal

   refresh() and wrefresh(win)
          These  functions  must  be called to actually get any output on
          the   terminal,   as  other  routines  merely  manipulate  data
          structures.  wrefresh() copies the named window to the physical
          terminal  screen,  taking into account what is already there in
          order   to  do  optimizations.  refresh()  does  a  refresh  of
          stdscr().  Unless  leaveok()  has  been  enabled,  the physical
          cursor  of the terminal is left at the location of the window's
          cursor.

   doupdate() and wnoutrefresh(win)
          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 (wnoutrefresh()), and then calling the
          routine  to  update  the screen (doupdate()). If the programmer
          wishes  to output several windows at once, a series of calls to
          wrefresh will result in alternating calls to wnoutrefresh() and
          doupdate(),  causing several bursts of output to the screen. By
          calling  wnoutrefresh() for each window, it is then possible to
          call  doupdate()  once,  resulting in only one burst of output,
          with  fewer  total  characters  transmitted (this also avoids a
          visually annoying flicker at each update).

  Low-Level Capability Access

   setupterm(term, filenum, errret)
          This  routine is called to initialize a terminal's description,
          without setting up the curses screen structures or changing the
          tty-driver mode bits. term is the character string representing
          the  name  of the terminal being used. filenum is the UNIX file
          descriptor  of  the terminal to be used for output. errret is a
          pointer to an integer, in which a success or failure indication
          is  returned. The values returned can be 1 (all is well), 0 (no
          such  terminal),  or  -1  (some  problem  locating the terminfo
          database).

          The  value  of  term can be given as NULL, which will cause the
          value of TERM in the environment to be used. The errret pointer
          can  also be given as NULL, meaning no error code is wanted. If
          errret is defaulted, and something goes wrong, setupterm() will
          print  an  appropriate  error  message  and  exit,  rather than
          returning.  Thus,  a simple program can call setupterm(0, 1, 0)
          and not worry about initialization errors.

          After  the call to setupterm(), the global variable cur_term is
          set to point to the current structure of terminal capabilities.
          By  calling  setupterm()  for  each  terminal,  and  saving and
          restoring  cur_term, it is possible for a program to use two or
          more  terminals  at  once.  Setupterm()  also  stores the names
          section  of  the  terminal  description in the global character
          array ttytype[]. Subsequent calls to setupterm() will overwrite
          this array, so you'll have to save it yourself if need be.

  Debugging

     NOTE: These functions are not part of the standard curses API!

   trace()
          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  TRACE_ defines in the curses.h file for
          details. (It is also possible to set a trace level by assigning
          a trace level value to the environment variable NCURSES_TRACE).

   _tracef()
          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 printf(), only it
          outputs  a  newline after the end of arguments. The output goes
          to a file called trace in the current directory.

   Trace  logs  can  be difficult to interpret due to the sheer volume of
   data dumped in them. There is a script called tracemunch included with
   the  ncurses 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.

Hints, Tips, and Tricks

   The ncurses 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.

  Some Notes of Caution

   If  you  find yourself thinking you need to use noraw() or nocbreak(),
   think  again  and  move  carefully. It's probably better design to use
   getstr()  or one of its relatives to simulate cooked mode. The noraw()
   and  nocbreak() 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.

   Bear  in  mind that refresh() is a synonym for wrefresh(stdscr). Don't
   try  to  mix use of stdscr with use of windows declared by newwin(); a
   refresh()  call will blow them off the screen. The right way to handle
   this  is  to  use  subwin(),  or not touch stdscr at all and tile your
   screen  with  declared windows which you then wnoutrefresh() somewhere
   in  your  program event loop, with a single doupdate() call to trigger
   actual repainting.

   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  ncurses library is not yet an
   exception to this rule.

   There  is  a  panels library included in the ncurses distribution that
   does  a  pretty  good  job  of  strengthening  the overlapping-windows
   facilities.

   Try to avoid using the global variables LINES and COLS. Use getmaxyx()
   on  the stdscr 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.

  Temporarily Leaving NCURSES Mode

   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 ncurses.

   To  leave  ncurses  mode,  call  endwin()  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
   ncurses  mode,  simply call refresh() or doupdate(). This will repaint
   the screen.

   There  is  a  boolean function, isendwin(), which code can use to test
   whether ncurses screen mode is active. It returns TRUE in the interval
   between an endwin() call and the following refresh(), FALSE otherwise.

   Here is some sample code for shellout:
    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 */

  Using NCURSES under XTERM

   A  resize  operation  in  X  sends SIGWINCH to the application running
   under  xterm.  The  ncurses  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.

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

   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.   Ncurses  provides  an  extension  which  works  better,  the
   resizeterm  function.  That  function  ensures  that  all  windows are
   limited  to  the new screen dimensions, and pads stdscr with blanks if
   the screen is larger.

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

  Handling Multiple Terminal Screens