C/C++ Interactive Guide

home *** CD-ROM | disk | FTP | other *** search

/ C/C++ Interactive Guide / c-cplusplus-interactive-guide.iso / c_ref / csource4 / 298_01 / curses.doc < prev next >

Wrap

Text File | 1988-08-17 | 56.4 KB | 1,473 lines

The PC Curses Library (C) Copyright 1987,1988 Jeffrey S. Dean. All Rights Reserved. PC CURSES LICENSE AGREEMENT The PC Curses Library Package is a copyrighted software package that is being distributed as shareware. It is NOT in the public domain. By using or distributing this package, you agree to the conditions presented below: (1) You may use the PC Curses Library for your own personal use; if you find it useful, you are requested to pay a $20 registration fee. If you are using PC Curses in a commercial, professional, or governmental organization, you are granted a limited license, valid for thirty days, to use this package for evaluation purposes only; if you continue to use this package, you must pay the registration fee. The registration fee entitles you to use the PC Curses library on one machine. It also includes one free upgrade. (2) Source code is available to registered users only. Source code is also copyrighted, and may NOT be freely copied or distributed. The price of the source distribution is $20; in addition to the source modules, it include makefiles (as well as a version of the "make" program and other utilities). (3) The PC Curses Library (except source) may be freely distributed and copied inside the U.S.; however, you may not charge anything for the distribution. The distribution must include everything in the original distribution, including this agreement. You may not distribute this system with any modifications (this includes documentation as well as programs); additions must be placed in separate files and must be clearly marked as such. (4) If any part of the PC Curses Library is used in a program, system, or service that is distributed to machines other than the one originally licensed, there is a nominal fee (in addition to the registration fee) and a simple licensing agreement that must be completed. This fee may be waived if the program or system is distributed as shareware or by a non-profit organization (but the licensing agreement must still be completed). There are no royalties. (5) DISCLAIMER OF WARRANTY: THE PC CURSES PACKAGE IS SOLD "AS IS" AND WITHOUT ANY WARRANTIES, EXPRESS OR IMPLIED, AS TO PERFORMANCE OR MERCHANTABILITY. BECAUSE OF THE DIVERSITY OF CONDITIONS UNDER WHICH THIS PACKAGE MAY BE USED, NO WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE IS OFFERED. THE USER IS ADVISED TO TEST THE PACKAGE THOROUGHLY BEFORE RELYING ON IT. THE USER MUST ASSUME FULL RISK AS TO THE RESULTS AND PERFORMANCE OF USING THE PACKAGE. ANY LIABILITY OF THE AUTHOR OR DISTRIBUTOR WILL BE LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DAMAGES ARISING FROM THE USE OR INABILITY TO USE THIS PACKAGE. Ordering PC Curses PC Curses complete evaluation system . . . $5 PC Curses registration . . . . . . . . . . $20 The following items are available only to registered users: PC Curses source code . . . . . . . . . . . $20 PC Curses redistribution license . . . . . $20 When ordering source code, please specify the compiler (Microsoft or Turbo) and version you are using. All payments must be in U.S. dollars. For orders outside the U.S., please add an extra $15 per order. (The evaluation system is not available outside the U.S.) Send orders and other correspondence to: Jeff Dean 710 Chimalus Palo Alto, CA 94306 Table of Contents Introduction Programmers Notes Standard Curses Functions Terminfo Curses Functions Even Newer Curses Functions Special PC Curses Functions Special PC-Specific Functions Tracing in PC Curses What's Different Version History INTRODUCTION PC Curses is a C Library designed to provide compatibility with the Unix curses package. It was written for applications running on IBM PC compatible computers developed under Microsoft C or Turbo C. The Unix curses package was originally developed at the University of California at Berkeley as a screen management and windowing package, providing various tools for creating and manipulating windows. Its key strength is the ability to deal with many different types of terminals at any line speed in a semi-optimized fashion. For many years, it was the only generally available package that provided windowing capabilities in the Unix environment. PC Curses was produced to aid in porting programs from MS-DOS to Unix, though it is also useful in writing MS-DOS software that may need to be ported to Unix. The PC environment is drastically different from Unix, so while this package is meant to be functionally similar to the Unix one, there are a few small differences externally (but many differences internally). This package is much simpler that the Unix version. Because of the nature of the PC environment, there is no need for anything like cursor motion optimization. Because of the high screen bandwidth, little effort is spent trying to optimize screen output. Because the PC has features not always available in other environments, additional routines (not in the original curses package) are provided. The PC Curses code was developed independently, without reference to the Unix source code. This documentation is based on experience with the curses package, on Ken Arnold's paper "Screen Updating and Cursor Movement Optimization: A Library Package," and on the Unix System V curses documentation. Arnold's paper (or the newer System V documentation) should be considered required reading in order to understand how this system works. The documentation included here summarizes some of the relevant information, and points out differences between the Unix version and the PC version. Note that there are two major versions of curses. The original, produced some time ago at UC Berkeley, used the termcap database. More recently, the termcap (or termlib) database has been recast into the terminfo database, for efficiency and extensions. A new version of curses was written to take advantage of this system. PC Curses derives primarily from the earlier version, with some features of the later version added. In this documentation, the newer version is referred to as "terminfo curses"; elsewhere, you may hear it referred to as "System V curses." Please let us know what you think of this package; any feedback, positive or negative, is appreciated. If you have any suggestions, problems, or code you would like to see included in the distribution, please contact us. We are planning to continue to improve and expand this package, adding subroutines, utilities, and anything else that would prove generally useful to curses programmers. PROGRAMMERS NOTES The basic "unit" of manipulation in curses is a window. Windows are dynamically allocated structures, and are passed around by pointer. Windows represent a rectangular region on the terminal screen. The windows are, in a sense, buffered. There are a variety of operations for writing windows, but no changes visibly take place until a wrefresh() command is issued. At this point, all the changes are written to the physical screen. There are two special windows in the system, created on startup. One is the current screen (curscr), and represents the information that is presently on the screen. The other is the standard screen (stdscr), which is to windows what stdout is to buffered output. It is a window that represents the whole screen, and when a refresh is done, the contents of this window will be written to the physical screen. For simple applications, stdscr may be the only window that a programmer needs. For more information, refer to one of the standard Unix curses documents and/or the curses.h include file for the PC Curses package. STANDARD CURSES FUNCTIONS This section describes functions that are part of the original termcap curses package. The functions preceded by 'mv' are macros (except for mv*printw) that move to the specified location first, and if that move is legal (see move()), then the function is performed. The following definitions are assumed: WINDOW *win; int y,x; CHTYPE ch; ------------------------------ addch(ch) waddch(win,ch) mvaddch(y,x,ch) mvwaddch(win,y,x,ch) ------------------------------ Adds the character to the screen at the current position, replacing whatever was there. The current position is moved to the position after the character; returns ERR if the cursor cannot be moved to that position (e.g., at the end of a window and scrolling is not allowed). Several characters are handled specially: a tab is expanded, assuming tabstops every 8 characters from the window's left edge; a newline causes the rest of the line to be cleared, and the current position to be moved down one line (and over to the left edge if newline translation (see nl and nonl) is on); a return causes the current position to be moved back to the left edge; a backspace causes the current position to be moved left one character (unless at the left edge). Adding a character to a window will cause the cursor to move down to the next line under one of two conditions: if the character is the newline character, or if there is not enough room on the line for the character (wrap). If scrolling is enabled (see scrollok) and if adding the character would cause the cursor to move past the last line of the window (or past the the last line of the scrolling region -- see setscrreg), then the window will scroll. The scrolling is done logically (on the window) as well as physically (on the screen). This means that wrefresh will be called, resulting in a full screen update. PC Curses only: No conversions are done on the characters other than those mentioned above. Thus, control characters and characters out the Ascii range will be displayed as the appropriate graphics character. Note: Adding the characters "\r\n" (return, newline) to the end of a line will clear the entire line, since the return moves to the beginning of the line and newline clears to the end of the line. ------------------------------ addstr(str) waddstr(win,str) mvaddstr(y,x,str) mvwaddstr(win,y,x,str) char *str; ------------------------------ Adds the string to the window at the current position, using waddch. ------------------------------ box(win,vert,hor) CHTYPE vert, hor; ------------------------------ Draws a box around the window, using 'vert' as the vertical line character and 'hor' as the horizontal line character. Note that the box is drawn INSIDE the window, which means that it can be overwritten, just like anything else inside the window. Also note that the current attribute for the window has no effect on the box characters; if you want a box with attributes, they must be OR'ed with the box characters. PC Curses only: curses.h defines four constants convenient for drawing boxes: S_HOR, S_VERT, D_HOR, D_VERT, representing the single and double line horizontal and vertical line-drawing characters. The box routine will automatically figure out the right corner pieces for any combination of these characters; it also tries to "guess" the right attribute. ------------------------------ clear() wclear(win) ------------------------------ Equivalent to werase(win) followed by clearok(win). PC Curses only: All routines that clear any part of the screen (e.g., clear, erase, deleteln, insertln, delch, clrtoeol, clrtobot, etc.) use the current attribute setting. This means that a window can be "filled in" with an attribute (e.g., reverse video, or some color if on a color monitor) and that attribute will be preserved. There is no way to do this in the standard version of curses. ------------------------------ clearok(win,flag) int flag; ------------------------------ Sets/clears the "clear window" flag (works only on windows that cover the full screen). When a (full screen) window is refreshed, if the flag is TRUE, the screen is cleared first, and then the window is redrawn. This can be useful if the screen is trashed by another program. If the flag is set to TRUE on curscr, then the next call to refresh (for any window) will cause the screen to be cleared before redrawing the specified window. ------------------------------ clrtobot() wclrtobot(win) ------------------------------ Clears the window from the current position to the end. Note: This implementation leaves the current position unchanged; some implementations do not. If compatibility is a concern, do not make any assumptions about the cursor position after the completion of this operation. ------------------------------ clrtoeol() wclrtoeol(win) ------------------------------ Clears the window from the current position to the end of the line. ------------------------------ crmode() nocrmode() cbreak() nocbreak() ------------------------------ Macros for setting/clearing tty cbreak mode. Note: crmode() and nocrmode() are from termcap curses. cbreak() and nocbreak() are from terminfo curses. There is no difference between these pairs, aside from name. PC Curses only: A "read" done in cbreak mode is approximated with the MS-DOS "filtered" read, which reads one character and processes some control characters (such as <ctrl-C>). See getch(). ------------------------------ delch() wdelch(win) mvwdelch(win,y,x) ------------------------------ Deleted the character at the current position. Everything to the right is moved over one position, and the rightmost column becomes blank. ------------------------------ deleteln() wdeleteln(win) ------------------------------ Deletes the current entire current line. Everything below is scrolled up, and the last line of the window becomes blank. The current coordinates remain unchanged. ------------------------------ delwin(win) ------------------------------ Deletes the specified window, freeing up associated space in memory. Has no effect on the screen (i.e., it does not clear the window from the screen). ------------------------------ echo() noecho() ------------------------------ Macros for settting/clearing tty echo mode. PC Curses only: A "read" in echo mode is approximated by using unechoed MS-DOS reads, and then echoing the character if echo mode is set. Echoing is done using waddch(); if waddch() returns ERR, then the read will also return ERR. See getch(). ------------------------------ endwin() ------------------------------ The curses termination routine. This routine should be called before exiting the program. It can also be used before a temporary exit, such as a shell escape; to continue afterwards, invoke wrefresh() or doupdate(). Note: The "temporary exit" capability is an unfortunate change added in Sys V. Older versions of Curses used endwin() to free up windows (among other things), but this is not possible with the new definition. Currently, the only way to free up space associated with a window is via delwin(). ------------------------------ erase() werase(win) ------------------------------ Changes the contents of the specified window to all blanks. The current position is reset to the origin. ------------------------------ int getch() wgetch(win) mvgetch(y,x) mvwgetch(win,y,x) ------------------------------ Input character from terminal. The result depends on the "tty mode" (see raw(), crmod(), and echo() functions) and keypad translation (see the keypad() function). Normally, returns the character input. If echo is set, writes the character in the specified window; if the character cannot be written (see waddch()), then ERR is returned. Note: These functions return ints (not chars). Note: The C library also has a getch() function. These two functions are similar but not identical. In particular, like all other curses routines, getch() will not work before initscr() is called. When using the curses library, you will get the curses version, not the library version. PC Curses only: This routine attempts to emulate the Unix- style input by using different MS-DOS input routines, depending on the tty mode. The default modes here may be non- standard, so be sure to set the tty modes exactly as you would like them. ------------------------------ getstr(buf) wgetstr(win,buf) mvgetstr(y,x,buf) mvwgetstr(win,y,x,buf) char *buf; ------------------------------ Gets a line from the terminal and places it in the argument, which is assumed to be large enough. Works by repeatedly calling wgetch until an ERR or a newline is received; in the former case, ERR is returned; in the latter case, the newline is stripped off. The erase character and the line kill character are handled, allowing basic line editing (see erasechar() and killchar()). Note: This function is generally used with echoing enabled. ------------------------------ gettmode() ------------------------------ PC Curses only: This function is a no-op. ------------------------------ getyx(win,y,x) ------------------------------ Sets (y, x) to the current coordinates. This is a macro, so it is not necessary for the arguments to be pointers. ------------------------------ inch() winch(win) mvinch(y,x) mvwinch(win,y,x) ------------------------------ Returns the character at the current position. Note: These functions are implemented according to the new (terminfo) version of curses; this means that they are somewhat incompatible with the old (termcap) version. They return a character which is OR'ed with its attributes (the old versions return a character without its attributes). The constants A_ATTRIBUTES and A_CHARTEXT can be AND'ed with the character to extract the component parts. PC Curses only: For the convenience of termcap curses users, the macro wcinch() is defined to work like the old winch(). The variant forms (cinch, mvcinch, and mvwcinch) are also defined. ------------------------------ initscr() ------------------------------ The curses initialization routine. This routine must be called before any other routine in the curses package. Note: initscr() returns stdscr. NULL is returned on error, which generally means that there was not enough space (i.e., malloc failed). IMPORTANT: The error return condition should always be checked. Performing window operations after initscr fails is certain to cause problems. ------------------------------ insch(ch) winsch(win, ch) mvinsch(y,x,ch) ------------------------------ Inserts the character at the current position. Remaining characters on the line are moved right one position. The character at the rightmost edge of the window will be lost. ------------------------------ insertln() winsertln(win) ------------------------------ Inserts a blank line above the current line. Everything below is scrolled down, and the last line of the window is lost. The current coordinates remain unchanged. ------------------------------ leaveok(win,flag) int flag; ------------------------------ Sets the "leave cursor alone" flag. The flag is meant to indicate whether the cursor is being used in a window. When FALSE (the default setting), the cursor will be moved to the current position whenever the window is refreshed (i.e., the cursor is being used). When TRUE, the action of the cursor is, in general, unpredictable; in the PC Curses implementation, the result is that the cursor is turned off while inside the window. ------------------------------ longname() ------------------------------ PC Curses only: A dummy function, macro-defined to "ibm-pc". ------------------------------ mvcur(lasty, lastx, newy, newx) int lasty, lastx, newy, newx; ------------------------------ Moves the cursor from (lasty, lastx) to (newy, newx), bypassing wrefresh. PC Curses only: The reason for requiring the present coordinates as well as the intended ones is to allow for cursor motion optimization. Since there is no need for this type of optimization in the PC environment, the first two coordinates are ignored. ------------------------------ mvwin(win,y,x) ------------------------------ Changes the location of the window so that the upper left hand corner is at the specified position. If the window cannot be moved to that position, then the original position is left unchanged, and ERR is returned. Note: This routine does not remove the window from its current position on the screen, nor does it redisplay the window in the new position. All it does is change the coordinates that are stored in the window structure. ------------------------------ WINDOW * newwin(lines,cols,begin_y,begin_x) int lines, cols, begin_y, begin_x; ------------------------------ Creates a new window, with the specified number of lines and columns, starting at the specified position. If any of the parameters are zero, they are set to a default value: lines to the maximum number of lines, cols to the maximum number of cols, begin_y and begin_x to zero. Thus, newwin(0, 0, 0, 0) will create a full-screen window. PC Curses only: returns NULL if window cannot be allocated (out of space) or if the window will not fit on the screen. IMPORTANT: The error return condition should be checked. Performing window operations on a nonexistent window is certain to cause problems. ------------------------------ nl() nonl() ------------------------------ Enable/disable newline translation. On input, a carriage return is normally translated to a newline; on output, a newline is normally translated to a carriage return/linefeed sequence. nonl() disables this translation. PC Curses only: The setting of this translation flag has no effect on refresh optimization. However, for greatest compatibility with Unix curses, nonl() is recommended. ------------------------------ overlay(from_win, to_win) overwrite(from_win, to_win) WINDOW *from_win, *to_win; ------------------------------ Overlay and overwrite copy the contents of one window to another. The copy is started at (0,0) in both windows, and is independent of physical screen location. The only difference between overlay and overwrite is that the former does not copy blanks while the latter does. If the windows are of different sizes, the copying is limited to the size of the smaller window. ------------------------------ printw(fmt,arg1,arg2,...) wprintw(win,fmt,arg1,arg2,...) mvprintw(y,x,fmt,arg1,arg2,...) mvwprintw(win,y,x,fmt,arg1,arg2,...) char *fmt; ------------------------------ Perform printf-style output on a window. Uses waddstr to write to the window and returns the result. PC Curses only: The formatted string is temporarily stored in a local buffer, which is currently set to BUFSIZ (512) bytes. It is the caller's responsibility to make sure that no overflow occurs. ------------------------------ raw() noraw() ------------------------------ Macros for enabling/disabling tty raw mode. PC Curses only: A "read" done in raw mode is approximated with the MS-DOS "unfiltered" read, which means that control characters (such as <ctrl-C>) are not processed. See getch(). ------------------------------ refresh() wrefresh(win) ------------------------------ Screen updating in curses is done asychronously. Changes made to a window have no effect on the physical screen until a refresh function is called. The refresh is optimized: only changed parts of a window are examined and compared to what is currently on the screen; the screen is written only when there is a discrepancy. ------------------------------ resetty() savetty() ------------------------------ Macros for restoring and saving current tty modes. PC Curses only: These functions are currently no-ops. ------------------------------ scanw(fmt,arg1,arg2,...) wscanw(win,fmt,arg1,arg2,...) mvscanw(y,x,fmt,arg1,arg2,...) mvwscanw(win,y,x,fmt,arg1,arg2,...) char *fmt; ------------------------------ Performs scanf-style input through a window. Uses wgetstr() to get input, then uses vsscanf() to process the input. PC Curses only: The input string is temporarily stored in a local 128 byte buffer. No overflow checking is done. PC Curses only: These functions depend on vsscanf(), a standard C library routine. At the current time, Microsoft C does not provide this routine. ------------------------------ scroll(win) ------------------------------ Scrolls the specified window up one line. The scrolling is done both logically (in the window) and physically (on the screen). This routine in invoked internally by waddch() when trying to move down past the last line in a scrollable window. Note: The termcap and terminfo definitions of this function appear somewhat different, so rely on the above definition. The original curses documentation states that this routine is not normally invoked by the user; this advice still appears reasonable. The same effect can be achieved by using waddch() to add a newline while on the last line of a window. Note: Scrolling is generally faster for windows that are full width and/or full length. This is true of both PC and Unix implementations, although for different reasons. ------------------------------ scrollok(win,flag) int flag; ------------------------------ Sets the scroll flag for the specified window. When adding a character to a window would cause that character to go off the bottom edge of the window, the window will be scrolled if the scroll flag is set to TRUE. If the flag is set to FALSE (the default condition), the cursor remains on the last line. ------------------------------ setterm(name) ------------------------------ PC Curses only: This function is a no-op. ------------------------------ standend() wstandend(win) ------------------------------ Turns off all attributes for the specified window. See the "attr" functions for more general versions of these routines. ------------------------------ standout() wstandout(win) ------------------------------ Sets standout mode, causing all subsequent characters added to the window to be highlighted (defined in curses.h to be inverse video mode). Attributes "stay" with a character, through scrolling, insertion, deletion, etc. See the "attr" functions for more general versions of these routines. ------------------------------ WINDOW * subwin(win,lines,cols,begin_y,begin_x) int lines, cols, begin_y, begin_x; ------------------------------ Creates a new window; the last four arguments are identical to those of newwin(). However, this new sub-window shares the internal character map with the window specified as the first argument. Any changes made to the sub-window will affect the parent, and any changes to the parent in the shared region will affect the sub-window (it may be necessary to use touchwin() for the changes in one window to be seen in the other). Note that begin_y and begin_x are relative to the whole screen, not to the specified window. Also note that the parent window should not be deleted (with delwin()) if the sub-window is still to be used. PC Curses only: Like newwin(), failure to create a new window will result in a NULL return value. NULL is also returned if the last four arguments do not actually form a sub-window of the specified window. ------------------------------ touchwin(win) ------------------------------ Normal screen updating is optimized so that only changed regions are examined when updating. touchwin() modifies a window so that on the next refresh, the entire window is examined. This is useful when a window may have been overwritten (e.g., by another window). When working with overlapped windows, if a window does not appear correctly on the screen, touching and refreshing it may solve the problem. ------------------------------ tstp() ------------------------------ PC Curses only: This function is a no-op. ------------------------------ char * unctrl(ch) ------------------------------ Returns a string representation of a control character. The string consists of a caret ("^") followed by the upper case representation of the control character. PC Curses only: [1] If the argument to unctrl is not a control character, then the result string will consist of the argument character (unchanged). [2] The result string is a static buffer, and will be overwritten by subsequent calls. [3] The Delete character (Ascii 127, not the delete key) is considered to be a control character, and is mapped to "^?". [4] There is no <unctrl.h> include file. TERMINFO CURSES FUNCTIONS The original version of curses was written for use with the termcap database. When the termcap database facility was rewritten to improve performance and extend capability, a new version of curses was written to accompany it. This terminfo version of curses provides a number of new functions and changes (or refines) the semantics of some of the old functions. The new functions currently supported are described below; a more complete implementation (with the exception of the multiple terminal capability) is planned. The functions that have been changed or refined are still listed in the previous section. ------------------------------ attrset(attrs) wattrset(win,attrs) attroff(attrs) wattroff(win, attrs) attron(attrs) wattron(win,attrs) int attrs; ------------------------------ These functions set the current attribute of the specified window. Attributes defined in the curses.h file are: A_REVERSE reverse video A_UNDERLINE underlined text A_BOLD bold A_BLINK blinking mode A_STANDOUT currently defined as A_REVERSE A_DIM currently defined as A_NORMAL These definitions are for a monochrome system. Color is not part of the standard Unix curses package, but color attribute definitions for PC Curses can be found in the curses.h include file. When a character is written to a window, it is written with the current set of attributes. wattron and wattroff can be used to turn on and off attributes; attrset can be used to set the attributes to any desired state. standout() is the same as attron(A_STANDOUT). standend() is the same as attrset(A_NORMAL). PC Curses only: [1] All the modes correspond to standard PC attributes, with the exception of zero (A_NONE), which PC Curses maps to mean "normal" mode (A_NORMAL). [2] The current attributes are used when clearing any portion of a window. [3] The functions attrget() and wattrget(win) have been added to provide a way to get the current window attributes. ------------------------------ beep() ------------------------------ Beeps. ------------------------------ doupdate() ------------------------------ Maps an internally maintained virtual screen onto the actual screen. See the description of wnoutrefresh() below. ------------------------------ erasechar() ------------------------------ Returns the current erase character. PC Curses only: The current version of this is macro-defined to be backspace. The only PC Curses routine that uses this macro is getstr(). The value can be changed by redefining the macro in curses.h and recompiling (or avoiding) getstr(). ------------------------------ flash() ------------------------------ Flashes the screen. ------------------------------ flushinp() ------------------------------ Flushes the input stream, throwing away any characters that have been typed but not yet read. ------------------------------ idlok(win,flag) int flag; ------------------------------ PC Curses only: This function is a no-op. ------------------------------ keypad(win,flag) int flag; ------------------------------ Sets/clears the keypad translation flag. If the flag is set, getch() translates function keys (which may actually be more than one character) into predefined integer values (see below). PC Curses only: When keypad translation is on, special keys that are in the list below are translated. For handling of "Alt shifted" keys, see the discussion of meta(). The PC Curses implementation is different, and more reliable, than Unix curses. When a function key prefix character is received, Unix curses waits for up to one second for the next character in the function key sequence; if it does not receive the key, it returns with the prefix character. As a result, keypad translation in the Unix environment may appear "jerky," and timing delays may even cause a function key to go unrecognized. In the PC environment, the prefix character is unique, and whenever it is seen, the rest of the function key sequence is already there. This results in a much "smoother" implementation. Translation values: KEY_BREAK 0x101 -- unused in PC Curses KEY_DOWN 0x102 -- DOWN ARROW KEY_UP 0x103 -- UP ARROW KEY_LEFT 0x104 -- LEFT ARROW KEY_RIGHT 0x105 -- RIGHT ARROW KEY_HOME 0x106 -- HOME KEY KEY_F0 0x108 -- dummy value KEY_F(x) (KEY_F0+(x)) -- FUNCTION KEYS KEY_DL 0x148 -- unused in PC Curses KEY_IL 0x149 -- unused in PC Curses KEY_DC 0x14a -- DELETE KEY KEY_IC 0x14b -- INSERT KEY KEY_EIC 0x14c -- unused in PC Curses KEY_CLEAR 0x14d -- unused in PC Curses KEY_EOS 0x14e -- unused in PC Curses KEY_EOL 0x14f -- unused in PC Curses KEY_SF 0x150 -- unused in PC Curses KEY_SR 0x151 -- unused in PC Curses KEY_NPAGE 0x152 -- PAGE DOWN KEY KEY_PPAGE 0x153 -- PAGE UP KEY KEY_STAB 0x154 -- unused in PC Curses KEY_CTAB 0x155 -- unused in PC Curses KEY_CATAB 0x156 -- unused in PC Curses KEY_ENTER 0x157 -- unused in PC Curses KEY_SRESET 0x158 -- unused in PC Curses KEY_RESET 0x159 -- unused in PC Curses KEY_PRINT 0x15a -- unused in PC Curses KEY_LL 0x15b PC Curses only: The following definitions have been added for the PC environment: KEY_END KEY_LL -- END KEY KEY_sF(x) (KEY_F(10)+x) -- SHIFTED FUNCTION KEYS KEY_cF(x) (KEY_SF(10)+x) -- CONTROL FUNCTION KEYS KEY_aF(x) (KEY_CF(10)+x) -- ALT FUNCTION KEYS KEY_cNPAGE 0x180 -- CTRL-PGDN KEY_cPPAGE 0x181 -- CTRL-PGUP KEY_cHOME 0x182 -- CTRL-HOME KEY_cEND 0x183 -- CTRL-END KEY_cLEFT 0x184 -- CTRL-LEFTARROW KEY_cRIGHT 0x185 -- CTRL-RIGHTARROW KEY_cPRTSC 0x186 -- CTRL-PRTSC KEY_BTAB 0x187 -- SHIFTED (REVERSE) TAB Any PC function keys which are not defined above will return the appropriate two character extended code instead. ------------------------------ killchar() ------------------------------ Returns the current line kill character. PC Curses only: The current version of this is macro-defined to be Control-U. The only PC Curses routine that uses this macro is getstr(). The value can be changed by redefining the macro in curses.h and recompiling (or avoiding) getstr(). ------------------------------ meta(win, flag) int flag ------------------------------ Provides eight bit input through the specified window. PC Curses only: When input is done through a window with meta mode on, the 'Alt' key is treated like a meta key, and so extended character codes involving the Alt key get turned into the appropriate characters with the meta (parity) bit set. [Note that the Alt key cannot be used in combination with the control key.] When meta mode is off, the extended character codes get passed through untranslated. Note: Unlike Unix curses, PC Curses always provides 8 bit character input, regardless of meta(). ------------------------------ WINDOW * newpad(lines,cols) int lines, cols; ------------------------------ A pad is similar to a window, with two differences. First, a pad may be of any size; it is not bounded by the size of the screen. Second, any part of the pad may be displayed on any part of the screen; the origin is not specified when the pad is created. The structure of a pad is identical to the structure of a window. The two may be used interchangeably, except when refreshing. Since there is no fixed relationship between the pad and the screen, the relationship must be specified when refreshing. This is done with the special refresh functions prefresh() and pnoutrefresh(); wrefresh() or wnoutrefresh() should not be called with a pad as an argument. All of the other standard curses functions can be applied to pads. The only difference is that certain functions which automatically refresh a window (e.g., getch, addch) will not refresh the pad. PC Curses only: Returns if NULL pad cannot be allocated. ------------------------------ nodelay(win, flag) int flag; ------------------------------ Sets/clears nodelay mode. When nodelay mode is not set, getch() will not return until a character has been input. When nodelay mode is set, getch() will always return immediately. If there was input present, it will return the character; otherwise, it will return -1. ------------------------------ pnoutrefresh(pad, pminy, pminx, sminy, sminx, smaxy, smaxx) prefresh( pad, pminy, pminx, sminy, sminx, smaxy, smaxx) WINDOW *pad; int pminy, pminx, sminy, sminx, smaxy, smaxx; ------------------------------ Refreshes a pad (corresponds to wnoutrefresh or wrefresh for a window). A rectangular area of the pad, starting with the upper left corner specified by (pminy,pminx) is mapped to a rectangular area on the screen, specified by the upper left corner (sminy,sminx) and the lower right corner (smaxy,smaxx). The lower right corner is implicit. See newpad() for a description of pads. PC Curses only: Returns ERR on failure. Failure occurs if the argument is not a pad, or if either of the rectangular areas exceeds the bounds of the associated object. ------------------------------ setscrreg(top,bot) wsetscrreg(win,top,bot) int top, bot; ------------------------------ Defines a scrolling region inside a window. The top line of the scrolling region is set to "top" and the bottom line is set to "bot". These values are relative to the window. If scrolling for the window is enabled, the window will be scrolled when adding a character would cause the cursor to move past the bottom line of the region. Scrolling occurs when adding a character to the last line of a region, and when that character is a newline, or that character would go past the end of the line. This means that the only routine which scrolls the screen is waddch(), or any other routine that calls it (waddstr(), wgetch(), etc.). A window with no scrolling region is equivalent to a window whose scrolling region is the entire window. Thus, scrolling regions allow the creation of a window-like region within a window. PC Curses only: Returns ERR if the specified scrolling region is out of range. The scrolling region can be disabled by setting both top and bottom values to zero. ------------------------------ wnoutrefresh(win) ------------------------------ The pair of functions (wnoutrefresh, doupdate) provide similar functionality to the single function wrefresh(). Wnoutrefresh() writes the specified argument onto an internally maintained virtual window, representing what should be on the screen. Unlike wrefresh(), nothing is actually written on the screen. Doupdate() does the actual update, making the screen look like the virtual screen. These functions are most useful when updating several (possibly overlapping) windows. With wrefresh(), some unnecessary drawing might be done in this case. By calling wnoutrefresh() for each window, then doupdate() at the end, redundant screen updates would be eliminated. PC Curses only: Wrefresh() is equivalent to wnoutrefresh() followed by doupdate(). For efficiency reasons, wrefresh has not been written exactly this way (although it acts exactly like it was implemented this way). Unless the power of wnoutrefresh is needed, wrefresh is a better choice. EVEN NEWER CURSES FUNCTIONS The curses package has continued to evolve. The latest version of AT&T Sytem V release 3 Unix added several new capabilities to curses. The newer capabilities supported by PC Curses are described below. Also, see the curses.h include file for the line graphics characters now supported by System V.3. ------------------------------ copywin(swin,dwin,sminy,sminx,dminy,dminx,dmaxy,dmaxx,overlay) WINDOW *swin,dwin; int sminy, sminx, dminy, dminx, dmaxy, dmaxx, overlay; ------------------------------ Copies a rectangular region from the source window (swin) to the destination window (dwin). The starting point in the source window is specified by (sminy,sminx). The data is copied to the region in the destination window specified by the upper left corner (dminy,dminx) and the lower right corner (dmaxy,dmaxx). If overlay is non-zero, copying is done only to character positions that are blank. PC Curses only: In the current implementation, overlay() and overwrite() are macros which invoke copywin(). Note: copywin() is a quick and convenient way of saving the contents of a window (or part of a window) in another window. ------------------------------ curs_set(mode) int mode; ------------------------------ Low level curses function, not normally used directly. Sets the cursor, depending on the mode argument. Currently, only modes 0 (invisible) and 1 (visible) are supported. This routine is used internally by the screen update routines, which look at the leaveok() flag to determine if the cursor should be made invisible. ------------------------------ getbegyx(win,y,x) getmaxyx(win,y,x) ------------------------------ Macros similar to getyx(). getbegyx() gets the beginning coordinates of the window (corresponding to the last two parameters passed to newwin). getmaxyx() gets the size parameters of the window (corresponding to the first two parameters passed to newwin). ------------------------------ vwprintw(win,fmt,ap) vwscanw(win,fmt,ap) char *fmt; va_alist ap; ------------------------------ vwprintw() is the varargs (variable argument) version of wprintw(). wscanw() is the varargs version of wscanw(). See the Unix (or PC Compiler) manual section for more information on varargs. SPECIAL PC CURSES FUNCTIONS The following functions are additions to the normal curses package. They are provided for programming convenience. These functions are coded on top of curses and are designed to be source-code compatible with Unix curses. These routines are experimental, and subject to change. ------------------------------ drawbox(win, vert, hor, begin_y, begin_x, end_y, end_x) CHTYPE vert, hor; int begin_y, begin_x, end_y, end_x; ------------------------------ Generalized version of box(). Draws a box anywhere in the specified window. The box is specified by the "begin" and "end" coordinates. If both coordinates specify the same point, or if the coordinates are out of range, nothing is drawn. See box() for a further discussion of how boxes are drawn. box(win, vert, hor) is equivalent to drawbox(win, vert, hor, 0, 0, 0, 0) ------------------------------ WINDOW * shadowwin(win, shadow) WINDOW *win,*shadow; ------------------------------ Creates a "shadow" of a window. A window's shadow is the part of the current screen that is replaced when the window is displayed. The concept of shadows is useful when dealing with pop-up windows, which need to appear and disappear without permanently disturbing what is on the screen. The first argument is the window whose shadow is to be taken. The second argument is the shadow window, which will hold the shadow. If the second argument is NULL, a new window is allocated for the shadow. The routine returns the shadow window, or NULL on error. Possible errors are inability to allocate a window, or if the window and its shadow are not the same size. A shadow is no different than any other window. All the standard routines for dealing with windows can be applied, though generally only a small number of routines are really appropriate. To pop-up a window, save its shadow with this function before displaying the pop-up window on the screen (unless this is the first time the pop-up is displayed, it will probably be necessary to invoke touchwin on the pop-up). To remove the pop-up window, redisplay the shadow with wrefresh(), thereby restoring the previous contents of the screen. SPECIAL PC-SPECIFIC FUNCTIONS The following functions are PC specific functions, and have may have no meaning on other systems. ------------------------------ pc_uptype(flag) int flag; ------------------------------ Sets the screen update method. Legal values for "flag" are T_BIOS for bios updates, and T_DIRECT for direct video memory updated. Note that in either case, any screen driver is bypassed; thus, an ansi screen driver (e.g., ANSI.SYS) is not required for applications written with this library. The default method is T_BIOS updating, which is compatible across a much wider range of machines. It also reduces or eliminates flicker on certain types of monitors. However, it is significantly slower than direct video memory updates. Setting the update method to T_DIRECT forces direct updates. pc_uptype() attempts to automatically figure out the address of video memory. The current algorithm for this is experimental. To provide a backup in case of failure, pc_uptype() can be called with flag set to the segment address of video memory. This feature may go away in the future. This function is experimental, and is subject to change. TRACING IN PC CURSES PC Curses has a built-in tracing facility. The libraries "sdcurses" and "ldcurses" are the debugging/tracing versions of the curses, corresponding to the standard libraries "scurses" and "lcurses". The tracing facility records most function calls and parameters in a log file. Since high frequency functions, such as waddch() and wmove() are logged, tracing tends to slow down things considerably. It also causes the log to grow very rapidly. To prevent the log file from growing too large, it is cleared out each time the program is run. Why is tracing useful? Tracing is a simple way of seeing what your program is doing. It is easy to use and does not require the source code to be available. Tracing is most commonly used to track down program bugs. It is also useful for analyzing performance, since it provides a picture of which routines are invoked (and some idea of what they are doing). To create a traced version of your program, link with one of the tracing libraries instead of the regular curses libraries. To start tracing, create a file named "trace.log" in the directory in which the program runs. When you exit your program, the output will be in trace.log. Note that the log file is closed by a call to endwin(); if the call to endwin() is omitted, the log file may be truncated. In looking at trace.log, pay special attention to messages flagged by two exclamation marks "!!". These indicate an error condition (note that not all error conditions are fatal). For finer control of tracing, the functions traceon() and traceoff() can be used. The "trace.log" file must still be set up as described above (if it does not exist, these functions will have no effect). Since tracing can be quite slow, judicious use of these functions will result in considerable speedup as well as a much smaller trace.log file. While most versions of curses provide tracing facilities, they all differ in implementation. This description of tracing should be considered specific to PC Curses. ------------------------------ traceon() traceoff() ------------------------------ Turns tracing on and off. Tracing is initialized by initscr(). The file "trace.log" must exist in the starting directory when initscr() is called; if not, these functions have no effect. These functions also have no effect before initscr() is called. When tracing is initialized, a warning message is printed out on the screen, to warn that things may be very slow. ------------------------------ traceclose() ------------------------------ Closes the trace log file. This forces any output that might be buffered out to the log file. This routine is normally called by endwin(). Subsequent tracing will cause the file to be reopened automatically. ------------------------------ tracedump(win, flag) int flag; ------------------------------ Dumps the window to the trace log file. If flag is 0, only the window parameters are dumped; if flag is non-zero, the entire character map of the window is also dumped. ------------------------------ traceprint(fmt,arg1,arg2,...) char *fmt; ------------------------------ Performs printf-style output to the trace log file. This is the routine that is used internally to log all function calls. It can be used to log your own information in the trace log file. WHAT'S DIFFERENT? The current version of PC Curses contains most of the functions from the Unix termcap and terminfo versions of curses. There are two groups of functions that are not included: multiple terminal functions - will not be supported. terminfo level functions - unlikely to be supported VERSION HISTORY The important changes between versions of PC Curses are described below; there may be other fixes, enhancements, and additions not mentioned. Version 0.8 (9/88) - Microsoft C library built with version 5.0, using /Ox - Turbo C library built with version 1.5 - added vwprintw() and vwscanw() - added wscanw() and related functions (Turbo C only) - added copywin() - added getbegyx() and getmaxyx() macros - added support for medium model in low.asm - added the "ACS_" line graphics definitions to curses.h - changed all void functions to return OK - replaced definition KEY_sTAB with KEY_BTAB - fixed problem caused when using nodelay() without keypad() - fixed problem in getstr() caused when deleting characters - fixed problem with missing screen update after clearok() - fixed pad functions to properly check screen size - fixed problem which allowed addch() to move past last column Version 0.7 (9/87) - added support for Turbo C - added function prototypes to curses.h - fixed problem with incorrect calculation of subwindow offsets Version 0.6 (6/87) - fixed problem with subwindows - fixed problems that occurred only on some PCs: - stack overflow - disappearing screen after program termination - rewrote several low level functions in assembly Version 0.5 (5/87) - fixed incorrect handling of clearok() - defined A_CHARTEXT (instead of A_CHARSET) - changed initscr() to return stdscr Version 0.4 (3/87) - Added pads. - Added tracing. - Added scrolling regions. - Added meta character translation (using the Alt key). - Added shadow windows for pop-up support. - Added #ifdef's to allow custom versions. - Added support for color attributes. - Fixed addch to physically scroll windows. - Fixed the case sensitivity problem in the assembly module. - Fixed problem with deallocation of scrolled windows. - Removed the PC-specific scrolling functions. Version 0.3 (2/87) - Added terminfo-style screen updating (wnoutrefresh and doupdate). - Added unctrl() for handling control characters. - Fixed getstr to handle erase and kill characters. Version 0.2 (1/87) - Added leaveok(), so that cursor can be turned off. - Added sub-windows. - Modified screen clearing code to use current attribute. Version 0.1 (1/87) - Added unix.h for porting programs to Unix. - Added support for direct screen updates. - Added keypad() and function key recognition to wgetch(). - Recoded critical routines in assembly. - Made internal names start with underscore (unless static). Version 0.0 (12/86) - First release of PC Curses.