EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) ------------------------------------------------------------------------------- extended curses library PURPOSE Controls cursor movement and windowing. LIBRARY Extended Curses Library (libcur.a) SYNTAX #include DESCRIPTION The Extended Curses subroutines control input and output to a workstation, performing optimized cursor movement, windowing, and other functions. This package is based on the curses subroutine package, which is included in most UNIX-compatible systems. The curses subroutines are also included in AIX for complete compatibility with existing programs (see "curses"). However, curses and Extended Curses cannot both be used by the same program. The enhancements provided by Extended Curses include: o A wider range of display attributes o Generalized drawing of boxes o Terminal-independent input data processing o Extended window control o Pane, panel, and field concepts o Support for extended characters o Handling of locator input. TERMINOLOGY window The internal representation of what a portion of the display may look like at some point in time. Windows can be any size from the entire display screen to a single character. screen A window that is large as the display screen. A screen named stdscr is automatically provided. terminal Sometimes called a terminal screen. A special screen that is the Extended Curses package's understanding of what the workstation's display screen currently looks like. The terminal screen is identified by a window named curscr, which should not be accessed directly by the user. Instead, changes should be made to stdscr (or a user-defined screen) and then refresh (or wrefresh) should be called to update the terminal. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 1 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) presentation space The array that contains the data and attributes associated with a window. pane An area of the display that shows all or part of the data contained in a presentation space associated with that pane. active pane The pane in which the text cursor is positioned. A pane must be active before you can do input. panel A group of one or more panes that are treated as a unit. The panes of a panel are displayed together, erased together, and usually represent a unit of information to a person using the application. A panel is represented on the display as a rectangular area that is tiled (completely filled) with panes. field An area in a presentation space into which the program accepts input. extended character A character other than 7-bit ASCII that can be represented in either 1 or 2 bytes. (See "data stream.") NLSCHAR Represents an mbchar_t (unsigned long) character stored in four bytes. It is used for both interface data (arguments to library functions) and internal representation of a character. When a double display width character needs to be displayed where only a single display width space is available, then a partial-character indicator is displayed instead. The partial-character indicator is the @ (at sign), and it is represented by the constant pd_char. See the discussion of Extended Curses in AIX Programming Tools and Interfaces, and "Introduction to International Character Support" in Managing the AIX Operating System for more detailed information about these concepts. LINKING THE EXTENDED CURSES ROUTINES The Extended Curses routines also call terminfo subroutines, which are located in the Curses Library (libcurses.a). Therefore, compile programs that use Extended Curses routines with the flags -lcur and -lcurses. HEADER FILES o The cur00.h header file replaces curses.h when converting programs that use the original curses package to Extended Curses. o All of the routines require the cur01.h header file. o The key codes returned by getch are defined in cur02.h. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 2 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) o The cur03.h header file defines attribute priority codes, and is not needed by application programs. o The unctrl routine requires cur04.h. o The routines that manage panes and panels (the routines whose names begin with ec) also require the cur05.h header file. NAMING CONVENTIONS The new routines added to the original curses package begin with the letters ec. Many routines operate on stdscr, the standard screen, by default. Corresponding routines that allow you to specify a window have the same name, prefixed with the letter w. For example, addch adds a character to stdscr, while waddch allows you to specify the window. Sometimes a routine beginning with p also exists, such as paddch, which allows you to specify a pane. Some routines also allow you to specify cursor movement with the action to be performed. These routines have a prefix of mv. Thus, addch becomes mvaddch, waddch becomes mvwaddch, and paddch becomes mvpaddch. Each of these routines is equivalent to calling move or wmove before performing the operation. The various prefixed forms of the routines are implemented as macros. In each case, the routine beginning with w is the base subroutine from which the others are defined. PARAMETERS The following declarations serve for all of the routines: char ch *string; NLSCHAR xc; int line, col, firstline, firstcol; int numlines, numcols, numchars, length, mode; bool boolf; WINDOW *win, *win1, *win2, *oldwin, *newwin; PANE *pane; PANEL *panel; RETURN VALUES Unless otherwise noted, each routine returns a value of type int that is either OK (indicating successful completion) or ERR (if an error is encountered). THE EXTENDED CURSES ROUTINES The Extended Curses routines are listed here alphabetically, except that routines with w, p, and mv prefixes are listed with the corresponding routine that does not have these prefixes. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 3 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) addch (xc) waddch (win, xc) paddch (pane, xc) mvaddch (line, col, xc) mvwaddch (win, line, col, xc) mvpaddch (pane, line, col, xc) The xc parameter is a value of type NLSCHAR. The addch routine adds the NLSCHAR specified by the xc parameter on the window at the current (line, col) coordinates. paddch adds the character to the presentation space for the pane specified by the pane parameter. If the character is "'\n'" (new-line character), the line is cleared to the end, and the current (line, col) coordinates are changed to the beginning of the next line. A "'\r'" (return character) moves the current position to the beginning of the current line on the window. A "'\t'" (tab character) is expanded into spaces in the normal tabstop positions of every eighth column. Adding a character to the lower right corner of a window that includes the lower right corner of the display causes many terminals to scroll the entire display image up one line. If adding a character or a character attribute causes such scrolling to occur, addch makes the change on the window but does not mark it for wrefresh purposes; addch returns the value ERR. A double display width character must be added to addch in a single call. If adding a character would cause that character to split across two lines, the system appends a blank to the end of the current line and adds the entire character at the beginning of the following line. If an added character overwrites half an existing two-byte character, the system replaces the remaining half of that existing character with a blank. addstr (string) waddstr (win, string) paddstr (pane, string) mvaddstr (line, col, string) mvwaddstr (win, line, col, string) mvpaddstr (pane, line, col, string) The addstr routine adds the string pointed to by the string parameter on the window at the current (line, col) coordinates. The string can contain single-shift control codes. Upon successful completion, addstr returns OK and the current (line, col) coordinates point to the location just beyond the end of the string. The addstr routine returns ERR if an attempt is made to add a character to the lower right corner of a window that includes the lower right corner of the display. In this case, addstr writes as much of the string on the window as possible. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 4 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) waddfld (win, string, length, numlines, numcols, mode, xc) The waddfld routine adds data to a field within a window. The current coordinates specify the upper-left corner of the field in the window. The numlines and numcols parameters specify the number of lines and columns in the field, respectively. The length parameter specifies the length of the data. The mode parameter specifies the attribute for the field output. The xc parameter specifies the NLSCHAR that is used to fill the remainder of the field after the data has been added to it. The xc parameter must be in single display width; otherwise ERR is returned. If the string contains a "'\n'" (new-line character), the fill character is added to the remainder of the columns on that line of the field, and the remainder of the data is added starting at the first column of the next line of the field. A "'\r'" (return character) changes the current position to the beginning column of the field. A "'\t'" (tab character) is expanded with fill characters up to the next normal tabstop position within the field. The waddfld routine follows the same rules as addch for adding double display width characters. beep ( ) The beep routine sounds the speaker or bell at the workstation. box (win, System V, hor) NLSCHAR System V, hor; The box routine draws a box around the window specified by the win parameter. box uses the NLSCHAR specified by the System V parameter to draw the vertical sides of the box, and the NLSCHAR specified by the hor parameter for drawing the horizontal lines and corners. If the window includes the lower right corner of the display and scrollok is not set, then the lower right corner of the box is not shown on the window, and the box routine returns ERR. The box routine is a macro that invokes superbox. cbox (win) The cbox routine draws a box around the window specified by the win parameter. The characters used are those defined in /usr/lib/terminfo (type 1 box characters) or defaulted during the initialization. The cbox routine is implemented as a macro that invokes superbox. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 5 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) The cbox routine returns ERR if the window includes the lower right corner of the display and scrollok is not set on. chgat (numchars, mode) wchgat (win, numchars, mode) pchgat (pane, numchars, mode) mvchgat (line, col, numchars, mode) mvwchgat (win, line, col, numchars, mode) mvpchgat (pane, line, col, numchars, mode) The chgat routine changes the attributes of the next numchars characters on the window starting from the current (line, col) coordinates. The attributes are changed to the attributes specified by the mode parameter. This routine does not wrap around to the next line; however, specifying a value for the numchars parameter that would cause a line wrap is not an error. The mode parameter is one or more of the attributes defined by the global attribute variables. More than one attribute may be specified by logically ORing them together. The following example changes the attributes of the next 10 characters to bold blue characters on a black background: chgat (10, BOLD | F_BLUE | B_BLACK) The range of columns to be changed should include entire characters. The numchars variable refers to the number of single or double width display characters. If the current (line, col) position is on the second column of a double display width character, clearing begins at position col "-1". The chgat routine returns ERR if the change forces scrolling and scrollok is not set on for the window. clear ( ) wclear (win) The clear routine resets the entire stdscr window to blank characters. clear sets the current (line, col) coordinates to (0, 0). clearok (scr, boolf) WINDOW *scr; The clearok routine sets the clear flag for the screen specified by the scr parameter. If the boolf parameter is TRUE, the screen is cleared on the next call to refresh or wrefresh. If the boolf parameter is FALSE, the screen is not cleared on the next call to refresh or wrefresh. This only works on screens, and, unlike clear, does not alter the contents of Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 6 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) the screen. If the scr parameter is curscr, the next refresh will cause a clear-screen, even if the window passed to refresh is not a screen. The clearok routine returns ERR if the window is not a full-screen window. clrtobot ( ) wclrtobot (win) The clrtobot routine erases the window from the current (line, col) coordinates to the bottom. clrtobot leaves the current (line, col) coordinates unchanged. This does not force a clear-screen sequence on the next refresh. If the current (line, col) position is on the second column of a double display width character, clearing begins at position col "-1". The clrtobot routine always returns the value OK. clrtoeol ( ) wclrtoeol (win) The clrtoeol routine clears the window from the current (line, col) coordinates to the end of the current line. The current (line, col) coordinates are not changed. If the current (line, col) position is on the second column of a double display width character, clearing begins at position col "-1". The clrtoeol routine always returns the value OK. colorend ( ) wcolorend (win) The colorend routine returns the terminal to NORMAL mode. By default, NORMAL is usually defined as (F_WHITE | B_BLACK). The colorend routine is a macro that invokes xstandend. The colorend routine always returns the value OK. colorout (mode) wcolorout (win, mode) The colorout routine sets the current standout bit-pattern of the window (win"->"_csbp) to the attribute specified by the mode parameter. Characters added to the window after such a call will have mode as their attribute. The mode parameter is constructed by logically ORing together attributes that are declared in the cur01.h header file that are supported by the terminal. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 7 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) The colorout routine overrides the current setting of the window and works in conjunction with almost all of the routines that cause output to be placed on the window. The colorout routine is a macro that invokes xstandout. The colorout routine always returns the value OK. cresetty (boolf) The cresetty routine resets the terminal to the state saved by the last call to csavetty. Use this routine after the completion of a program that uses the terminal as a simple terminal. If the boolf parameter is TRUE, then the data in curscr is redisplayed. crmode ( ) nocrmode ( ) The crmode routine turns off the canonical processing of input by the system device driver. When canonical processing is off, data is made available without waiting for a "'\n'" (new-line character). nocrmode enables canonical processing by the system device driver. The wgetch routine, which is used for all Extended Curses input, forces the equivalent of crmode before requesting input if echoing is active, and reinstates the original status on exit. If you are using echo, you should issue a call to either crmode or raw to avoid multiple calls by wgetch. The crmode routine differs from raw in that crmode has no effect on output data processing and does not disable signal processing by the device driver. The crmode routine always returns the value OK. csavetty (boolf) The csavetty routine saves the current Extended Curses state so that it can later be reset by cresetty. Use this routine before running a program that uses the terminal as a simple terminal. If the boolf parameter is TRUE, then the following status is set before saving the terminal status: crmode, noecho, meta, nonl, and keypad (TRUE). delay See nodelay on page 27 Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 8 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) delch ( ) wdelch (win) mvdelch (line, col) mvwdelch (win, line, col) The delch routine deletes the character at the current (line, col) coordinates. Each character after the deleted character on the line shifts to the left, and the last characters become blank. The delch routine always returns the value OK. deleteln ( ) wdeleteln (win) The deleteln routine deletes the current line. Every line below the current line moves up, and the bottom line becomes blank. The current (line, col) coordinates remain unchanged. The deleteln routine always returns the value OK. delwin (win) The delwin routine deletes the window specified by the win parameter. All resources used by the deleted window are freed for future use. If a window has a subwindow allocated inside of it, the deletion of the window does not affect the subwindow even though the subwindow is invalidated. Therefore, subwindows must be deleted before the outer windows are deleted. The delwin routine always returns the value OK. dounctrl (boolf) The dounctrl routine turns the printing of control characters on or off. If the boolf parameter is TRUE, then the printing is turned on; if FALSE, printing is turned off. By default, dounctrl processing is initially turned off. The unctrl routine defined in cur04.h is used to get the string of printable characters being printed. Control characters become the printable character represented by the control character plus 0x40, preceded by a ^ (circumflex). drawbox (win, line, col, numlines, numcols) The drawbox routine draws a box with the upper left corner located at the position specified by the line and col parameters. The numlines Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 9 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) parameter specifies the number of rows to be used by the box, and the numcols parameter specifies the number of columns to be used by the box. The characters used to draw the box are either those specified in the terminfo file, or those defaulted at initialization. The drawbox routine returns ERR if part or all of the box is outside the window, or the box addresses the lower right corner of the screen and scrollok is not on. #include ecactp (pane, boolf) The ecactp routine specifies the active pane in a panel. The pane specified by the pane parameter is made the active pane if the boolf parameter is TRUE. If an active pane has been previously designated, then the border of that pane is reset to the inactive display mode, and the border of the pane specified by the pane parameter is set to the active display mode. If the boolf parameter is FALSE, then the border of the pane specified by the pane parameter is set to the inactive display mode. #include ecadpn (pane, win) The ecadpn routine adds the window specified by the win parameter to the list of windows that can be presented in the pane specified by the pane parameter. No visible action occurs as a result of this routine. A call to ecaspn must be made after ecadpn to change the data associated with the pane display. The ecadpn routine returns ERR if the system is unable to allocate the storage required. #include ecaspn (pane, win) The ecaspn routine makes the window specified by the win parameter the current window for display in the pane specified by the pane parameter. A refresh call for the pane or panel is needed to cause the data to be presented on the display. The viewport associated with the pane is positioned with the top left corner of the viewport at the top left corner of the data for the window. The ecaspn routine returns ERR if the window specified by the win parameter was not previously associated with this pane using ecadpn. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 10 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) #include WINDOW *ecblks ( ) The ecblks routine returns a pointer to a window that is filled with blanks. This window is intended to be used as a filler for panes that have no real content. It requires less storage than normal windows because all lines will always contain blanks. Do not modify or delete this window. #include PANEL *ecbpls (numlines, numcols, firstline, firstcol, title, divdim, border, pane) short numlines, numcols, firstline, firstcol; char *title; char divdim, border; The ecbpls routine builds a panel structure. The numlines parameter specifies the panel size in rows. The numcols parameter specifies the panel size in columns. The firstline parameter specifies the panel's origin on the display's upper left corner row coordinate. The firstcol parameter specifies the panel's origin on the display's upper left corner column coordinate. The title parameter points to a title string. The title is shown centered in the top border. If no title is desired, this parameter should be NULL. The divdim parameter specifies the dimension along which this panel is to be divided: either Pdivtyv (vertical) or Pdivtyh (horizontal). The border parameter indicates whether or not this panel is to have a border: either Pbordry (yes) or Pbordrn (no). The pane parameter points to the first pane that defines the divisions of this panel. All parameters should be given as defined here. However, they are not checked or used until a call is made to ecdvpl. An application may modify values put into this structure until it calls ecdvpl. Upon successful completion, a pointer to the new panel is returned. ecbpls returns ERR if there is not enough storage available. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 11 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) #include PANE *ecbpns (numlines, numcols, ln, ld, divdim, ds, du, border, lh, lv) short numlines, numcols, ds; PANE *ln, *ld, *lh, *lv; char divdim, du, border; The ecbpns routine builds a pane structure. The numlines parameter specifies the number of rows in the presentation space for the pane. The numcols parameter specifies the number of columns in the presentation space for the pane. The ln parameter points to a neighboring pane either above or to the left. The ld parameter points to the start of a chain for divisions of the pane. The divdim parameter specifies the dimension of the pane along which division is to occur. This parameter is used if and only if the ld parameter is not NULL. Valid values for this parameter are Pdivpnv (vertical dimension) and Pdivpnh (horizontal dimension). The ds and du parameters together specify the size of this pane as part of the division of a parent pane: du Vertical or Horizontal Size of the Pane Pdivszc The size is specified by the ds parameter. Pdivszp The size is ds / 10000 of the available space. For example, if ds is 5000, then the row or column size is half of the available space. Pdivszf The pane has a floating size. The value of the ds parameter is not used. If you specify NULL for the ld parameter or if you are not sure which value to use for du, specify Pdivszf for the du parameter. The border parameter specifies whether or not this pane has a border: either Pbordry (yes) or Pbordrn (no). The lh parameter points to a pane that is to scroll with this pane when the pane scrolls horizontally. The lv parameter points to a pane that is to scroll with this pane when the pane scrolls vertically. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 12 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) If the ln parameter is not NULL, the divs field of the pane structure being built receives the value that was in the ln.divs field. The ln.divs field is modified to point to the new pane structure being built. If the lh and the lv parameters are not NULL, they are used to link the new structure to the specified structures and to link the specified structures to the new structure. The links thus created form a ring that includes all panes that scroll together. Upon successful completion, a pointer to the new pane structure is returned. ecbpns returns ERR if a error is detected during processing. #include ecdfpl (panel, boolf) The ecdfpl routine creates the Extended Curses WINDOW structures needed to define the specified panel. At the time this routine is invoked, all size and location specifications of the panel and its constituent panes must be properly set. ecdfpl does not examine any of the division size specifications or the scroll link specifications. The fpane pointer in the indicated PANEL structure must point to the first leaf pane for the panel, and the subsequent nxtpn pointers from that pane must form a loop back to the first leaf pane. (This is done by ecdvpl.) A WINDOW structure is built for the panel specified by the panel parameter. This WINDOW has a size that corresponds to the size of the panel. For each of the panes in the subsequent chain, a separate WINDOW structure is built with a size that corresponds to the specified presentation space size or the viewport size, whichever is larger. If borders are specified for any of the panes, those borders are drawn on the WINDOW for the panel. All corners are checked and, if needed, proper junction characters are used to draw the corner. The boolf parameter indicates whether to suppress the creation of presentation spaces for the panes. If the value is TRUE, presentation spaces are not created. If FALSE, presentation spaces are created. The ecdfpl routine returns ERR if sufficient storage is not available for the WINDOW structures being created. #include ecdppn (pane, oldwin, newwin) The ecdppn routine adds, drops or replaces a presentation space for a pane. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 13 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) First, if the oldwin parameter is not NULL, then ecdppn drops oldwin from the list of windows that are alternatives for the pane specified by the pane parameter. The previous association should have been established using edadpn. If the oldwin parameter is NULL, then no window is dropped. Next, if the newwin parameter is not NULL, then ecdppn adds newwin as a valid pane for this window, replacing oldwin, if it was associated with the pane specified by the pane parameter. (See ecadpn for a better way to add a pane). The ecdppn routine always returns the value OK. #include ecdspl (panel) The ecdspl routine releases all of the data structures associated with the panel specified by the panel parameter. The released data structures are returned to the free pool. The released data structures include the panel structure, all associated pane structures, any window structures associated with the panes, any auxiliary window structures associated with the panes, and all private control structures used by Extended Curses. #include ecdvpl (panel) The ecdvpl routine assigns a real size and relative position to all the panes defined for the panel specified by the panel parameter. All of the panes must be linked to the panel. The structure of a tree is followed to determine the sizes for each pane. The direction of the first set of divisions and the size of the first set of divisions is determined. This information is used to control the division algorithm. Using the size along the direction of division, first, the total space for the interior of panes is determined by counting the panes and their borders. Next, any panes with fixed size are given the space indicated by the divsz field in the pane structure. The remaining available space is then assigned to the panes that have specified a proportional size. Finally, any space that remains is assigned to those panes that specified a floating size. Once the sizes are determined, the origin for each pane relative to the panel origin is determined and entered into the PANE structure. A final pass is made over the list of panes in the current division, and, for each that is itself divided, the process is repeated. If adjacent panes both have a border specified, the border space is shared between them. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 14 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) If all of the panes have a fixed size and the total is less than the available space, there will be space that cannot be accessed by the application in the resulting structure. If, after allocating space to the proportional panes, there is space remaining and no floating panes are in the current set, the remaining free space is allocated to the proportional panes. The ecdvpl routine returns ERR and the structures are invalid for use by ecdfpl if one or more of the following occur: o The total size specified for fixed panes exceeds the space available. o The total fractions specified for the proportional panes exceed a total of 1. o The number of panes exceeds the number of positions available. #include ecflin (pane, firstline, firstcol, numlines, numcols, pat, xc, buf, mask) NLecflin (pane, firstline, firstcol, numlines, numcols, pat, xc, buf, length, mask) char *pat, *buf, *mask; MBecflin (pane, firstline, firstcol, numline, numcols, xc, buf, length, validcheck, validfunc) int *validfunc; The ecflin, NLecflin, and MBecflin routines input field data to a pane. ecflin is retained to preserve traditional functionality. NLceflin, which supports code set pc850 only, is retained for backward compatibility, and MBecflin is provided for international character set support. NLecflin works like ecflin, but has an additional parameter, length, which specifies the length of the buffer in which the input data is stored. The ecflin routine inputs field data to the pane pointed to by the pane parameter. The firstline and the firstcol parameters specify the upper left corner of the field in the current window being shown in the pane. The numcols parameter specifies the number of columns in the field, and the numlines parameter specifies the number of rows in the field. The buf parameter points to a buffer into which input data is stored. The buffer must be at least numlines * numcols characters long. The xc parameter specifies the first NLSCHAR to be entered into the field. If the xc parameter is a null character, it is ignored. The pat and mask parameters specify the set of characters that are to be accepted as valid input. The position in the field may not always correspond to the position in the input buffer. Input is accepted from the terminal as long as the cursor remains within the bounds of the field. However, if the input Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 15 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) buffer is filled before the cursor exits the field, input processing stops and ecflin returns. Cursor movement that moves the cursor outside the field is allowed and is reflected on the display. If cursor movement places the cursor in a position where data input would cause the input buffer to overflow, input processing stops. Any data keys entered are checked against the character set specified by the pat parameter. If the data character is acceptable, then it is echoed. If the character is not acceptable, then the ecflin routine returns its value. Insert and delete keys are honored and data is shifted within the field as needed. If the field spans more than one line and insertions or deletions are made, then data that is shifted out of one line of the field is shifted into the end of the next line. Data shifted out of the field is lost. When characters are deleted, null characters are shifted into the end of the field. The pat parameter points to a string that indicates the set of characters that is acceptable as valid input. These characters include all code points of the P0 code page (see "display symbols"). The string is formed of these codes: U Uppercase letters: "'A'"-"'Z'" plus the accented uppercase letters from code page P0. L Lowercase letters: "'a'"-"'z'" plus the accented lowercase letters from code page P0. N Numeric characters: "'0'"-"'9'". A Alphanumeric characters: "'A'"-"'Z'", "'a'"-"'z'", and "'0'"-"'9'" plus the accented letters from code pages P0, P1, and P2. B Blank (space character-0x20). P Printable characters: blank-"'^'" (0x20-0x7E). G Graphic characters: "'!'"-"'^'" (0x21-0x7E). X Hexadecimal characters: "'0'"-"'9'", "'A'"-"'F'", and "'a'"-"'f'". C Control Characters: o Cursor Up, Cursor Down, Cursor Left, Cursor Right o Backspace o Back-tab (to first position of field) o Insert (enable or disable insert mode) o Delete (delete current character) o New-line (to left column and down one line) D Default characters: o 0x20-0x7E o 0x80-0xFF o Controls, as defined for code "C". Z Application-specified character set + Allows characters indicated by following codes. - Does not allow characters indicated by following codes. If the first character of pat is "+" or "-", the set of characters specified by the rest of the string is added to ("+") or taken from ("-") the default characters (which can also be specified with "D"). If the Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 16 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) first character in this string is not "+" or "-", then the set of characters specified by pat replaces the default. After the first character, the sets indicated are allowed unless preceded by a "-" (minus sign). For example: "PC-L" Allows the printable and control characters, except for lowercase letters. "-CBN" Allows all of the default characters, except for control characters, blanks, or numeric characters. If the pat string contains a "Z", then the array pointed to by the mask parameter specifies a character validity mask. This array must be exactly 64 bytes long (512 bits), where each bit corresponds to a character code as returned by wgetch. The bytes in the array correspond as follows: Bytes 0-31 P0 characters 0x00-0xFF Bytes 32-63 Keycodes 0x100-0x1FF If a given bit is set to 1, then the corresponding character is accepted (for "+Z") or rejected (for "-Z"). If a bit is set to 0, then the acceptance status of the corresponding character, as determined by the rest of pat, is not changed. Upon successful completion, the code associated with the last input that terminated input is returned. The ecflin routine returns ERR if one or more of the following are true: o There is an error in the parameters. o The firstline parameter is outside the window. o The firstcol parameter is outside the window. o The numcols parameter is too large. o The numlines parameter is too large. The MBecflin routine works like the NLecflin routine, except that it also handles multiple byte and double display width character input. The definitions of the parameters pane, firstline, firstcol, numline, numcols, xc, buf, and length are the same as those described for NLecflin. When validcheck is TRUE, MBecflin calls the routine validfunc (c) where c is the input code, and checks the return value from it. If the return value is TRUE, c is considered valid and processing continues; otherwise, c is considered invalid and processing terminates. When validcheck is FALSE, MBecflin performs a default validity check in which any input data code not defined in the current locale is considered invalid (that is, _mblen returns a value of -1). c may be data code in NLSCHAR (mbchar_t, file code), or keypad code defined in cur02.h. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 17 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) The routine validfunc must be defined by the user for the validity check, and a conversion from file code to wide code might be required in the routine to achieve code independence. When an entered character overwrites half of an existing double display width character, the system replaces the remaining half of that existing character with a blank. If a character is inserted when the cursor is positioned at the second column of a double display width character, the cursor is adjusted to the first column of that character before insertion. A deletion, on the other hand, always deletes a whole character regardless of how many columns it occupies. When a double display width character is entered at the last column of any line but the last line, the character enters the input buffer. On the screen, however, it is replaced by two partial-character indicators (@@), appearing at the last column of the current line, and at the beginning column of the next line respectively. Note that this is only a display-time feature. The original character is still kept as is in the input buffer. For example, during the editing session in the insertion mode, if there are insertions or deletions before that character, the character will be displayed normally whenever it is assigned two consecutive columns. echo ( ) noecho ( ) The echo routine causes the terminal to echo characters to the display. If echo is set on, wgetch places all input into the data structure for the window. The noecho routine turns echo off. If echo is turned off, characters are not written to the display. #include ecpnin (pane, boolf, xc) The ecpnin routine causes the pane to accept keyboard input. The pane specified by the pane parameter is scrolled, if necessary, to ensure that the cursor is visible on the display. Keyboard input is then accepted. If the boolf parameter is TRUE and if the input character is a simple cursor movement, then the resulting cursor position is reflected on the display. Further input is then read from the terminal. If the boolf parameter is FALSE, or if the input character is not a simple cursor movement, then the value of the input character is returned. The xc parameter specifies the first NLSCHAR to be assumed from the display. If xc is a null character, then it is ignored. This routine tracks the locator cursor if locator tracking is enabled (see "trackloc" on page 32). Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 18 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) void ecpnmodf (pane) The ecpnmodf macro marks the panel that contains the pane specified by the pane parameter as modified. This information is used by ecrfpl to determine whether a panel needs to be written to the display. #include ecrfpl (panel) The ecrfpl routine refreshes the panel specified by the panel parameter. If that panel is partially obscured by other panels, then those panels are also written to the display. If the panel parameter is NULL, then all panels that have been marked as modified (with ecpnmodf) are written. If any panels have been removed (with ecrmpl), then all panels are written. #include ecrfpn (pane) The ecrfpn routine refreshes the pane specified by the pane parameter on the display. If the pane is the active pane, then the window might be scrolled to ensure that the cursor is visible. If the pane is not active, then the window is not scrolled. The ecrfpn routine always returns the value OK. #include ecrlpl (panel) The ecrlpl routine returns the structures associated with the panel specified by the panel parameter to the free storage pool. This includes all window structures associated with the panes of the panel, all Extended Curses private structures, and any added window structures. The panel and associated pane structures are not released and can be reused. The ecrlpl routine always returns the value OK. #include ecrmpl (panel) The ecrmpl routine removes the panel specified by the panel parameter from the list of panels that are currently being displayed. If the panel is not currently in that list, no action is taken and no error is returned. This routine should be followed by a call to ecrfpl to update the display. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 19 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) The ecrmpl routine always returns the value OK. #include ecscpn (pane, numlines, numcols) The ecscpn routine causes the pane specified by the pane parameter to be scrolled over the underlying window the distance indicated by the numcols and the numlines parameters. The numcols parameter specifies the distance to scroll horizontally and the numlines parameter specifies the distance to scroll vertically. These parameters can be positive or negative and may imply a movement that positions the viewport partially or completely off the window. If such a position results from the scroll, the scroll stops after moving as far in the indicated direction as possible. Positive values move to the right or down. Negative values move to the left or up. If there are other panes linked to the pane specified, those panes will also scroll an amount necessary to maintain the identical horizontal or vertical positioning on the respective windows. If the resulting position requires placing the viewport partially or completely off the window, the scroll request terminates at the edge of the window. #include ecshpl (panel) The ecshpl routine shows the panel specified by the panel parameter on the terminal. If the specified panel is currently the top panel, no action is taken and no error is returned. If there is another top panel, the active pane in that panel is changed to the inactive state. The specified panel is placed at the top of the panel chain. This routine should be followed by a call to ecrfpl to update the display. The ecshpl routine always returns the value OK. #include ectitl (title, line, col) char *title; The ectitl routine creates or modifies the title panel. The title panel is always visible, that is, on top of any other panels. The title parameter points to a character string that is displayed as the new title. If title is NULL, then any existing title is removed. The line and col parameters specify the coordinates for the upper left corner of the title panel. If firstline is not valid, then it defaults to 1. If firstcol is not valid, then the title will be centered. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 20 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) endwin ( ) The endwin routine ends window routines before exiting. Ending window routines before exiting restores the terminal to the state it was before initscr (or gettmode and setterm) was called. endwin should always be called before exiting. endwin does not exit. erase ( ) werase (win) perase (pane) The erase routine clears the window and sets it to blanks without setting the clear flag. Similarly, werase erases the window specified by the win parameter, and perase erases the pane specified by the pane parameter. This is analogous to the clear routine, except that it does not cause a clear-screen sequence to be generated on a refresh. extended (boolf) The extended routine turns on and off the combining of input bytes into multibyte extended characters. If the boolf parameter is TRUE, then this input processing is turned on; if FALSE, then it is turned off. By default, extended processing is initially turned on. flash ( ) The flash routine displays a visual bell on the terminal screen if one is available. If a visual bell is not available, then flash toggles the terminal speaker or bell. The flash routine always returns the value OK. fullbox (win, vert, hor, topl, topr, botl, botr) NLSCHAR vert, hor, topl, topr, botl, botr; The fullbox routine puts box characters on the edges of the window. The vert parameter specifies the NLSCHAR to use for the vertical sides. The hor parameter specifies the NLSCHAR to use for the horizontal lines. The topl and the topr parameters specify the NLSCHARs to use for the top left and the top right corners. The botl and the botr parameters specify the NLSCHARs to use for the bottom left and the bottom right corners. The fullbox routine returns ERR if an attempt is made to scroll when scrollok is not active. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 21 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) The fullbox routine does not accept double display width characters. If a double width character is used, the fullbox routine substitutes a single display character and draws the box. The system returns ERR. The fullbox routine is a macro that invokes superbox. #include NLSCHAR getch ( ) NLSCHAR wgetch (win) NLSCHAR mvgetch (line, col) NLSCHAR mvwgetch (win, line, col) The getch routine gets a character from the terminal and echoes it on the window, if necessary. If noecho has been set, then the window does not change. noecho and either crmode or raw must be set for Extended Curses to know what is actually on the terminal. If these settings are not correct, wgetch sets noecho and crmode and resets them to the original mode when done. Upon completion, the NLSCHAR for the data key or one of the following values is returned: KEY_NOKEY nodelay is active and no data is available. KEY_xxxx keypad is active and a control key was recognized. See the cur02.h header file for a complete list of the key codes that can be returned. ERR Echoing the character would cause the screen to scroll illegally. #include NLSCHAR getstr (string) NLSCHAR wgetstr (win, string) NLSCHAR mvgetstr (line, col, string) NLSCHAR mvwgetstr (win, line, col, string) The getstr routine gets a string through the window and stores it in the location pointed to by the string parameter. The string may contain single-shift control codes. The area pointed to must be large enough to hold the string. getstr calls wgetch to get the characters until a new-line character or some other control character is encountered. Upon completion, one of the following values is returned: OK The input string was terminated with a new-line character. KEY_NOKEY nodelay is active and no data is available. KEY_xxxx The input string ended with a control key, and the code for this key was returned. See the cur02.h header file for a complete list of the key codes that can be returned. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 22 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) ERR The string caused the screen to scroll illegally. gettmode ( ) The gettmode routine issues the needed control operation to the display device driver to save the processing flags in a fixed global area. gettmode is invoked by initscr and is not normally called directly by applications. getyx (win, line, col) The getyx routine stores the current (line, col) coordinates of window specified by the win parameter into the variables line and col. Because getyx is a macro and not a subroutine, the names of line and col are passed, rather than their addresses. Upon successful completion, line and col contain the current row and column coordinates for the cursor in the specified window. NLSCHAR inch ( ) NLSCHAR winch (win) NLSCHAR mvinch (line, col) NLSCHAR mvwinch (win, line, col) The inch routine returns the NLSCHAR at the current (line, col) coordinates on the specified window. No changes are made to the window. Upon successful completion, the code for the character located at the current cursor location is returned. WINDOW *initscr ( ) The initscr routine performs screen initialization. initscr must be called before any of the screen routines are used. It initializes the terminal-type data, and without it, none of the Extended Curses routines can operate properly. If standard input is not a tty, initscr sets the specifications to the terminal whose name is pointed to by Def_term (initially "dumb"). If the value of the bool global variable My_term is TRUE, Def_term is always used. If standard input is a terminal, the specifications for the terminal named in the environment variable TERM are used. These specifications are obtained from the terminfo description file for that terminal. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 23 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) The initscr routine creates the structures for stdscr and curscr and saves the pointers to those structures in global variables with the corresponding names. Upon successful completion, a pointer to stdscr is returned. insch (xc) winsch (win, xc) mvwinsch (win, line, col, xc) mvinsch (line, col, xc) The insch routine inserts the NLSCHAR specified by the xc parameter into the window at the current (line, col) coordinates. Each character after the inserted character shifts to the right and the last byte on the line disappears. If the current position is at the second column of a double display width character, the position is moved left to the first byte of that character before the specified NLSCHAR is inserted. If a double display width character is inserted at the last column of the window, nothing is done and ERR is returned; otherwise the insch routine always returns the value OK. insertln ( ) winsertln (win) The insertln routine inserts a line above the current line. Each line below the current line is shifted down, and the bottom line disappears. The current line becomes blank and the current (line, col) coordinates remain unchanged. The insertln routine always returns the value OK. keypad (boolf) The keypad routine turns on and off the mapping of key sequences to single integers. If the boolf parameter is TRUE, input processing is turned on. If the boolf parameter is FALSE, input processing is turned off. By default, input processing is initially turned off. When turned on, sequences of characters from the terminal are translated into integers that are defined in the cur02.h header file. The codes available on a given terminal are determined by the terminfo terminal description file. The keypad routine always returns the value OK. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 24 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) leaveok (win, boolf) The leaveok routine sets a flag, used by the window specified by the win parameter, which controls where the cursor is placed after the window is refreshed. If the boolf parameter is TRUE, when the window is refreshed, the cursor is left at the last point where a change was made on the terminal, and the current (line, col) coordinates for the window specified by the win parameter are changed accordingly. If the (line, col) coordinates are outside the window, the coordinates are forced to (0, 0). If the boolf parameter is FALSE, when the window is refreshed, the cursor is moved to the current (line, col) coordinates within the window. The controlling flag is initially set to FALSE. The leaveok routine always returns the value OK. char *longname ( ) The longname routine returns a pointer to a static area that contains the long (full) name of the terminal as it appears in the terminfo entry for the terminal. meta ( ) nometa ( ) The meta routine prevents the stripping of the eighth bit of each keyed character. The nometa routine causes the eighth or most-significant bit of each keyed character to be stripped. Not all terminals support the stripping of bits. The meta and nometa routines always return the value OK. move (line, col) wmove (win, line, col) The move routine changes the current (line, col) coordinates of the window to the coordinates specified by the line and col parameters. The move routine returns ERR if the destination for the cursor is outside the window or viewport. mvcur (line, col, newline, newcol) int line, col, newline, newcol; The mvcur routine moves the terminal's cursor from the coordinates specified by the line and col parameters to the coordinates specified by Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 25 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) the newline and newcol parameters. The line and col parameters must specify the current coordinates. It is possible to use this optimization without the benefit of the screen routines. In fact, mvcur should not be used with the screen routines. Use move and refresh to move the cursor position and inform the screen routines of the move. mvwin (win, line, col) The mvwin routine moves the position of the viewport or the subwindow specified by the win parameter from its current starting coordinates to the coordinates specified by the line and col parameters. The line parameter specifies the row on the display for the top row of the window. The col parameter specifies the column on the display for the first column of the window. The mvwin routine returns ERR if a part of the window position is outside the bounds of the window on which the viewport is defined. WINDOW *newview (win, numlines, numcols) The newview routine creates a new window that has the number of lines specified by the numlines parameter and the number of columns specified by the numcols parameter. The new window is a viewport of the window specified by the win parameter and starts at the current (line, col) coordinates of the window specified by the win parameter. The resulting window's initial position on the display is set to (0, 0). The viewport window returned by newview is a special subwindow that is suitable for viewport scrolling. Viewport scrolling here refers to the type of scrolling that is characteristic of full-screen editors. Because the returned viewport window is a subwindow, any change made in either window in the area covered by the viewport window appears in both windows. Both windows actually share the relevant storage area. A viewport window cannot be scrolled using scroll. Other than the exceptions noted above, viewport windows behave like subwindows. Upon successful completion, a pointer to the control structure for the new viewport is returned. The newview routine returns ERR if the window specified by the win parameter is a subwindow or a viewport, or if sufficient storage is not available for the new structures. WINDOW *newwin (numlines, numcols, firstline, firstcol) Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 26 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) The newwin routine creates a new window that contains the number of lines specified by the numlines parameter and the number of columns specified by the numcols parameter. The new window starts at the coordinates specified by the firstline and the firstcol parameters. If the numlines parameter is 0, that dimension is set to (LINES - firstline). If the numcols parameter is 0, that dimension is set to (COLS - firstcol). Therefore, to get a new window of dimensions (LINES * COLS), use: newwin (0, 0, 0, 0) The size specified for the window can exceed the size of the real display. In this case, a viewport or subwindow must be used to present the data from the window on the terminal. Upon successful completion, a pointer to the new window structure is returned. The newwin routine returns ERR if any of the parameters are invalid, or if there is insufficient storage available for the new structure. nl ( ) nonl ( ) The nl routine sets the terminal to nl mode. When in nl mode, the system maps "'\r'" (return characters) to "'\n'" (new-line or line-feed characters). If the mapping is not done, refresh can do more optimization. nonl turns nl mode off. The nl routine and nonl do not affect the way in which waddch processes new-line characters. The nl and nonl routines always return the value OK. nodelay (boolf) The nodelay routine controls whether read requests wait for input if no keystroke is available. If the boolf parameter is FALSE, then the read routines wait for operator input. This is the default setting. If the boolf parameter is TRUE, then the read routines return immediately if no keyboard data is available. If nodelay is set (TRUE) and if no keystroke is available from the keyboard, then getch returns KEY_NOKEY, which is defined in the cur02.h header file. The nodelay routine always returns the value OK. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 27 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) overlay (win1, win2) The overlay routine overlays the window specified by the win1 parameter on the window specified by the win2 parameter. The contents of the window specified by the win1 parameter, insofar as they fit, are placed on the window specified by the win2 parameter at their starting (line, col) coordinates. This is done nondestructively; that is, blanks on the win1 window leave the contents of the space on the win2 window untouched. The overlay routine moves data only if the data is nonblank or if the display attribute is different. The only data that is considered for moving from the win1 window to the win2 window is data that occupies display positions that are common to both windows. The overlay routine is implemented as a macro that invokes overput, which uses waddch to transfer the data from window to window. The overlay routine returns ERR if an attempt is made to write to the lower right corner of the display and scrollok is FALSE. overwrite (win1, win2) The overwrite routine copies data from the window specified by the win1 parameter to the window specified by the win2 parameter. The contents of the win1 window, insofar as they fit, are placed on the win2 window at their starting (line, col) coordinates. This is done destructively; that is, blanks on the win1 window become blanks on the win2 window. Only the data that occupies positions on the display that are common to the two windows is moved from the win1 window to the win2 window. The overwrite routine is implemented as a macro that invokes overput which uses waddch to transfer the data from window to window. The overwrite routine returns ERR if an attempt is made to write to the lower right corner and scrollok is FALSE. printw (fmt [, value,...]) wprintw (win, fmt [, value,...]) char *fmt; The printw routine performs a printf on the window using the format control string specified by the fmt parameter and the values specified by the value parameters. The output to the window starts at the current (line, col) coordinates. Use the field width options of printf to avoid leaving things on the window from earlier calls. See "printf, fprintf, sprintf, NLprintf, NLfprintf, NLsprintf, wsprintf" for details. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 28 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) The printw routine returns ERR if it causes the screen to scroll illegally. raw ( ) noraw ( ) The raw routine sets the terminal to raw mode. In raw mode, canonical processing by the device driver and signal processing are turned off. The noraw routine turns off raw mode. The raw and noraw routines always return the value OK. refresh ( ) wrefresh (win) The refresh routine synchronizes the terminal screen with the window. If the window is not a screen, then only the part of the display covered by it is updated. refresh checks for possible scroll errors at display time. The refresh routine returns ERR if the change specified is in the last position of a window that includes the lower right corner of the display, or if it would cause the screen to scroll illegally. If it would cause the screen to scroll illegally, refresh updates whatever can be updated without causing the scroll. resetty (boolf) The resetty routine restores the terminal status flags that were previously saved by savetty. If the boolf parameter is TRUE, then the screen is cleared in addition to resetting the terminal. resetty is performed automatically by endwin and is not normally called directly by applications. savetty ( ) The savetty routine saves the current terminal status flags. savetty is performed automatically by initscr and is not normally called directly by applications. scanw (fmt [, pointer,...]) wscanw (win, fmt [, pointer,...]) char *fmt; The scanw routine performs a scanf through the window using the format control string specified by the fmt parameter. scanw uses wgetstr to Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 29 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) obtain the string, then invokes the internal routine for scanf to process the data. See "scanf, fscanf, sscanf, NLscanf, NLfscanf, NLsscanf, wsscanf" for details. scroll (win) The scroll routine moves the data in the window specified by the win parameter up one line and inserts a new blank line at the bottom. scrollok (win, boolf) The scrollok routine sets the scroll flag for the window specified by the win parameter. If the boolf parameter is TRUE, then scrolling is allowed. The default setting is FALSE, which prevents scrolling. sel_attr (set) int *set; The sel_attr routine allows you to change the selection and priority of attributes for the run-time terminal. The set parameter points to a null-terminated integer array that contains display attribute values from the cur03.h header file in the order that you want them regardless of whether or not they are available on the terminal. Groups of attributes (colors and fonts) cannot be split in the array. For instance, all foreground colors specified must be in adjacent locations in the array. The first element of a group of attributes must be the default color or font of the terminal. For example, the first foreground color specified is usually F_WHITE, and the first background color specified is usually B_BLACK. It is recommended that sel_attr only be called before initscr. If sel_attr is called after initscr, then the routine setup_attr should be called after calling sel_attr. If sel_attr is called after data has been added to a window, the values in the associated attribute array for that window may denote different attributes than the original attributes used when displaying the data (except NORMAL which remains constant). A subsequent refresh of the window shows the different attributes only if the data has been modified or if a total refresh has been forced by a previous call to touchwin. The sel_attr routine always returns the value OK. setterm (name) char *name; Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 30 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) The setterm routine sets the terminal characteristics to be those of the terminal specified by the name parameter. setterm is called by initscr so you do not normally have to use it unless you wish to use just the cursor motion optimizations. setup_attr () The setup_attr routine creates the display attribute masks assigned to the attribute variables declared in the cur01.h header file. The priorities of the attributes determine how the masks are created. This routine is called by initscr and is not normally called by applications. This routine should only be called following a call to sel_attr which follows a call to initscr. standend ( ) wstandend (win) The standend routine stops displaying characters in standout mode. standout ( ) wstandout (win) The standout routine starts displaying characters in standout mode. Any characters added to the window are put in standout mode on the terminal if the terminal has that capability. The first available attribute as determined by sel_attr is used for standout. This is normally the reverse attribute when the default display attribute priority is used. The standout routine always returns the value OK. WINDOW *subwin (win, numlines, numcols, firstline, firstcol) The subwin routine creates a subwindow in the window pointed to by the win parameter. The subwindow has the number of lines specified by the numlines parameter and the number of columns specified by the numcols parameter. The new subwindow starts at the coordinates specified by the firstline and the firstcol parameters. Any change made to the window or the subwindow in the area covered by the subwindow is made to both windows. The firstline and firstcol parameters are specified relative to the overall screen, not to the relative (0, 0) of the window specified by the win parameter. If the numlines parameter is 0, then the lines dimension is set to (LINES - firstline). If the numcols parameter is 0, then the column dimension is set to (COLS - firstcol). Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 31 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) Upon successful completion, a pointer to the control structure for the new subwindow is returned. The subwin routine returns ERR if the window specified by the win parameter already has a subwindow, or if there is insufficient storage for the new control structure. superbox (win, line, col, numlines, numcols, System V, hor, topl, topr, botl, botr) NLSCHAR System V, hor, topl, topr, botl, botr; The superbox routine draws a box on the window specified by the win parameter. The line and col parameters specify the starting coordinates for the box. The numlines parameter specifies the depth of the box. The numcols parameter specifies the width of the box. The System V parameter specifies the NLSCHAR to use for vertical delimiting. The hor parameter specifies the NLSCHAR to use for horizontal delimiting. The topl, topr, botl, and botr parameters specify the NLSCHARs to use for the top left corner, the top right corner, the bottom left corner, and the bottom right corner, respectively. If the window specified by the win parameter is a _SCROLLWIN window and scrolling is not allowed, then the bottom right corner is not put on the window. The superbox routine uses addch to place the characters on the window. The superbox routine returns ERR if the defined box is outside the window, or an attempt is made to write to the lower right corner of the display when scrollok is off. touchwin (win) The touchwin routine makes it appear as if every location on the window specified by the win parameter has been changed. This is useful when overlapping windows are to be refreshed. A subsequent refresh request considers all portions of the window as potentially modified. If touchwin is not used, then only those positions of the window that have been addressed by an addch are inspected. trackloc (boolf) The trackloc routine turns on and off the tracking of the locator cursor on the screen. If the boolf parameter is TRUE, then locator tracking is turned on; if FALSE, then it is turned off. By default, locator tracking is initially turned on. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 32 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) The keycode KEY_LOCESC is returned from getch when a locator report is input. The locator report is stored in the global char array ESCSTR, which is 128 bytes long. Locator tracking is handled by the ecpnin routine. tstp ( ) The tstp routine saves the current tty state and then put the process to sleep. When the process is restarted, the tty state is restored and then wrefresh (curscr) is called to redraw the screen. initscr sets the signal SIGTSTP to trap tstp. The tstp routine always returns the value OK. #include char *unctrl (ch) The unctrl routine returns a string that represents the value of the ch parameter. Control characters become the lowercase equivalents preceded by a "^" (circumflex). Other letters are unchanged. This function supports only the P0 characters 0x00 through 0x7F. Upon successful completion, a pointer to the string for the parameter character is returned. vscroll (win, numlines, numcols) The vscroll routine scrolls the viewport specified by the win parameter on the window. The numlines parameter specifies the direction and amount to scroll up or down. If the numlines parameter is positive, the viewport scrolls down the number of lines specified. If the numlines parameter is negative, the viewport scrolls up the number of lines specified. The numcols parameter specifies the direction and amount to scroll left or right. If the numcols parameter is positive, the viewport scrolls to the right the number of characters specified. If the numcols parameter is negative, then the viewport scrolls to the left the number of characters specified. The vscroll routine always scrolls as much of a requested scroll as possible. Specifying a parameter with a magnitude larger than that of the underlying window is not an error. The vscroll routine calls touchwin if any scrolling is done. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 33 EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L) The vscroll routine returns ERR if the window specified by the win parameter is not a window created by a call to newview. FILE /usr/lib/terminfo/?/* Compiled terminal capability data base. RELATED INFORMATION In this book: "curses" and "terminfo." The discussion of Extended Curses in AIX Programming Tools and Interfaces. "Introduction to International Character Support" in Managing the AIX Operating System. AIX Guide to Multibyte Character Set (MBCS) Support. Processed July 12, 1991 EXTENDED CURSES LIBRARY(3x,L) 34