home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / CURSES.LZH / CURSES.MAN < prev    next >
Text File  |  1980-01-01  |  15KB  |  296 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', stdscr is implied. The functions
  45.    that start with 'mv' before the 'generic' 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. There are also a few
  62.    globally accessible variables that should not be touched by the applica-
  63.    tion program. Those untouchable variables have names starting with an
  64.    underscore (_) to avoid conflicts. The user-accessible types, variables
  65.    and constants are (there are a number of other constants defining charac-
  66.    ter attribute names and function key names - consult <curses.h> for de-
  67.    tails):
  68.  
  69.    (manifest constants)
  70.  
  71.        TRUE                boolean true
  72.     FALSE                boolean false
  73.     ERR                unsuccessful operation
  74.     OK                successful operation
  75.  
  76.    (types)
  77.  
  78.        WINDOW                a window structure type
  79.     bool                boolean flag type
  80.  
  81.    (variables)
  82.  
  83.        WINDOW curscr            physical display image
  84.     WINDOW stdscr            default user drawing board
  85.        int    LINES            terminal height
  86.     int    COLS            terminal width
  87.  
  88.    The following is an alphabetical list of the curses functions, together
  89.    with their types, parameters and a short comment for each. Win is a win-
  90.    dow; ch, l, r, t, b, tl, tr, bl and br are characters; buf is a character
  91.    buffer; attrs is an attribute bit map; bf is a boolean flag. Note that
  92.    `character' return values in this context usually can have 16 bits. Gua-
  93.    ranteed portable functions (existing in Berkeley UNIX curses) are marked
  94.    with an asterisk (*):
  95.  
  96.  
  97. *  int   addch(ch)            put char in stdscr
  98.    int     addrawch(ch)            put raw char in stdscr
  99. *  int     addstr(str)            put string in stdscr
  100.    void     attroff(attrs)            clear attribute(s) in stdscr
  101.    void     attron(attrs)            add attribute(s) in stdscr
  102.    void     attrset(attrs)            set stdscr char attributes
  103.    int     baudrate()            dummy for compatibility
  104.    void     beep()                ring the bell
  105.    void     border(l,r,t,b,tl,tr,bl,br)    Set non-std box characters
  106. *  void     box(win,l,t)            box in a window, with given characters
  107. *  void     cbreak()            set terminal cbreak mode
  108. *  void     clear()            clear stdscr
  109. *  void     clearok(win,bf)        marks window for screen clear
  110. *  int     clrtobot()            clear end of stdscr
  111. *  int     clrtoeol()            clear end of line in stdscr
  112. *  void     crmode()            set terminal cbreak mode
  113.    void     cursoff()            turns off hardware cursor
  114.    void     curson()            turns on hardware cursor
  115.    void     def_prog_mode()        save TTY modes
  116.    void     def_shell_mode()        compatibility dummy
  117. *  int     delch()            delete a char in stdscr
  118. *  int     deleteln()            delete a line in stdscr
  119. *  void     delwin(win)            delete a window or a subwindow
  120.    void     doupdate()            update physical screen
  121. *  void     echo()                set terminal echo mode
  122. *  int     endwin()            cleanup and curses finitialization
  123. *  void     erase()            erase stdscr
  124.    int     erasechar()            return char delete character
  125.    int     fixterm()            dummy for compatibility
  126.    void     flash()            flash terminal screen
  127.    void  flushinp()            kill pending keyboard input
  128. *  int     getch()    (#def macro)    get character via stdscr
  129. *  int     getstr(buf)            get string via stdscr to a buffer
  130. *  void     getyx(win,y,x)            get a window's cursor position
  131. *  int     gettmode()            dummy for compatibility
  132.    void     idlok(win,bf)            dummy for compatibility
  133. *  int     initscr()            curses initialization (ret 1 if OK)
  134. *  int     inch()                get char at stdscr cursor
  135. *  int     insch(ch)            insert character in stdscr
  136.    int     insrawch(ch)            insert raw character in stdscr
  137. *  int     insertln()            insert an empty line in stdscr
  138.    void     keypad(win,bf)            marks a window for keypad usage
  139.    int   killchar()            return line delete character
  140. *  void     leaveok(win,bf)        marks window for cursor 'update leave'
  141. *  char *longname()            returns terminal description string
  142.    void  meta(win,bf)            marks window for meta (dummy function)
  143. *  int     move(y,x)            move cursor in stdscr
  144. *  int     mvaddch(y,x,ch)        move & put char in stdscr
  145.    int     mvaddrawch(y,x,ch)        move & put raw char in stdscr
  146. *  int     mvaddstr(y,x,str)        move & put string in stdscr
  147. *  int     mvclrtobot(y,x)        move & clear end of stdscr
  148. *  int     mvclrtoeol(y,x)        move & clear lineend in stdscr
  149. *  int     mvcur(oldy,oldx,y,x)        move terminal cursor to <y,x>
  150. *  int     mvdelch(y,x)            move & delete a char in stdscr
  151. *  int     mvdeleteln(y,x)        move & delete a line in stdscr
  152. *  int     mvgetch(y,x)            move & get char to stdscr
  153. *  int     mvgetstr(y,x,buf)        move & get string via stdscr to buffer
  154. *  int     mvinch(y,x,)            move & get char at stdscr cursor
  155. *  int     mvinsch(y,x,ch)        move & insert char in stdscr
  156.    int     mvinsrawch(y,x,ch)        move & insert raw char in stdscr
  157. *  int     mvinsertln(y,x)        move & insert new line in stdscr
  158. *  int     mvprintw(y,x,fmt,args)        move & print string in stdscr
  159. *  int     mvscanw(y,x,fmt,args)        move & get values via stdscr
  160. *  int     mvwaddch(win,y,x,ch)        move & put char in a window
  161.    int     mvwaddrawch(win,y,x,ch)    move & put raw char in a window
  162. *  int     mvwaddstr(win,y,x,str)        move & put string in a window
  163. *  int     mvwclrtobot(win,y,x)        move & clear end of a window
  164. *  int     mvwclrtoeol(win,y,x)        move & clear lineend in a window
  165. *  int     mvwdelch(win,y,x)        move & delete a char in a window
  166. *  int     mvwdeleteln(win,y,x)        move & delete a line in a window
  167. *  int     mvwgetch(win,y,x)        move & get char to a window
  168. *  int     mvwgetstr(win,y,x,str)        move & get string to a window
  169. *  int     mvwinch(win,y,x)        move & get char at window cursor
  170. *  int     mvwinsch(win,y,x,ch)        move & insert char in a window
  171.    int     mvwinsrawch(win,y,x,ch)    move & insert raw char in a window
  172. *  int     mvwinsertln(win,y,x)        move & insert new line in window
  173.    int     mvwin(win,y,x)            move window on physical screen
  174. *  int     mvwprintw(win,x,y,fmt,args)    move & print string in a window
  175. *  int     mvwscanw(win,y,x,fmt,args)    move & get values via a window
  176. *  WINDOW *newwin(lines,cols,begy,begx)    create a new window
  177. *  void     nl()                set terminal cr-crlf mapping mode
  178. *  void     nocbreak()            unset terminal cbreak mod
  179. *  void     nocrmode()            unset terminal cbreak mode
  180.    void     nodelay(win,bf)        marks window for no input wait
  181. *  void     noecho()            unset terminal echo mode
  182. *  void     nonl()                unset terminal cr-crlf mapping mode
  183. *  void     noraw()            unset raw terminal mode
  184. *  void     overlay(win1,win2)        overlay one window on another
  185. *  void     overwrite(win1,win2)        overwrite one window on another
  186. *  int     printw(fmt,args)        print string in stdscr
  187. *  void     raw()                set raw terminal mode
  188.    void     refrbrk(bf)            set screen update break mode
  189. *  void     refresh()            refresh stdscr
  190.    int     resetterm()            dummy for compatibility
  191. *  int     resetty()            restore terminal I/O modes
  192.    void     reset_prog_mode()        restore terminal I/O modes
  193.    void     reset_shell_mode()        set terminal to default modes
  194.    int     saveoldterm()            dummy for compatibility
  195.    int     saveterm()            dummy for compatibility
  196. *  int     savetty()            save terminal I/O modes
  197. *  int     scanw(fmt,args)        get values via stdscr
  198. *  void     scroll(win)            scroll scrolling region of a window
  199. *  void     scrollok(win,bf)        marks a window to allow scroll
  200.    int     setsrcreg(miny,maxy)        define stdscr's scroll region
  201. *  int     setterm()            dummy for compatibility
  202.    int     setupterm(term,fd,errret)    set up terminal (no-op on PC)
  203. *  void     standend()            start normal chars in stdscr
  204. *  void     standout()            start standout chars in stdscr
  205. *  WINDOW *subwin(win,lines,cols,begy,begx) create a sub-window in window win
  206.    int     tabsize(ts)            set/get tabsize of stdscr
  207. *  void     touchwin(win)            mark a window as totally modified
  208. *  char    *unctrl(ch)            char-to-string converter
  209.    int     ungetch(ch)    (#def macro)    push back a character to input */
  210. *  int     waddch(win,ch)            put char in a window
  211.    int     waddrawch(win,ch)        put raw char in a window
  212. *  int     waddstr(win,str)        put string in a window
  213.    void     wattroff(win,attrs)        clear attribute(s) in window
  214.    void     wattron(win,attrs)        add attribute(s) in window
  215.    void     wattrset(win,attrs)        set window char attributes
  216.    void     wborder(win,l,r,t,b,tl,tr,bl,br) Set non-std box characters
  217. *  int     wbox(win,miny,minx,maxy,maxx,l,r) draw a box inside a window
  218. *  void     wclear(win)            clear a window
  219. *  int     wclrtobot(win)            clear end of a window
  220. *  int     wclrtoeol(win)            clear end of line in a window
  221. *  int     wdelch(win)            delete a char in a window
  222. *  int     wdeleteln(win)            delete a line in a window
  223. *  void     werase(win)            erase a window
  224. *  int     wgetch(win)            get char via a window
  225. *  int     wgetstr(win,buf)        get string via window to a buffer
  226. *  int     winch(win)            get char at window cursor
  227. *  int     winsch(win,ch)            insert character in a window
  228.    int     winsrawch(win,ch)        insert raw character in a window
  229. *  int     winsertln(win)            insert new line in a window
  230. *  int     wmove(win,y,x)            move cursor in a window
  231.    void     wnoutrefresh(win)        create internal screen image
  232. *  int     wprintw(win,fmt,args)        print string in a window
  233. *  void     wrefresh(win)            refresh window
  234. *  int     wscanw(win,fmt,args)        get values via a window
  235.    int     wsetsrcreg(win,miny,maxy)    define a window's scrolling region
  236. *  void     wstandend(win)            start normal chars in window
  237. *  void     wstandout(win)            start standout chars in window
  238.    int     wtabsize(win,ts)        set/get tabsize of a window
  239.    int     wungetch(ch)            push back a character to input */
  240.  
  241. MISSING FUNCTIONS
  242.  
  243.    The following functions existing in UNIX curses are missing in PCcurses:
  244.  
  245.    getcap(nam)                get terminal capability 'name'
  246.  
  247. FUNCTIONS UNIQUE TO PCcurses
  248.  
  249.    The following functions are (to the author's knowledge) unique to PCcurses:
  250.  
  251.    int     addrawch(ch)            put raw char in stdscr
  252.    int     waddrawch(win,ch)        put raw char in a window
  253.    int     mvaddrawch(y,x,ch)        move & put raw char in stdscr
  254.    int     mvwaddrawch(win,y,x,ch)    move & put raw char in a window
  255.    int   insrawch(ch)            insert raw character in stdscr
  256.    int   winsrawch(win,ch)        insert raw character in a window
  257.    int     mvinsrawch(y,x,ch)        move & insert raw char in stdscr
  258.    int     mvwinsrawch(win,y,x,ch)    move & insert raw char in a window
  259.    int   tabsize(ts)            set/get tabsize of stdscr
  260.    int     wtabsize(win,ts)        set/get tabsize of a window
  261.  
  262. SEE ALSO
  263.    "Screen Updating And Cursor Movement Optimization: A Library Package" -
  264.    Kenneth C.R.C. Arnold
  265.    "The Ncurses Reference Manual" - Pavel Curtis, Cornell University
  266.  
  267. BUGS
  268.    The terminal raw I/O mode is implemented by reading characters directly
  269.    from the BIOS. This means that the programmer must not use the normal
  270.    I/O routines to the screen or from the keyboard, since they will trap the
  271.    MS-DOS ^C, ^S, ^Q and ^P characters and thus nullify the raw input.
  272.  
  273.    Also, if the terminal is in normal or cbreak mode and the programmer has
  274.    trapped CTRL-BREAK by using signal(SIGINT,ownhandler), MS-DOS will still
  275.    echo the characters '^C' on the screen when the character is intercepted.
  276.    There seems to be no way to avoid this under MS-DOS (use raw mode in-
  277.    stead, or redraw the whole screen).
  278.  
  279.    The function key support is hardware dependent. There is a table in char-
  280.    get.c that maps keyboard scan codes from the keyboard to function key
  281.    names. The one supplied works for IBM PC/XT/AT, and for most clones.
  282.  
  283. REVISION
  284.    The current revision is v.1.3 (881005). If you find or correct bugs, or if
  285.    you think up or implement enhancements, please contact the author. That way
  286.    he can maintain an 'official' version of PCcurses, without too many local
  287.    versions floating around.
  288.  
  289. AUTHOR
  290.    Home:       Bjorn Larsson        Work:    INFOVOX AB
  291.            Ynglingagatan 5,IV            Box 2503
  292.            S-113 47 Stockholm            S-171 02 Solna
  293.            SWEDEN                SWEDEN
  294.  
  295.            UseNet: ...!seismo!mcvax!enea!infovax!bl
  296.