home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 2 / MacMania 2.toast / Demo's / Tools&Utilities / Programming / Curses / README < prev    next >
Encoding:
Text File  |  1994-06-01  |  7.4 KB  |  173 lines  |  [TEXT/R*ch]
  1.     This is a public domain implementation of Curses for IBM PC's and
  2.     compatibles. It was developed on an IBM PC-AT clone using a Monochrome
  3.     (Hercules compatible) display adapter.  It should run on other adapters as
  4.     well, but has not been tested.  There is no support for displays with more
  5.     than 25 lines, and I am also not sure of the support for CGA displays with
  6.     40 characters per line.
  7.  
  8.     The curses functions included are a major subset of that provided on
  9.     System V. Specifically, pads are not included, nor are the lower-level
  10.     "terminfo" calls.
  11.  
  12.     This source code is placed in the public domain and may be included in any
  13.     product in whole or in part.  The only restriction on the use of this code
  14.     is that I specifically disallow the use of this free code to create a
  15.     virtually identical product for sale commercially.  (In other words,
  16.     please do not delete my name from the source code, put your name in its
  17.     place, and then sell this package as if it were your own.)
  18.  
  19.     Permission is specifically granted on the use of these subroutines within
  20.     any private, commercial, public domain, shareware, or whatever program.
  21.  
  22. Files
  23.  
  24.     Included in this distribution are the following files:
  25.  
  26.     curses.c    Portable source code for curses entry points.
  27.     curses.h    Header file required by all programs that access curses.
  28.     makefile    A makefile to build the necessary .obj, .lib, and .exe files.
  29.     readme    This file.
  30.     t.c        A unit test to test the functionality of curses (and to demo
  31.         some of its features).
  32.     v_msdos.c    IBM-PC (MS-DOS?) specific low-level screen and keyboard
  33.         functions.
  34.  
  35. Use
  36.  
  37.     If you have access to Unix documentation, the use of curses is virtually
  38.     identical.  If you do not have access to this, the best information on
  39.     curses is probably "Screen Updating and Cursor Movement Optimization: A
  40.     Library Package", by Kenneth Arnold.  It is available electronically a
  41.     number of places, including the Xenix data library in the TRS-80
  42.     Professional Forum on CompuServe.
  43.  
  44. Porting
  45.  
  46.     The curses routines exist in two modules:
  47.     - curses.c    All curses entry points.
  48.     - v_msdos.c    Routines containing machine specific code.
  49.  
  50.     The machine specific entry points (within v_msdos.c) are described below:
  51.  
  52.     ms_init()        Perform any initializations that need to be done.
  53.             This could include accessing a terminal file,
  54.             initializing the "acs_map" array, etc.
  55.  
  56.     ms_refresh()    Make the display screen look like the specified window.
  57.  
  58.     ms_end()        Perform any necessary cleanup (freeing of allocated
  59.             memory, closing files, etc.).
  60.  
  61.     ms_beep()        Sound an alarm, and optionally flash the screen.
  62.  
  63.     ms_kbinp()        Get a single character from the terminal.  Do not echo
  64.             the character.
  65.  
  66.     acs_map[]        Alternate character set map array.  Refer to curses.h
  67.             for the mappings of the alternate character set.
  68.             These mappings were taken from the curses makefile
  69.             from System V/386.
  70.  
  71.     To port the code to another system, you will need to rewrite the v_msdos.c
  72.     code for the target machine.
  73.  
  74. CURSES window structure
  75.  
  76.     The WINDOW structure is used to communicate between the application
  77.     program, curses, and the machine specific implementation module.  Curses.c
  78.     should be the only module modifying any of the information within this
  79.     structure.  In addition, the application program should only use the
  80.     defined subroutines and macros to access the information within the
  81.     structure.
  82.  
  83.     For those attempting to implement a machine-specific implementation
  84.     module, the following is a description of the fields in the WINDOW
  85.     structure:
  86.  
  87.     _cury, _curx    Current location of the cursor, relative to the
  88.             window (0,0 = top left corner of window).
  89.     _maxy, _maxx    The size of the window in lines and columns,
  90.             respectively.
  91.     _begy, _begx    The location of the upper left hand corner of this
  92.             window on the display (0,0 = top left corner of
  93.             display).
  94.     _flags        Special attributes of this window.  The following
  95.             flags are defined, although only those preceded by an
  96.             asterisk are actually used (the names were chosen for
  97.             compatibility with Unix curses):
  98.               _SUBWIN    Window is a subwindow of another.
  99.               _ENDLINE
  100.               _FULLWIN
  101.               _SCROLLWIN
  102.             * _FLUSH    Flush input on receipt of input.
  103.               _ISPAD    Window may be larger than screen.
  104.             * _WINCHANGED    Window has changed since last refresh.
  105.             * _WINMOVED    Window has been moved since last
  106.                     refresh.
  107.     _attrs        Current default character attributes for window.
  108.     _clear        Boolean - If true, redraw window from scratch.
  109.     _leave        Boolean - If true, cursor position is not important.
  110.     _scroll        Boolean - If true, window may be scrolled.
  111.     _use_idl        Boolean - If true, need to wait for terminal to
  112.             update.
  113.     _use_keypad        Boolean - If true, return special characters for
  114.             keypad characters (eg, KEY_INS).
  115.     _use_meta        Boolean - If true, use a meta key.
  116.     _nodelay        Boolean - If true, wgetch() is non-blocking and
  117.             returns ERR if no character waiting.
  118.     _y            Physical description of the current window.  An array
  119.             of "chtype", whose dimensions are _maxy and _maxx
  120.             (eg, chtype _y[maxy][maxx];).
  121.     _firstch        Not used - First screen updating command.
  122.     _lastch        Not used - Points to next screen updating command.
  123.     _notimeout        Boolean - If true, wait for function key string when a
  124.             lead-in character (usually ESC) is received.
  125.     _need_idl        Not used - included for compatibility with Unix
  126.             curses.
  127.     _tmarg,_bmarg    Scrolling region - _tmarg is the first line (from
  128.             zero) that scrolls, _bmarg is the last line (from
  129.             zero) that scrolls.
  130.  
  131.     The names of these members were chosen to be compatible with System V
  132.     curses.
  133.  
  134. Non-portable enhancements
  135.  
  136.     An enhancement has been added in that the function wprintw() uses a
  137.     dynamically allocated buffer.  Prior to the first call of wprintw(),
  138.     you may set the external variable "curses_prntw_size" to the number of
  139.     characters to allocate for wprintw()'s buffer.  In a like manner, you may
  140.     set the external variable "curses_prntw" to point to an actual buffer.
  141.     The wprintw() buffer is an array of chars (not chtypes).
  142.  
  143.     By default, curses uses a buffer size of 512 and dynamically allocates the
  144.     buffer on the first call to wprintw().
  145.  
  146. Enhancements / Bug fixes / Support
  147.  
  148.     Since the target audience for this package is Unix programmers who want to
  149.     port their code to DOS (or other operating systems), documenting the
  150.     functions is left to the official sources. If you need help using curses,
  151.     please do not contact me.  Instead, refer to the information in the
  152.     section entitled "Use" for where you can find the documentation.
  153.  
  154.     If you need help porting to another environment, drop me a line at one of
  155.     the addresses below.  If you are successful in you port, I would be
  156.     interested in distributing the implementation module(s) with future
  157.     releases of curses.
  158.  
  159.     If you send me bug fixes and enhancements, I will add them to later
  160.     releases of the code (with the proper credit going to the author or
  161.     authors). Please make all enhancements compatible with System V curses.
  162.     I will also attempt to alert all known contributors of future releases
  163.     of the product.
  164.  
  165.     I can be reached electronically at the following addresses:
  166.  
  167.     CompuServe        [72236,3516]
  168.     Delphi            LARRYG
  169.     Bix            LAR3RY
  170.     uucp            lg@bsw.com -or- lg@risk.bsw.com
  171.     US Mail            104 Lowell Road / Salem, NH  03079 / USA
  172.  
  173.