home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / misc / volume10 / pccurses14 / part06 / curses.3 next >
Encoding:
Text File  |  1990-01-19  |  14.3 KB  |  299 lines
  1. CURSES(3)        MS-DOS Programmer's Manual          CURSES(3)
  2.  
  3. NAME
  4.    curses - screen/window management library
  5.  
  6. DESCRIPTION
  7.    Curses is a library of screen and window management routines. It is modeled
  8.    after the UNIX curses and ncurses libraries. Normally, programs written for
  9.    PCcurses should be easily ported to UNIX, and vice versa.
  10.  
  11.    To use the routines, the function initscr() must first be called. This cre-
  12.    ates two 'windows' for the user: stdscr and curscr. Stdscr is the default
  13.    window for the user to make changes on, and curscr reflects the current
  14.    contents of the physical display screen. The user writes or edits the std-
  15.    scr window to his liking, then calls the refresh() function to make curscr
  16.    and the physical screen look like stdscr. When the user program terminates,
  17.    it should call the endwin() function to restore things to normal.
  18.  
  19.    There are all sorts of window manipulation routines available to the pro-
  20.    grammer: auxiliary windows may be created, edited, moved and deleted. The
  21.    terminal may be set in many different modes, output text may be attributed
  22.    with blink, blank, bold and reverse attributes. There are window-specific
  23.    printf- and scanf-like routines, routines for scrolling, box-drawing, win-
  24.    dow overlaying, clearing routines etc. Curses also handles terminal func-
  25.    tion keys, which is enables by calling the keypad() function.
  26.  
  27.    The handling of character attributes is different on MGA, CGA and Hercules
  28.    adapters. The package has been tested with them all. EGA has not been tes-
  29.    ted, but should also work except for special screen modes.
  30.  
  31.    For more and detailed information, see the library source codes. All curses
  32.    functions are preceded by a brief but complete description.
  33.  
  34. COMPILING
  35.    All programs that use curses facilities should include the file <curses.h>,
  36.    and during linking, the library ?curses.lib should be specified to the lin-
  37.    ker ('?' is 's', 'c' 'm' or 'l' for small, compact, medium or large memory
  38.    model respectively).
  39.  
  40. FUNCTIONS
  41.    Below is a list over the available functions, together with a brief de-
  42.    scription of what they do. In general, functions whose names start with
  43.    'w' differ from the one without 'w' (like wmove vs. move) signify that
  44.    a specific window is used. Without a 'w', sdtscr is implied. The functions
  45.    that start with 'mv' before the 'genereic' function name signify that a
  46.    cursor motion should be made before the actual work. 'mv' and 'w' combine
  47.    as expected.
  48.  
  49.    Most routines that return an int will return the manifest constant ERR if
  50.    there is a failure during execution. Routines that return a char actually
  51.    return an int, so that ERR does not conflict with the character code 0xff.
  52.    All IBM PC characters from 0 to 0xff are allowed for usage with curses.
  53.    There are (non-portable) character output routines to write the special
  54.    IBM fonts for characters with ASCII code less than 0x20 (control charac-
  55.    ters).
  56.  
  57.    Some routines, like {mv}{w} printw() and {mv}{w}scanw() return a meaningful
  58.    positive value if the operation is successful.
  59.  
  60.    The curses package uses some predefined types, variables and manifest con-
  61.    stants that are also available to the programmer. For example, the ERR and
  62.    OK macros should be used to test for failure of curses functions. Don't use
  63.    the numerical values, since those are different for different versions of
  64.    curses!
  65.  
  66.    There are also a few globally accessible variables that should not be tou-
  67.    ched by the application program. Those untouchable variables have names
  68.    starting with an underscore (_) to avoid conflicts. The user-accessible
  69.    types, variables and constants are (there are a number of other constants
  70.    defining character attribute names and function key names - consult the
  71.    <curses.h> and <curspriv.h> include files for details):
  72.  
  73.    (manifest constants)
  74.  
  75.        TRUE                boolean true
  76.     FALSE                boolean false
  77.     ERR                unsuccessfull operation
  78.     OK                successfull operation
  79.  
  80.    (types)
  81.  
  82.        WINDOW                a window structure type
  83.     bool                boolean flag type
  84.  
  85.    (variables)
  86.  
  87.        WINDOW curscr            physical display image
  88.     WINDOW stdscr            default user drawing board
  89.        int    LINES            terminal height
  90.     int    COLS            terminal width
  91.  
  92.    The following is an alphabetical list of the curses functions, together
  93.    with their types, parameters and a short comment for each. Win is a win-
  94.    dow; ch, l, r, t, b, tl, tr, bl and br are characters; buf is a character
  95.    buffer; attrs is an attribute bit map; bf is a boolean flag. Note that
  96.    `character' return values in this context usually are 16 bits. Guaranteed
  97.    portable functions are marked with an asterisk (*):
  98.  
  99.  
  100. *  int   addch(ch)            put char in stdscr
  101.    int     addrawch(ch)            put raw char in stdscr
  102. *  int     addstr(str)            put string in stdscr
  103.    void     attroff(attrs)            clear attribute(s) in stdscr
  104.    void     attron(attrs)            add attribute(s) in stdscr
  105.    void     attrset(attrs)            set stdscr char attributes
  106.    int     baudrate()            dummy for compatibility
  107.    void     beep()                ring the bell
  108.    void     border(l,r,t,b,tl,tr,bl,br)    Set non-std box characters
  109. *  void     box(win,l,t)            box in a window, with given characters
  110. *  void     cbreak()            set terminal cbreak mode
  111. *  void     clear()            clear stdscr
  112. *  void     clearok(win,bf)        marks window for screen clear
  113. *  int     clrtobot()            clear end of stdscr
  114. *  int     clrtoeol()            clear end of line in stdscr
  115. *  void     crmode()            set terminal cbreak mode
  116.    void     cursoff()            turns off hardware cursor
  117.    void     curson()            turns on hardware cursor
  118.    void     def_prog_mode()        save TTY modes
  119.    void     def_shell_mode()        compatibility dummy
  120. *  int     delch()            delete a char in stdscr
  121. *  int     deleteln()            delete a line in stdscr
  122. *  void     delwin(win)            delete a window or a subwindow
  123.    void     doupdate()            update physical screen
  124. *  void     echo()                set terminal echo mode
  125. *  int     endwin()            cleanup and curses finitialization
  126. *  void     erase()            erase stdscr
  127.    int     erasechar()            return char delete character
  128.    int     fixterm()            dummy for compatibility
  129.    void     flash()            flash terminal screen
  130.    void  flushinp()            kill pending keyboard input
  131. *  int     getch()    (#def macro)    get character via stdscr
  132. *  int     getstr(buf)            get string via stdscr to a buffer
  133. *  void     getyx(win,y,x)            get a window's cursor position
  134. *  int     gettmode()            dummy for compatibility
  135.    void     idlok(win,bf)            dummy for compatibility
  136. *  int     initscr()            curses initialization (ret 1 if OK)
  137. *  int     inch()                get char at stdscr cursor
  138. *  int     insch(ch)            insert character in stdscr
  139.    int     insrawch(ch)            insert raw character in stdscr
  140. *  int     insertln()            insert an empty line in stdscr
  141.    void     keypad(win,bf)            marks a window for keypad usage
  142.    int   killchar()            return line delete character
  143. *  void     leaveok(win,bf)        marks window for cursor 'update leave'
  144. *  char *longname()            returns terminal description string
  145.    void  meta(win,bf)            marks window for meta (dummy function)
  146. *  int     move(y,x)            move cursor in stdscr
  147. *  int     mvaddch(y,x,ch)        move & put char in stdscr
  148.    int     mvaddrawch(y,x,ch)        move & put raw char in stdscr
  149. *  int     mvaddstr(y,x,str)        move & put string in stdscr
  150.    int     mvclrtobot(y,x)        move & clear end of stdscr
  151.    int     mvclrtoeol(y,x)        move & clear lineend in stdscr
  152. *  int     mvcur(oldy,oldx,y,x)        move terminal cursor to <y,x>
  153. *  int     mvdelch(y,x)            move & delete a char in stdscr
  154.    int     mvdeleteln(y,x)        move & delete a line in stdscr
  155. *  int     mvgetch(y,x)            move & get char to stdscr
  156. *  int     mvgetstr(y,x,buf)        move & get string via stdscr to buffer
  157. *  int     mvinch(y,x,)            move & get char at stdscr cursor
  158. *  int     mvinsch(y,x,ch)        move & insert char in stdscr
  159.    int     mvinsrawch(y,x,ch)        move & insert raw char in stdscr
  160.    int     mvinsertln(y,x)        move & insert new line in stdscr
  161. *  int     mvprintw(y,x,fmt,args)        move & print string in stdscr
  162. *  int     mvscanw(y,x,fmt,args)        move & get values via stdscr
  163. *  int     mvwaddch(win,y,x,ch)        move & put char in a window
  164.    int     mvwaddrawch(win,y,x,ch)    move & put raw char in a window
  165. *  int     mvwaddstr(win,y,x,str)        move & put string in a window
  166.    int     mvwclrtobot(win,y,x)        move & clear end of a window
  167.    int     mvwclrtoeol(win,y,x)        move & clear lineend in a window
  168. *  int     mvwdelch(win,y,x)        move & delete a char in a window
  169.    int     mvwdeleteln(win,y,x)        move & delete a line in a window
  170. *  int     mvwgetch(win,y,x)        move & get char to a window
  171. *  int     mvwgetstr(win,y,x,str)        move & get string to a window
  172. *  int     mvwinch(win,y,x)        move & get char at window cursor
  173. *  int     mvwinsch(win,y,x,ch)        move & insert char in a window
  174.    int     mvwinsrawch(win,y,x,ch)    move & insert raw char in a window
  175.    int     mvwinsertln(win,y,x)        move & insert new line in window
  176.    int     mvwin(win,y,x)            move window on physical screen
  177. *  int     mvwprintw(win,x,y,fmt,args)    move & print string in a window
  178. *  int     mvwscanw(win,y,x,fmt,args)    move & get values via a window
  179. *  WINDOW *newwin(lines,cols,begy,begx)    create a new window
  180. *  void     nl()                set terminal cr-crlf mapping mode
  181. *  void     nocbreak()            unset terminal cbreak mod
  182. *  void     nocrmode()            unset terminal cbreak mode
  183.    void     nodelay(win,bf)        marks window for no input wait
  184. *  void     noecho()            unset terminal echo mode
  185. *  void     nonl()                unset terminal cr-crlf mapping mode
  186. *  void     noraw()            unset raw terminal mode
  187. *  void     overlay(win1,win2)        overlay one window on another
  188. *  void     overwrite(win1,win2)        overwrite one window on another
  189. *  int     printw(fmt,args)        print string in stdscr
  190. *  void     raw()                set raw terminal mode
  191.    void     refrbrk(bf)            set screen update break mode
  192. *  void     refresh()            refresh stdscr
  193.    int     resetterm()            dummy for compatibility
  194. *  int     resetty()            restore terminal I/O modes
  195.    void     reset_prog_mode()        restore terminal I/O modes
  196.    void     reset_shell_mode()        set terminal to default modes
  197.    int     saveoldterm()            dummy for compatibility
  198.    int     saveterm()            dummy for compatibility
  199. *  int     savetty()            save terminal I/O modes
  200. *  int     scanw(fmt,args)        get values via stdscr
  201. *  void     scroll(win)            scroll scrolling region of a window
  202. *  void     scrollok(win,bf)        marks a window to allow scroll
  203.    int     setscrreg(miny,maxy)        define stdscr's scroll region
  204. *  int     setterm()            dummy for compatibility
  205.    int     setupterm(term,fd,errret)    set up terminal (no-op on PC)
  206. *  void     standend()            start normal chars in stdscr
  207. *  void     standout()            start standout chars in stdscr
  208. *  WINDOW *subwin(win,lines,cols,begy,begx) create a sub-window in window win
  209.    int     tabsize(ts)            set/get tabsize of stdscr
  210. *  void     touchwin(win)            mark a window as totally modified
  211. *  char    *unctrl(ch)            char-to-string converter
  212.    int     ungetch(ch)    (#def macro)    push back a character to input */
  213. *  int     waddch(win,ch)            put char in a window
  214.    int     waddrawch(win,ch)        put raw char in a window
  215. *  int     waddstr(win,str)        put string in a window
  216.    void     wattroff(win,attrs)        clear attribute(s) in window
  217.    void     wattron(win,attrs)        add attribute(s) in window
  218.    void     wattrset(win,attrs)        set window char attributes
  219.    void     wborder(win,l,r,t,b,tl,tr,bl,br) Set non-std box characters
  220.    int     wbox(win,miny,minx,maxy,maxx,l,r) draw a box inside a window
  221. *  void     wclear(win)            clear a window
  222. *  int     wclrtobot(win)            clear end of a window
  223. *  int     wclrtoeol(win)            clear end of line in a window
  224. *  int     wdelch(win)            delete a char in a window
  225. *  int     wdeleteln(win)            delete a line in a window
  226. *  void     werase(win)            erase a window
  227. *  int     wgetch(win)            get char via a window
  228. *  int     wgetstr(win,buf)        get string via window to a buffer
  229. *  int     winch(win)            get char at window cursor
  230. *  int     winsch(win,ch)            insert character in a window
  231.    int     winsrawch(win,ch)        insert raw character in a window
  232. *  int     winsertln(win)            insert new line in a window
  233. *  int     wmove(win,y,x)            move cursor in a window
  234.    void     wnoutrefresh(win)        create internal screen image
  235. *  int     wprintw(win,fmt,args)        print string in a window
  236. *  void     wrefresh(win)            refresh window
  237. *  int     wscanw(win,fmt,args)        get values via a window
  238.    int     wsetscrreg(win,miny,maxy)    define a window's scrolling region
  239. *  void     wstandend(win)            start normal chars in window
  240. *  void     wstandout(win)            start standout chars in window
  241.    int     wtabsize(win,ts)        set/get tabsize of a window
  242.    int     wungetch(ch)            push back a character to input */
  243.  
  244. MISSING FUNCTIONS
  245.  
  246.    The following functions existing in UNIX cursees are missing in PCcurses:
  247.  
  248.    getcap(nam)                get terminal capability 'name'
  249.  
  250. FUNCTIONS UNIQUE TO PCcurses
  251.  
  252.    The following functions are (to the author's knowledge) unique to PCcurses:
  253.  
  254.    int     addrawch(ch)            put raw char in stdscr
  255.    int     waddrawch(win,ch)        put raw char in a window
  256.    int     mvaddrawch(y,x,ch)        move & put raw char in stdscr
  257.    int     mvwaddrawch(win,y,x,ch)    move & put raw char in a window
  258.    int   insrawch(ch)            insert raw character in stdscr
  259.    int   winsrawch(win,ch)        insert raw character in a window
  260.    int     mvinsrawch(y,x,ch)        move & insert raw char in stdscr
  261.    int     mvwinsrawch(win,y,x,ch)    move & insert raw char in a window
  262.    int   tabsize(ts)            set/get tabsize of stdscr
  263.    int     wtabsize(win,ts)        set/get tabsize of a window
  264.  
  265. SEE ALSO
  266.    "Screen Updating And Cursor Movement Optimization: A Library Package" -
  267.    Kenneth C.R.C. Arnold
  268.    "The Ncurses Reference Manual" - Pavel Curtis, Cornell University
  269.  
  270. BUGS
  271.    The terminal raw I/O mode is implemented by reading characters directly
  272.    from the BIOS. This means that the programmer must not use the normal
  273.    I/O routines to the screen or from the keyboard, since they will trap the
  274.    MS-DOS ^C, ^S, ^Q and ^P characters and thus nullify the raw input.
  275.  
  276.    Also, if the terminal is in normal or cbreak mode and the programmer has
  277.    trapped CTRL-BREAK by using signal(SIGINT,ownhandler), MS-DOS will still
  278.    echo the characters '^C' on the screen when the character is intercepted.
  279.    There seems to be no way to avoid this under MS-DOS (use raw mode in-
  280.    stead, or redraw the whole screen).
  281.  
  282.    The function key support is hardware dependent. There is a table in char-
  283.    get.c that maps keyboard scan codes from the keyboard to function key
  284.    names. The one supplied works for IBM PC/XT/AT, and for most clones.
  285.  
  286. REVISION
  287.    The current revision is v.1.4 (900114). If you find or correct bugs, or if
  288.    you think up or implement enhancements, please contact the author. That way
  289.    he can maintain an 'official' version of PCcurses, without too many local
  290.    versions floating around.
  291.  
  292. AUTHOR
  293.    Home:       Bjorn Larsson        Work:    INFOVOX AB
  294.            Ynglingagatan 5,IV            Box 2503
  295.            S-113 47 Stockholm            S-171 02 Solna
  296.            SWEDEN                SWEDEN
  297.  
  298.            UseNet: bl@infovox.se
  299.