ncurses-intro.doc

ncurses 库 可能有用酒用 没用就算了 我觉得还可以用

                         Writing Programs with NCURSES

     by Eric S. Raymond and Zeyd M. Ben-Halim
     updates since release 1.9.9e by Thomas Dickey

                                   Contents

     * Introduction
          + A Brief History of Curses
          + Scope of This Document
          + Terminology
     * The Curses Library
          + An Overview of Curses
               o Compiling Programs using Curses
               o Updating the Screen
               o Standard Windows and Function Naming Conventions
               o Variables
          + Using the Library
               o Starting up
               o Output
               o Input
               o Using Forms Characters
               o Character Attributes and Color
               o Mouse Interfacing
               o Finishing Up
          + Function Descriptions
               o Initialization and Wrapup
               o Causing Output to the Terminal
               o Low-Level Capability Access
               o Debugging
          + Hints, Tips, and Tricks
               o Some Notes of Caution
               o Temporarily Leaving ncurses Mode
               o Using ncurses under xterm
               o Handling Multiple Terminal Screens
               o Testing for Terminal Capabilities
               o Tuning for Speed
               o Special Features of ncurses
          + Compatibility with Older Versions
               o Refresh of Overlapping Windows
               o Background Erase
          + XSI Curses Conformance
     * The Panels Library
          + Compiling With the Panels Library
          + Overview of Panels
          + Panels, Input, and the Standard Screen
          + Hiding Panels
          + Miscellaneous Other Facilities
     * The Menu Library
          + Compiling with the menu Library
          + Overview of Menus
          + Selecting items
          + Menu Display
          + Menu Windows
          + Processing Menu Input
          + Miscellaneous Other Features
     * The Forms Library
          + Compiling with the forms Library
          + Overview of Forms
          + Creating and Freeing Fields and Forms
          + Fetching and Changing Field Attributes
               o Fetching Size and Location Data
               o Changing the Field Location
               o The Justification Attribute
               o Field Display Attributes
               o Field Option Bits
               o Field Status
               o Field User Pointer
          + Variable-Sized Fields
          + Field Validation
               o TYPE_ALPHA
               o TYPE_ALNUM
               o TYPE_ENUM
               o TYPE_INTEGER
               o TYPE_NUMERIC
               o TYPE_REGEXP
          + Direct Field Buffer Manipulation
          + Attributes of Forms
          + Control of Form Display
          + Input Processing in the Forms Driver
               o Page Navigation Requests
               o Inter-Field Navigation Requests
               o Intra-Field Navigation Requests
               o Scrolling Requests
               o Field Editing Requests
               o Order Requests
               o Application Commands
          + Field Change Hooks
          + Field Change Commands
          + Form Options
          + Custom Validation Types
               o Union Types
               o New Field Types
               o Validation Function Arguments
               o Order Functions For Custom Types
               o Avoiding Problems
     _________________________________________________________________

                                 Introduction

   This document is an introduction to programming with curses. It is not
   an   exhaustive  reference  for  the  curses  Application  Programming
   Interface  (API);  that  role  is  filled  by the curses manual pages.
   Rather,  it  is  intended  to  help  C programmers ease into using the
   package.

   This   document  is  aimed  at  C  applications  programmers  not  yet
   specifically  familiar with ncurses. If you are already an experienced
   curses  programmer, you should nevertheless read the sections on Mouse
   Interfacing,  Debugging, Compatibility with Older Versions, and Hints,
   Tips,  and  Tricks.  These  will  bring you up to speed on the special
   features  and  quirks of the ncurses implementation. If you are not so
   experienced, keep reading.

   The  curses  package  is a subroutine library for terminal-independent
   screen-painting  and  input-event handling which presents a high level
   screen  model  to  the programmer, hiding differences between terminal
   types  and doing automatic optimization of output to change one screen
   full  of  text into another. Curses uses terminfo, which is a database
   format  that  can  describe the capabilities of thousands of different
   terminals.

   The  curses  API  may  seem  something of an archaism on UNIX desktops
   increasingly  dominated  by  X,  Motif, and Tcl/Tk. Nevertheless, UNIX
   still  supports  tty lines and X supports xterm(1); the curses API has
   the advantage of (a) back-portability to character-cell terminals, and
   (b)  simplicity.  For  an application that does not require bit-mapped
   graphics  and multiple fonts, an interface implementation using curses
   will  typically  be  a  great deal simpler and less expensive than one
   using an X toolkit.

A Brief History of Curses

   Historically, the first ancestor of curses was the routines written to
   provide   screen-handling   for   the   game  rogue;  these  used  the
   already-existing  termcap  database  facility  for describing terminal
   capabilities. These routines were abstracted into a documented library
   and first released with the early BSD UNIX versions.

   System  III UNIX from Bell Labs featured a rewritten and much-improved
   curses  library.  It introduced the terminfo format. Terminfo is based
   on  Berkeley's termcap database, but contains a number of improvements
   and  extensions.  Parameterized  capabilities strings were introduced,
   making  it  possible to describe multiple video attributes, and colors
   and  to  handle far more unusual terminals than possible with termcap.
   In  the  later  AT&T  System  V  releases,  curses evolved to use more
   facilities and offer more capabilities, going far beyond BSD curses in
   power and flexibility.

Scope of This Document

   This document describes ncurses, a free implementation of the System V
   curses  API  with  some  clearly  marked  extensions.  It includes the
   following System V curses features:
     * Support  for  multiple  screen  highlights  (BSD curses could only
       handle one `standout' highlight, usually reverse-video).
     * Support for line- and box-drawing using forms characters.
     * Recognition of function keys on input.
     * Color support.
     * Support  for pads (windows of larger than screen size on which the
       screen or a subwindow defines a viewport).

   Also,  this  package  makes  use  of  the  insert  and delete line and
   character  features  of  terminals  so equipped, and determines how to
   optimally  use  these  features  with  no help from the programmer. It
   allows  arbitrary  combinations  of  video attributes to be displayed,
   even  on  terminals that leave ``magic cookies'' on the screen to mark
   changes in attributes.

   The  ncurses  package  can  also  capture and use event reports from a
   mouse in some environments (notably, xterm under the X window system).
   This document includes tips for using the mouse.

   The  ncurses  package  was  originated  by  Pavel Curtis. The original
   maintainer  of  this  package is Zeyd Ben-Halim <[e-mail]>.
   Eric S. Raymond <[e-mail]> wrote many of the new features
   in  versions  after  1.8.1 and wrote most of this introduction. J黵gen
   Pfeifer  wrote  all  of  the  menu and forms code as well as the Ada95
   binding.  Ongoing  work  is  being done by Thomas Dickey (maintainer).
   Contact the current maintainers at [e-mail].

   This  document  also describes the panels extension library, similarly
   modeled  on  the  SVr4  panels  facility.  This  library allows you to
   associate  backing  store  with each of a stack or deck of overlapping
   windows,  and  provides  operations  for  moving windows around in the
   stack that change their visibility in the natural way (handling window
   overlaps).

   Finally,  this  document  describes  in  detail  the  menus  and forms
   extension  libraries,  also  cloned  from System V, which support easy
   construction and sequences of menus and fill-in forms.

Terminology

   In  this  document,  the following terminology is used with reasonable
   consistency:

   window
          A  data  structure  describing  a  sub-rectangle  of the screen
          (possibly  the  entire  screen).  You  can write to a window as
          though  it  were a miniature screen, scrolling independently of
          other windows on the physical screen.

   screens
          A  subset of windows which are as large as the terminal screen,
          i.e.,  they  start  at the upper left hand corner and encompass
          the   lower  right  hand  corner.  One  of  these,  stdscr,  is
          automatically provided for the programmer.

   terminal screen
          The package's idea of what the terminal display currently looks
          like, i.e., what the user sees now. This is a special screen.

                              The Curses Library

An Overview of Curses

  Compiling Programs using Curses

   In order to use the library, it is necessary to have certain types and
   variables defined. Therefore, the programmer must have a line:
          #include <curses.h>

   at the top of the program source. The screen package uses the Standard
   I/O   library,  so  <curses.h>  includes  <stdio.h>.  <curses.h>  also
   includes  <termios.h>,  <termio.h>,  or  <sgtty.h>  depending  on your
   system.  It is redundant (but harmless) for the programmer to do these
   includes,  too.  In  linking with curses you need to have -lncurses in
   your  LDFLAGS  or  on the command line. There is no need for any other
   libraries.

  Updating the Screen

   In  order  to  update  the  screen  optimally, it is necessary for the
   routines  to  know  what  the screen currently looks like and what the
   programmer  wants  it to look like next. For this purpose, a data type
   (structure)  named WINDOW is defined which describes a window image to
   the  routines,  including its starting position on the screen (the (y,
   x)  coordinates  of  the  upper left hand corner) and its size. One of
   these  (called  curscr,  for current screen) is a screen image of what
   the  terminal currently looks like. Another screen (called stdscr, for
   standard screen) is provided by default to make changes on.

   A  window is a purely internal representation. It is used to build and
   store  a potential image of a portion of the terminal. It doesn't bear
   any  necessary relation to what is really on the terminal screen; it's
   more like a scratchpad or write buffer.

   To  make  the  section  of  physical  screen corresponding to a window
   reflect  the  contents  of the window structure, the routine refresh()
   (or wrefresh() if the window is not stdscr) is called.

   A  given physical screen section may be within the scope of any number
   of  overlapping  windows.  Also, changes can be made to windows in any
   order,  without  regard  to  motion  efficiency.  Then,  at  will, the
   programmer can effectively say ``make it look like this,'' and let the
   package implementation determine the most efficient way to repaint the
   screen.

  Standard Windows and Function Naming Conventions

   As  hinted  above,  the  routines can use several windows, but two are
   automatically given: curscr, which knows what the terminal looks like,
   and  stdscr,  which  is what the programmer wants the terminal to look
   like  next.  The  user  should  never actually access curscr directly.
   Changes  should  be  made  to  through  the  API, and then the routine
   refresh() (or wrefresh()) called.

   Many  functions  are  defined  to  use stdscr as a default screen. For
   example,  to  add  a  character  to stdscr, one calls addch() with the
   desired character as argument. To write to a different window. use the
   routine  waddch()  (for  `w'indow-specific  addch()) is provided. This
   convention of prepending function names with a `w' when they are to be
   applied  to specific windows is consistent. The only routines which do